Re: [Qemu-devel] [PATCH] qemu-options.hx: Change from recommending '?' to 'help'

["Daniel P. Berrange" <berrange@redhat.com>]

On Thu, Sep 06, 2012 at 02:54:40PM +0100, Peter Maydell wrote:
> Update the -help output and documentation so that it recommends
> 'help' rather than '?' for the various "list valid values for this
> option" cases. '?' is deprecated (as it can fail confusingly if
> not quoted), so it's better to steer users towards 'help'. ('?'
> still works, for backwards compatibility.)
> 
> This is the -help option part of the change otherwise done in
> commit c8057f9, since we are now past release 1.2 and free to
> change our help text without worrying about breaking libvirt.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

On behalf of libvirt...

  Signed-off-by: Daniel P. Berrange <berrange@redhat.com>

> ---
>  qemu-options.hx |   36 ++++++++++++++++--------------------
>  1 file changed, 16 insertions(+), 20 deletions(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 3c411c4..dd5a27c 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -6,10 +6,6 @@ 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
>  
> -HXCOMM TODO : when we are able to change -help output without breaking
> -HXCOMM libvirt we should update the help options which refer to -cpu ?,
> -HXCOMM -driver ?, etc to use the preferred -cpu help etc instead.
> -
>  DEFHEADING(Standard options:)
>  STEXI
>  @table @option
> @@ -33,7 +29,7 @@ ETEXI
>  
>  DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
>      "-machine [type=]name[,prop[=value][,...]]\n"
> -    "                selects emulated machine (-machine ? for list)\n"
> +    "                selects emulated machine (-machine help for list)\n"
>      "                property accel=accel1[:accel2[:...]] selects accelerator\n"
>      "                supported accelerators are kvm, xen, tcg (default: tcg)\n"
>      "                kernel_irqchip=on|off controls accelerated irqchip support\n"
> @@ -43,7 +39,7 @@ DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
>  STEXI
>  @item -machine [type=]@var{name}[,prop=@var{value}[,...]]
>  @findex -machine
> -Select the emulated machine by @var{name}. Use @code{-machine ?} to list
> +Select the emulated machine by @var{name}. Use @code{-machine help} to list
>  available machines. Supported machine properties are:
>  @table @option
>  @item accel=@var{accels1}[:@var{accels2}[:...]]
> @@ -64,11 +60,11 @@ HXCOMM Deprecated by -machine
>  DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
>  
>  DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
> -    "-cpu cpu        select CPU (-cpu ? for list)\n", QEMU_ARCH_ALL)
> +    "-cpu cpu        select CPU (-cpu help for list)\n", QEMU_ARCH_ALL)
>  STEXI
>  @item -cpu @var{model}
>  @findex -cpu
> -Select CPU model (-cpu ? for list and additional feature selection)
> +Select CPU model (-cpu help for list and additional feature selection)
>  ETEXI
>  
>  DEF("smp", HAS_ARG, QEMU_OPTION_smp,
> @@ -452,12 +448,12 @@ ETEXI
>  DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
>      "-soundhw c1,... enable audio support\n"
>      "                and only specified sound cards (comma separated list)\n"
> -    "                use -soundhw ? to get the list of supported cards\n"
> +    "                use -soundhw help to get the list of supported cards\n"
>      "                use -soundhw all to enable all of them\n", QEMU_ARCH_ALL)
>  STEXI
>  @item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
>  @findex -soundhw
> -Enable audio and selected sound hardware. Use ? to print all
> +Enable audio and selected sound hardware. Use 'help' to print all
>  available sound hardware.
>  
>  @example
> @@ -466,7 +462,7 @@ qemu-system-i386 -soundhw es1370 disk.img
>  qemu-system-i386 -soundhw ac97 disk.img
>  qemu-system-i386 -soundhw hda disk.img
>  qemu-system-i386 -soundhw all disk.img
> -qemu-system-i386 -soundhw ?
> +qemu-system-i386 -soundhw help
>  @end example
>  
>  Note that Linux's i810_audio OSS kernel (for AC97) module might
> @@ -555,16 +551,16 @@ DEF("device", HAS_ARG, QEMU_OPTION_device,
>      "-device driver[,prop[=value][,...]]\n"
>      "                add device (based on driver)\n"
>      "                prop=value,... sets driver properties\n"
> -    "                use -device ? to print all possible drivers\n"
> -    "                use -device driver,? to print all possible properties\n",
> +    "                use -device help to print all possible drivers\n"
> +    "                use -device driver,help to print all possible properties\n",
>      QEMU_ARCH_ALL)
>  STEXI
>  @item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
>  @findex -device
>  Add device @var{driver}.  @var{prop}=@var{value} sets driver
>  properties.  Valid properties depend on the driver.  To get help on
> -possible drivers and properties, use @code{-device ?} and
> -@code{-device @var{driver},?}.
> +possible drivers and properties, use @code{-device help} and
> +@code{-device @var{driver},help}.
>  ETEXI
>  
>  DEFHEADING()
> @@ -1335,7 +1331,7 @@ Valid values for @var{type} are
>  @code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
>  @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
>  @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
> -Not all devices are supported on all targets.  Use -net nic,model=?
> +Not all devices are supported on all targets.  Use -net nic,model=help
>  for a list of available devices for your target.
>  
>  @item -net user[,@var{option}][,@var{option}][,...]
> @@ -2361,7 +2357,7 @@ Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
>  ETEXI
>  
>  DEF("d", HAS_ARG, QEMU_OPTION_d, \
> -    "-d item1,...    output log to /tmp/qemu.log (use -d ? for a list of log items)\n",
> +    "-d item1,...    output log to /tmp/qemu.log (use -d help for a list of log items)\n",
>      QEMU_ARCH_ALL)
>  STEXI
>  @item -d
> @@ -2496,13 +2492,13 @@ ETEXI
>  
>  DEF("clock", HAS_ARG, QEMU_OPTION_clock, \
>      "-clock          force the use of the given methods for timer alarm.\n" \
> -    "                To see what timers are available use -clock ?\n",
> +    "                To see what timers are available use -clock help\n",
>      QEMU_ARCH_ALL)
>  STEXI
>  @item -clock @var{method}
>  @findex -clock
>  Force the use of the given methods for timer alarm. To see what timers
> -are available use -clock ?.
> +are available use -clock help.
>  ETEXI
>  
>  HXCOMM Options deprecated by -rtc
> @@ -2571,7 +2567,7 @@ watchdog with a single timer, or @code{i6300esb} (Intel 6300ESB I/O
>  controller hub) which is a much more featureful PCI-based dual-timer
>  watchdog.  Choose a model for which your guest has drivers.
>  
> -Use @code{-watchdog ?} to list available hardware models.  Only one
> +Use @code{-watchdog help} to list available hardware models.  Only one
>  watchdog can be enabled for a guest.
>  ETEXI

Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|