qemu-options.hx: Change from recommending '?' to 'help'

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>
---
 qemu-options.hx |   36 ++++++++++++++++--------------------
 1 file changed, 16 insertions(+), 20 deletions(-)

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

On 09/06/2012 07:54 AM, 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.

Agreed on that point.

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

Would it help to add some quoting?

"                selects emulated machine ('-machine help' for list)\n"
> @@ -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)

Here as well.

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

@code{-cpu help} here, to match the @code{-machine help} above.

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

Similar comments apply to the rest of the patch...

On 6 September 2012 15:55, Eric Blake <eblake@redhat.com> wrote:
> On 09/06/2012 07:54 AM, 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.
>
> Agreed on that point.
>
>>  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"
>
> Would it help to add some quoting?

I thought about that but decided it would be better to just
do the simple ?->help change and not try to also fix the
formatting or quoting in the same patch.

> "                selects emulated machine ('-machine help' for list)\n"
>> @@ -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)
>
> Here as well.
>
>>  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)
>
> @code{-cpu help} here, to match the @code{-machine help} above.

Again, don't want to get into trying to fix random formatting.
The text in general is not consistent about quoting of things,
so it's not like this patch is introducing any new issues.

Anthony says he's planning to majorly overhaul the help output
anyway...

-- PMM

Ping?

thanks
-- PMM

On 6 September 2012 14:54, Peter Maydell <peter.maydell@linaro.org> 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>
> ---
>  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
>
> --
> 1.7.9.5
>
>