Re: [Qemu-devel] [PATCH v3 1/2] Use help sub-sections to create sub-help options

[Eric Blake <eblake@redhat.com>]

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

On 08/27/2015 04:22 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 subsections already exist in the help description,
> add some command options to only display the wanted
> subsection.
> 
> As more is better, this patch adds 13 lines to the -help output:
> 
>     -help-standard  display standard options
>     -help-block     display block options
>     -help-usb       display usb options
>     -help-display   display display options
>     -help-machine   display machine options
>     -help-network   display network options
>     -help-character display character options
>     -help-url       display url options
>     -help-bt        display bt options
>     -help-tpm       display tpm options
>     -help-kernel    display kernel options
>     -help-expert    display expert options
>     -help-object    display object options

Here you are proposing multiple options, which each cause an exit.  If I do:

$ ./x86_64-softmmu/qemu-system-x86_64 --help-block --help-usb

I do NOT get usb help, because --help-block already caused an exit.

I think a nicer approach might be:

--help[=LIST]

so that I could do:

$ ./x86_64-softmmu/qemu-system-x86_64 --help
short help, that documents that I can add =LIST for more details
$ ./x86_64-softmmu/qemu-system-x86_64 --help=block,usb
both the block and usb help blurbs
$ ./x86_64-softmmu/qemu-system-x86_64 --help=all
all help

> Example:
> 
>     $ qemu-system-x86_64 -help-kernel
>     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
> 
> Signed-off-by: Laurent Vivier <lvivier@redhat.com>
> ---
> v3: add a 2nd patch to add an help section, -help displays only this section
> v2: simplify the dance of #define/#undef, thanks to Marc-André.

I like the idea of breaking help into sections, but think that adding
separate options rather than an optional list to a single option is more
useful.  Also, I think you'll get a better review of v4 if it occurs as
a top-level thread.

>  qemu-options.hx | 150 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  vl.c            | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 280 insertions(+), 4 deletions(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 77f5853..49b78df 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -6,17 +6,123 @@ HXCOMM construct option structures, enums and help message for specified
>  HXCOMM architectures.
>  HXCOMM HXCOMM can be used for comments, discarded from both texi and C
>  
> +#if defined(QEMU_HELP_SELECT_STANDARD) || !defined(QEMU_HELP_SELECT)
> +#undef QEMU_HELP_SELECT_STANDARD
>  DEFHEADING(Standard options:)
>  STEXI
>  @table @option
>  ETEXI
>  
>  DEF("help", 0, QEMU_OPTION_h,
> -    "-h or -help     display this help and exit\n", QEMU_ARCH_ALL)
> +    "-h or -help     display all help options and exit\n", QEMU_ARCH_ALL)
>  STEXI
>  @item -h
>  @findex -h
> -Display help and exit
> +Display all help options and exit
> +ETEXI
> +
> +DEF("help-standard", 0, QEMU_OPTION_h_standard,
> +    "-help-standard  display standard options\n", QEMU_ARCH_ALL)
> +STEXI

This documents all the sub-helps up front.  But I'd rather see a simple
'--help' to output at most a screenful of information; if that is not
possible, then I'd rather see the sub-helps mentioned at the END of the
long help (that is, if I don't know that --help is going to be multiple
screenfuls or that subhelps even exist, then the LAST thing left on my
screen should be the information that helps me further refine my next
command line).


> +#if defined(QEMU_HELP_SELECT_EXPERT) || !defined(QEMU_HELP_SELECT)
> +#undef QEMU_HELP_SELECT_EXPERT
>  DEFHEADING(Debug/Expert options:)
>  STEXI
>  @table @option
> @@ -3510,7 +3649,7 @@ DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
>      "                Output vmstate information in JSON format to file.\n"
>      "                Use the scripts/vmstate-static-checker.py file to\n"
>      "                check for possible regressions in migration code\n"
> -    "                by comparing two such vmstate dumps.",
> +    "                by comparing two such vmstate dumps.\n",
>      QEMU_ARCH_ALL)

It might help to separate minor whitespace changes (adding or
rearranging where newlines appear) to be a different patch than the one
turning on grouping.

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