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

[Daniel P . Berrangé]

On Tue, Apr 17, 2018 at 03:56:25PM +0200, Markus Armbruster wrote:
> Eric Blake <address@hidden> 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 <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.
> >
> >>
> >> 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 :|