[libvirt] consistency of virsh help output

[Zdenek Styblik]

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

On 02/03/11 19:05, Eric Blake wrote:
[...]
> 
> 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 :)
> 

I can't agree more.

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

How about a vote? Because the first is domain of man pages, I've seen
latter only in virsh(Note: "only", because I can't remember anything
else. It doesn't mean virsh is unique).

Since the most is in latter, short, then it would be better to go that
way, or not?

Once understood the latter, it's just fine and makes sense. Justin can
confirm it took me some time. Thus I think it should be documented
somewhere - perhaps in virsh-cmd-reference.

Frankly, I'm a bit afraid if command help wouldn't be too long(80chars
limit) and what would happen if it is. I hope this one makes sense.

> 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've got a bit lost in all those ORs. Anyway, I don't think there is
anything wrong with the options layout once it's understood.
Or is it? I've tried to find comparable shell command and its man page,
but I've failed. virsh seems to be a bit specific, to me, with its
variability of parameters ... [--flag] <string> thing.

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

Ok, thank you for the tip.

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/

iEYEARECAAYFAk1K/GMACgkQ8MreUbSH7inNvgCeOj5vTq4NPahEiGzSSzQBZP0D
QVwAoKmG4RveXyKtBTeXFeto9DNPgWHp
=ijIh
-----END PGP SIGNATURE-----