[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v3 1/2] Use help sub-sections to create sub-help
From: |
Eric Blake |
Subject: |
Re: [Qemu-devel] [PATCH v3 1/2] Use help sub-sections to create sub-help options |
Date: |
Wed, 2 Sep 2015 11:02:57 -0600 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.1.0 |
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 <address@hidden>
> ---
> 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
signature.asc
Description: OpenPGP digital signature