Re: [Qemu-devel] [PATCH v2] qemu-doc: Rework the network options chapter to make "-net" less prominent

[Markus Armbruster]

Eric Blake <address@hidden> writes:

> On 03/12/2018 04:07 AM, Paolo Bonzini wrote:
>> On 12/03/2018 08:27, Thomas Huth wrote:
>>> "-net" is clearly a legacy option. Yet we still use it in almost all
>>> examples in the qemu documentation, and many other spots in the network
>>> chapter. We should make it less prominent that users are not lured into
>>> using it so often anymore. So instead of starting the network chapter with
>>> "-net nic" and documenting "-net <backend>" below "-netdev <backend>"
>>> everywhere, all the "-net" related documentation is now moved to the end
>>> of the chapter. The new "--nic" option is moved to the beginning of the
>>> chapter instead, with a new example that should demonstrate how "--nic"
>>> can be used to shortcut "--device" with "--netdev". The examples in this
>>> chapter are changed to use the "--device" and "--netdev" options or
>>> "--nic" instead of "-net nic -net <backend>".
>>>
>>> While we're at it, also remove a legacy remark about very old Linux
>>> distributions. Also remove the "[...]" from the examples in this chapter
>>> since we are not using this ellipsis in any other examples in our docu-
>>> mentation.
>>>
>>> Signed-off-by: Thomas Huth <address@hidden>
>>> ---
>>>   v2:
>>>   - Fixed the bad "--device=e1000" example
>>
>> Frankly I think this is the proof that double-dash option names are a
>> bad idea.  The reason to do that was to make qemu-img and qemu command
>> lines more similar in the documentation, but the truth is they are not
>> similar and shouldn't be made similar.  The equal sign is one example,
>> where qemu-img supports "--format=raw" but QEMU doesn't support
>> "--device=e1000", but it's not the only one.
>
> Our hand-rolled parser sucks.  We should fix it to be more like
> getopt, at which point --device=e1000 would work.
>
>>
>> qemu-img supports things such as "-fraw", qemu doesn't---for example
>> "-m1024" doesn't work).
>
> Our hand-rolled parser sucks.  We should fix it to be more like
> getopt, at which point -m1024 would work.
>
>>  qemu-img can combine single-letter options
>> (e.g. "qemu-img convert -pc") but qemu cannot---e.g. "-sm" doesn't
>> combine "-s" and "-m".
>
> That's a legitimate difference between getopt_long() and
> getopt_long_only() - but to some extent, even getopt_long_only() can
> bundle unambiguous short options correctly.  Again, fixing our
> hand-rolled parser to use getopt_long_only() might make this better.
>
>> No need to drop them in QEMU, since it's more or less just a convenience
>> for people that are used to double-dash long options, but using them in
>> the documentation is confusing.
>
> For -object vs. --object (which IS used identically between qemu-img
> and qemu proper), we really do want to favor a common spelling (which
> perhaps means we need to first fix our hand-rolled parser to not suck
> so much - possibly by rewriting it to use getopt_long_only()).  For
> options like -nic vs. --nic, which have no (current) counterpart in
> qemu-img, it's a harder sell (as you continue to argue), but Dan's
> original suggestion to prefer double-dash in the documentation was
> because consistency helps (and if that means improving our parser to
> behave more consistently, that's a good thing).

For what it's worth, my "[RFC PATCH 00/32] Command line QAPIfication"
replaces the original parsing art by getopt_long_only().

Completing that work will take some time, but once it's done, we can
(and I think we should) prefer double-dash for consistency.