Re: [Qemu-devel] [PATCH v4 3/3] Use help sub-sections to create sub-help options

[Eric Blake <eblake@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 3808 bytes --]

On 09/04/2015 01:30 PM, Laurent Vivier wrote:
> As '-help' output is 400 lines long it is not easy
> to find information, but generally we know from
> which area we want the information.
> 
> As sections already exist in the help description,
> add some options to only display the wanted section.
> 
> '-help' now can take an optional parameter, which is
> a comma separated list of sections to display:
> 
>     standard  display standard options
>     block     display block options
>     usb       display usb options
>     display   display display options
>     machine   display machine options
>     network   display network options
>     character display character options
>     url       display url options
>     bt        display bt options
>     tpm       display tpm options
>     kernel    display kernel options
>     expert    display expert options
>     object    display object options
> 
> '-help' without option displays all help sections.

No, that's not quite what I suggested.

-help without options should display AT MOST one screen-ful: start with
the usage: header (I don't know if version information has to stay,
since it is also present in --version, but it doesn't hurt as it is only
one line), and conclude with details about how to get more help.

Or, based on your patch, it should be something like:

> $ qemu-kvm -help
> QEMU emulator version 2.4.50, Copyright (c) 2003-2008 Fabrice Bellard
> usage: qemu-system-x86_64 [options] [disk_image]
> 
> 'disk_image' is a raw hard disk image for IDE hard disk 0
> 
> Help/version options:
> -h|-help [section][,...]
> list help options.
> You can provide the list of sections to display.
> available sections are:
> standard,block,usb,display,machine,network,character,
> url,bt,tpm,kernel,expert,object
> -version display version information and exit
> 
> For full details, try -help=all.

--help=help (or --help=sections, or whatever you name it) could be a
synonym for bare --help.

--help=all should display ALL sections, without having to spell out each
section by name.  And the LAST thing displayed should be the --help=help
section (so I don't have to invoke a pager to see how to limit the
output to the subsections I'm interested in).

--help=LIST for any other comma-separated LIST should produce those
particular sections.  I don't care if you reorder the sections (that is,
if --help=block,usb and --help=usb,block produce the same output, or if
they produce sections in swapped order, is up to you).

> 
>     $ x86_64-softmmu/qemu-system-x86_64 -help kernel,usb

Also, I think you need '=' not ' ' between -help and the list; but other
than that,

>     QEMU emulator version 2.4.50, Copyright (c) 2003-2008 Fabrice Bellard
>     usage: qemu-system-x86_64 [options] [disk_image]
> 
>     'disk_image' is a raw hard disk image for IDE hard disk 0
> 
>     Linux/Multiboot boot specific:
>     -kernel bzImage use 'bzImage' as kernel image
>     -append cmdline use 'cmdline' as kernel command line
>     -initrd file    use 'file' as initial ram disk
>     -dtb    file    use 'file' as device tree image
> 
>     USB options:
>     -usb            enable the USB driver (will be the default soon)
>     -usbdevice name add the host or guest USB device 'name'

this is indeed a nice example of how limiting to subsections can be useful.

> 
> Signed-off-by: Laurent Vivier <lvivier@redhat.com>
> ---
>  qemu-options.hx | 120 +++++++++++++++++++++++++++++++++++++++---
>  vl.c            | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++++----
>  2 files changed, 265 insertions(+), 15 deletions(-)

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]