[libvirt] [PATCH] docs: Clarify interface/target/@dev docs

[Jiri Denemark]

On Tue, Mar 01, 2016 at 16:07:18 +0100, Martin Kletzander wrote:
> On Tue, Mar 01, 2016 at 12:51:53PM +0100, Jiri Denemark wrote:
> >https://bugzilla.redhat.com/show_bug.cgi?id=1313314
> >
> >Signed-off-by: Jiri Denemark <jdenemar at redhat.com>
> >---
> > docs/formatdomain.html.in | 4 ++--
> > 1 file changed, 2 insertions(+), 2 deletions(-)
> >
> >diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
> >index c54b308..df8c06c 100644
> >--- a/docs/formatdomain.html.in
> >+++ b/docs/formatdomain.html.in
> >@@ -4507,10 +4507,10 @@ qemu-kvm -net nic,model=? /dev/null
> >     <p>
> >       If no target is specified, certain hypervisors will
> >       automatically generate a name for the created tun device. This
> >-      name can be manually specified, however the name <i>must not
> >+      name can be manually specified, however the name <i>should not
> >       start with either 'vnet' or 'vif'</i>, which are prefixes
> >       reserved by libvirt and certain hypervisors. Manually specified
> >-      targets using these prefixes will be ignored.
> >+      targets using these prefixes may be ignored.
> >     </p>
> >
> 
> That sounds very arbitrary, could we instead say that 'vnet' will be
> ignored and libxl will also ignore 'vif'?  I know it bounds us to that,
> but when would we change that in the future and why?  Also the wording
> htat's there right now seems quite fine.  Maybe we could say vnet will
> be ignored as well as some other per-hypervisor prefixes and the user is
> advised to check what the result is.
> 
> Or we can just go the nicest way nad say that 'vnet' prefix will be
> ignored as well as the host's prefix which can be obtained in host
> capabilities.  That's as precise as you can get and we'll conform to
> that even if some new hypervisor chooses some new prefix to go with.

Hmm, I saw Pavel's ACK earlier than your email and already pushed this
patch. Anyway, I think it's good enough, users should not need to know
how exactly this works. Telling them to avoid several specific prefixes
(which may be used by libvirt) is simple and clear. Anyone who cares
about setting their own target names can just safely use a name which
doesn't conflict with libvirt.

Jirka