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

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.

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. -- libvir-list mailing list libvir-list(a)redhat.com https://www.redhat.com/mailman/listinfo/libvir-list