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

[Thomas Huth]

On 12.03.2018 10:07, 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.
> 
> 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".

I guess we could work on most of these issues ... but until we're there,
you're maybe right and we should not switch to double dash options in
the documentation yet. I'll send a v3 without double dashes...

 Thomas