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

[Paolo Bonzini]

On 12/03/2018 13:18, Eric Blake wrote:
> 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.

"--device=e1000,netdev=user0" is also pretty confusing, as is
"--machine=kernel_irqchip=off".

>> 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.

For -m1024 it makes sense, but what about -d?  How do you explain that
"-din_asm" is a short form of "-d in_asm", but "-device" is not a short
form of "-d evice"?

I agree that having a non-standard option parser is bad, but
getopt_long_only always seemed to me like the worst of both worlds.
"All options are 'long', cannot be abbreviated, must be separated from
their argument" is pretty easy.

All that matters for "-object" and "--object", I'd argue, is that the
syntax of the key-value list is the same for the two (and also the same
for the object_add HMP command).  Whether to spell it with one or two
dashes should not be an issue; we could perhaps take a hint for git's
"commit -amend" behavior and print a special error message if the user
writes "qemu-img -object" with one dash.

   $ qemu-img convert -object ~/chipsec.img bar
   qemu-img: Invalid parameter 'bject'

Instead it could be something like:

   $ qemu-img convert -object ~/chipsec.img bar
   qemu-img: did you mean '--object' (with two dashes)?

Thanks,

> 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).