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

[Eric Blake]

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

--
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org