Eric Blake <ebl...@redhat.com> 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 <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. > >> >> 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.
