[libvirt] [PATCH] virsh man page - domain-id consistency

[Eric Blake]

On 07/18/2012 10:03 AM, Jan Tomko wrote:
> Using 'domain-id' to represent domain name, domain id or uuid,
> as introduced in the DOMAIN COMMANDS section.
> ---
>  tools/virsh.pod |   86 +++++++++++++++++++++++++++---------------------------
>  1 files changed, 43 insertions(+), 43 deletions(-)
> 
> diff --git a/tools/virsh.pod b/tools/virsh.pod
> index 4bddf15..ed1efde 100644
> --- a/tools/virsh.pod
> +++ b/tools/virsh.pod
> @@ -580,11 +580,11 @@ If I<--graceful> is specified, don't resort to extreme measures
>  (e.g. SIGKILL) when the guest doesn't stop after a reasonable timeout;
>  return an error instead.
>  
> -=item B<domblkstat> I<domain> I<block-device> [I<--human>]
> +=item B<domblkstat> I<domain-id> I<block-device> [I<--human>]

Hmm.  'virsh help domblkstat' says that the option is spelled --domain,
using the meta-notation '[--domain] <string>'.  That is, these commands
are equivalent:

virsh domblkstat mydom mydev
virsh domblkstat --domain=mydom mydev
virsh domblkstat --domain mydom mydev

Our quasi-convention in 'man virsh' has been that if there is a required
option, it is easier to name that option according to its optional --foo
lead-in (that is, writing 'I<domain>' is shorter than writing
'[I<--domain>] B<domain-id>').

But by making 'man virsh' list I<domain-id>, which does not match the
name of the optional --domain lead-in, we are not following this
convention.  I think I'd rather keep I<domain> in the synopsis, then
alter the explanatory text to point back to our earlier description of a
valid domain id:

>  
>  Get device block stats for a running domain.

Get device block stats for the domain-id I<domain>.

where there term 'domain-id' implies 'domain nam, id, or uuid'.

Another option might be adding virsh option aliases, so that:

virsh domblkstat --domain-id=mydom mydev
virsh domblkstat --domain=mydom mydev

become equivalent, and where virsh would then match your proposed 'man
virsh' naming with --domain-id being the canonical option name but the
shorter --domain still working.

Hmm, if we would ever implement unambiguous-abbreviation option parsing,
then --domain is an unambiguous prefix of --domain-id.  In that case, we
don't even need option aliasing; we would just fix virsh.c to use the
longer option name everywhere, and scripts using the shorter option name
would still just work, and then your more-descriptive man page would
line up with the C code.

That said, if others like this patch, I'm not opposed to taking it as
is.  Take this as a weak ACK.

-- 
Eric Blake   eblake at redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 620 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20120718/c2b0d4a1/attachment-0001.sig>