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

Osier Yang jyang at redhat.com
Fri Jul 20 04:23:02 UTC 2012


On 2012年07月19日 00:29, Eric Blake wrote:
> 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:
</...
Agreed. "--domain-id" could be confused with "domain id" easily, it
could fall into a another trap. IMO the right way is to clarify
I<domain> can be "domain name", "domain id", or "domain uuid" somewhere
in the manual. It's similiar for other command groups like network,
pool, etc.

>
>>
>>   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 at redhat.com
> https://www.redhat.com/mailman/listinfo/libvir-list




More information about the libvir-list mailing list