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

[Paolo Bonzini]

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.

qemu-img supports things such as "-fraw", qemu doesn't---for example
"-m1024" doesn't 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".

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.

Paolo

>  - Fixed some typos discovered by Eric
>  - Use --nic in even more examples (Paolo)
>  - Improved patch description
>  - Use single dash only in @findex tags (the appendix with the index looks
>    strange otherwise)