Re: [Qemu-devel] [PATCH] qemu-img.c: increase spacing between commands in documentation

[Eric Blake <eblake@redhat.com>]

On 08/14/2018 03:40 AM, Kevin Wolf wrote:
>> And I've already expressed my opinion that it is already rather long, where
>> making it longer is not necessarily making it smarter.
> 
> I think if we want to improve the help text, we should split it up.
> 
> $ qemu-img --help
> qemu-img version 2.12.94 (v3.0.0-rc4-5-g4fe9c3e13d-dirty)
> Copyright (c) 2003-2017 Fabrice Bellard and the QEMU Project developers
> usage: qemu-img [standard options] command [command options]
> QEMU disk image utility
> 
>      '-h', '--help'       display this help and exit
>      '-V', '--version'    output version information and exit
>      '-T', '--trace'      [[enable=]<pattern>][,events=<file>][,file=<file>]
>                           specify tracing options
> 
> Commands:
> 
>      amend               Change options of an existing disk image
>      bench               Run benchmarks on a given disk image
>      check               Check the disk image for consistency or repair it
>      commit              Merge the disk image into its backing file
>      ...
> 
> Run 'qemu-img <command> --help' for details.
> 
> See <https://qemu.org/contribute/report-a-bug> for how to report bugs.
> More information on the QEMU project at <https://qemu.org>.

Indeed, that matches the approach that 'cvs --help' and 'git --help' 
have taken. I could live with a split along those lines as being 
something smarter.  When you want to learn the options for 'create', you 
may have to ask two different --help commands to learn everything you 
need ['--help' didn't give me enough, but told me to use 'create 
--help'], but at least you are not inundated with answers irrelevant to 
the question you are asking, so you don't have to scroll through a wall 
of text.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org