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 <th...@redhat.com> >>>> --- >>>> 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