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

[Thomas Huth]

On 12.03.2018 13:44, Paolo Bonzini wrote:
> 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"?

Slightly off-topic, but: I think it is also quite unfortunate that we
use a short option "-d" for something that you need rather seldomly,
while something important like "-device" does not have an abbreviated
one-letter alternative.

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

Hey, what about switching to getopt_long(), breaking with traditions and
call the first version that contains the change "QEMU v3.0"? ;-)
... SCNR.

 Thomas