[libvirt] consistency of virsh help output

Eric Blake eblake at redhat.com
Thu Feb 3 18:05:01 UTC 2011


On 02/03/2011 02:31 AM, Zdenek Styblik wrote:
> Hello,
> 
> I've found virsh help output to be inconsistent.
> 
> ~~~ SNIP ~~~
> attach-disk <domain> <source> <target> [--driver <string>]...
> 
> X
> 
> attach-interface <domain> <type> <source> [<target>] ...
> ~~~ SNIP ~~~
> 
> where <KEYWORD> is usually explained in OPTIONS as:
> ~~~ SNIP ~~~
> [--domain] <string>  domain name, id or uuid
> ~~~ SNIP ~~~

While I agree that a patch to make things more consistent is probably
worthwhile, I was unclear from your report on which way you thought
things should be changed.  In this case, patches speak louder than words :)

Did you have in mind changing the synopsis to match the options?

attach-disk [--domain] <string> [--source] <string> [--target] <string>
[--driver <string>]

or were you thinking of making the synopsis even more compact?

attach-disk <domain> <source> <target> [<driver>]

or are you thinking of changing the layout in options?  Remember, the
goal is to convey which parameters are required (but which can still be
specified out of order by using the optional --flag prefix), vs. which
parameters are optional (and therefore require a --flag prefix to make
it obvious which optional parameter is being provided), while also being
clear on which optional parameters require an argument (and whether that
argument is text or numeric) vs. those that are just boolean flags.

> I think it would be worth of cleaning out and make everything one way or
> another. Would it be a problem? I presume it's just matter of modifying
> "couple" printf()-s.

That's true - the option printing is all controlled in
tools/virsh.c:vshCmddefHelp.

-- 
Eric Blake   eblake at redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

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


More information about the libvir-list mailing list