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

[Eric Blake]

On 03/09/2018 11:41 AM, Thomas Huth wrote:
> On 09.03.2018 15:36, Eric Blake wrote:
> > On 03/09/2018 12:13 AM, 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".
> > > And the examples in this chapter are changed to use the "--device" and
> > > "--netdev" options or "--nic" instead of "-net nic -net <backend>".

> > > address@hidden
> > > +qemu-system-i386 --netdev user,id=n1,ipv6=off
> > > --device=e1000,netdev=n1,mac=52:54:98:76:54:32
> > > +qemu-system-i386 --nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
> > > address@hidden example
> >
> > Nice example.
>
> ... but looks like I even got it wrong - it should be "--device e1000",
> without "=". Will fix it.

Really?  As I understand it, both long-opt spellings work ('--long=opt' 
as one arg, and '--long' 'opt' as two args).  So the only reason to drop 
'=' would be consistency with other examples.

> > > @@ -2166,8 +2166,6 @@ or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS}
> > > (Windows NT/2000).
> > >    Then @address@hidden can be accessed in @file{\\smbserver\qemu}.
> > >      Note that a SAMBA server must be installed on the host OS.
> > > -QEMU was tested successfully with smbd versions from Red Hat 9,
> > > -Fedora Core 3 and OpenSUSE 11.x.
> > >    
> >
> > This change makes sense, but is somewhat unrelated to -net.  Worth
> > splitting the patch?
>
> Not sure whether it's really worth the effort ... I think I'll just
> mention it in the patch description, ok?

Yes, if you don't split, at least mention it (if a reviewer questioned 
it in an earlier revision, then an improved commit message serves as the 
preemptive reason for the next person looking at the next revision).


> > > -qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
> > > +qemu-system-i386 --nic user,hostfwd=tcp:127.0.0.1:6001-:6000
> >
> > The trailing [...] makes sense here, why did you drop it?
>
> Since we're incredibly inconsistent with that. Some examples do have
> that "[...]", many others don't have it. Since the amount of examples
> without it is larger than the amount of examples with it, I think it's
> more consistent to drop it here.
>
> I guess I should mention this in the commit message, too.

Yes, mention that it's intentional, and I'll go along with it.

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