On Mon, Jul 30, 2018 at 11:09 PM Eric Blake <ebl...@redhat.com> wrote:
> On 07/30/2018 02:54 PM, Nir Soffer wrote:
>
> >>> $ qemu-img
> >>> qemu-img: Not enough arguments
> >>> Try 'qemu-img --help' for more information
> >
> >
> > This is not user friendly, but unfortunately very common.
> > It can be improved by treating no arguments as --help, like git.
>
> I somewhat disagree that git is a good example. If '--help' occupies
> more than about 25 lines (a screenful on some default terminal sizes),
> the mere fact that you have to scroll to read it makes it less helpful
> than a 2-liner statement that lets you know "I couldn't do anything
> useful with your botched command line, please read the documentation and
> try again". 'git' behaving as 'git --help' outputs 42 lines, which
> fails my 'one screenful' test; and 'qemu-img --help' at 104 lines is
> definitely too verbose to be the default behavior when --help is not given.
>
> /me Wow - I can't believe I'm actually about to use this as an example,
> but:
>
> 'cvs' and 'cvs --help' is just 13 lines (except to stderr, when it
> should have been stdout), and gives enough hints on how to get more
> specific help on a particular topic. Great for the plain 'cvs' case; a
> bit more debatable on 'cvs --help' (the fact that you have to ask for
> help twice: once for the summary, again for the specific help, gets
> tedious).
>
> At any rate, getting command-line tools to have user-friendly behavior
> when insufficient arguments are supplied is an artform, and you'll find
> lots of bikeshed colors out there.
>
> And regardless of any opinions I've expressed above, this thread does
> point out that 104 lines for 'qemu-img --help' is long, and anything we
> can do to make that easier to digest may still be worthwhile.
>
I agree that git help is too long, and falling back to --help without
improving
qemu-img help is not very useful.
What we need is something like:
$ qemu-img
Commands:
amend description...
bench description...
check description...
commit description...
compare description...
convert description...
create description...
dd description...
info description...
map description...
measure description...
snapshot description...
rebase description...
resize description...
This fits in a terminal, and we have space for additional tips or common
command line options.
Note that this is not "botched command line", so we don't need to complain
about missing arguments.
qemu-img create --help
Should show only help for create.
virsh works in a similar way, but it has too many commands in the main help.
Of course this may break some management systems calling qemu-img --help
and parsing the output. We used to do this in oVirt in the past :-)
Nir
