[libvirt] consistency of virsh help output

[Zdenek Styblik]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Heya,

I've a bit of re-shuffled original e-mail and for that I'm sorry.

On 02/03/11 19:05, Eric Blake wrote:
> In this case, patches speak louder than words :)

Patch is attached.


> 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.  

I didn't say we should take one way or another; neither I've said I'm
going to. I merely wanted to point out at differences, which I think,
create a bit of confusion.

As suggested in my hasty reply, perhaps we should have a vote or poll.
It doesn't seem to be easy decision to me.

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

This is domain of man pages and might be (the best) understood. But it's
damn-o-damn long. And although we are way past 80 char terminals, I
still tend to keep within this limit etc. :)

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

When understood, it's ok. And the majority of virsh commands have this
format; except 19; I would stick with it.
I have nothing against either of these format, although this short one
requires '<domain> -> [--domain] <string>' substitution and a bit of
thinking :)
I wouldn't make boolean/switches shorter though -> keep eg.
[--print-xml] in Synopsis as it is.

> 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'm still a bit confused about this part. :| I don't think Options part
needs changes, although one could split params(domain) and
booleans/switches(print-xml) aside.

Regards,
Zdenek

- -- 
Zdenek Styblik
Net/Linux admin
OS TurnovFree.net
email: stybla at turnovfree.net
jabber: stybla at jabber.turnovfree.net
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk1Oag8ACgkQ8MreUbSH7ik1ZQCfWXHJCiVCmrwXOWyM6YNov8i/
gcEAnR9QycO0RuUCiKQyjzh6pv31Gces
=7SO+
-----END PGP SIGNATURE-----
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: 0001-Unify-virsh-help-synopsis-output.patch
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20110206/e45687f5/attachment-0001.ksh>