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

[Eric Blake]

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