Re: [Qemu-devel] [PATCH v2 8/8] qemu-doc: Make "-net" less prominent

[Thomas Huth]

On 20.02.2018 19:37, Paolo Bonzini wrote:
> On 20/02/2018 18:40, 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. And the examples are changed to use the "--device" and
>> "--netdev" options instead of "-net nic -net <backend>".
> 
> Do we want to change them to "-nic" instead?  The proof is in the
> pudding, they say, :) and "-nic" is way easier to learn than "-device
> -netdev".

While -nic is easier to use than -netdev, I don't think that we should
put the focus in our main qemu-doc on -nic instead of -netdev. -nic is a
convenience option, while -netdev is the "architected" way to configure
network devices. We first should document how to do it "right", and
teach the user to proper distinguish between emulated guest hardware and
host network backend (with the old -net command, a lot of people seemed
to have mixed that up IIRC), and then finally explain -nic on top of it.

> And maybe we *should* go the extra mile and deprecate "-net" altogether.
>  The only case where the newer syntax is a bit more uncomfortable is for
> "-net nic -net nic -net tap|user", which however does work with "-nic
> hubport -nic hubport -netdev tap|user,id=x -netdev hubport,netdev=x".

I'd be glad to add such a deprecation patch to this series - I just
thought it might have been too early so far, but if you feel confident
that we can mark it as deprecated, I can spin a v3 with such a patch on
top...

 Thomas