On Tue, Apr 17, 2018 at 03:56:25PM +0200, Markus Armbruster wrote: > 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.
Since our existing parser accepts single & double-dash already, is it worth explicitly deprecating single-dash usage right now. So that when your code comes along ready to merge, we're already able to say "i told you so" and drop single-dash support at that same time. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
