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

["Michael S. Tsirkin" <mst@redhat.com>]

On Mon, Sep 14, 2015 at 08:01:20PM +0200, 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.

I agree - a bit more order is IMHO needed in the general
-help - I'm not sure this is the place to start.
E.g. it is not your fault that it lists e.g. a ton of random
stuff as Standard options but this becomes more of
a problem if you hide things behind sub-sections.

For example, how do I change the amount of memory?
Currently I do --help and search for memory.


This also diverges from the way one queries other help
(-device foo,help, -cpu help  etc).

How about we move detailed help into each option instead?
This will mean only 113 lines which is a lot, but
kind of reasonable.

-machine [type=]name[,prop[=value][,...]] select emulated machine ('-machine help' for help)
-cpu cpu        select CPU ('-cpu help' for list)
-smp [cpus=]n[,prop[=value][,...]] configure SMP ('-smp help' for help)
-numa node[,prop[=value][,...]] configure NUMA ('-numa help' for help)


Of course it's also true that often the help says
nothing useful at all.


> As sections already exist in the help description,
> add some options to only display the wanted section.
> 
> '-help' now can take an optional parameter of the
> form -help[=LIST], which is a comma separated list
> of sections to display:
> 
>     all       display all help sections
>     help      display help options
>     standard  display standard options

What does standard options mean?

>     block     display block options
>     usb       display usb options
>     display   display display options
>     machine   display machine options
>     network   display network options
>     character display character options

Character device options?

>     url       display url options

what are these?

>     bt        display bt options

bluetooth options?

>     tpm       display tpm options
>     kernel    display kernel options
>     expert    display expert options
>     object    display object options

what are these?

> 
> '-help' without option displays only help options.
> 
> Example:
> 
>     $ x86_64-softmmu/qemu-system-x86_64 -help=kernel,usb
>     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'
> 
> Signed-off-by: Laurent Vivier <lvivier@redhat.com>

Maybe a good place to start is rewriting our man page.
We can then distill that to a minimum that makes sense
in -help.


-- 
MST