Document command line options with single dash

[Qemu-devel] [PATCH] Document command line options with single dash

Posted by BALATON Zoltan 7 years, 3 months ago

QEMU options have a single dash (but also work as double dash for
convenience and compatibility). Most options are listed with single
dash in command line help but some were listed with two dashes.
Normalize these to have the same format as the others.

Left --preconfig as that is mentioned as double dash everywhere so I
assume that is the preferred form for that.

Signed-off-by: BALATON Zoltan <balaton@eik.bme.hu>
---
 qemu-options.hx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index 371c427..b1bf0f4 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -471,7 +471,7 @@ STEXI
 @item -balloon virtio[,addr=@var{addr}]
 @findex -balloon
 Enable virtio balloon device, optionally with PCI address @var{addr}. This
-option is deprecated, use @option{--device virtio-balloon} instead.
+option is deprecated, use @option{-device virtio-balloon} instead.
 ETEXI
 
 DEF("device", HAS_ARG, QEMU_OPTION_device,
@@ -2005,7 +2005,7 @@ DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
     "-netdev hubport,id=str,hubid=n[,netdev=nd]\n"
     "                configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL)
 DEF("nic", HAS_ARG, QEMU_OPTION_nic,
-    "--nic [tap|bridge|"
+    "-nic [tap|bridge|"
 #ifdef CONFIG_SLIRP
     "user|"
 #endif
@@ -2024,7 +2024,7 @@ DEF("nic", HAS_ARG, QEMU_OPTION_nic,
     "socket][,option][,...][mac=macaddr]\n"
     "                initialize an on-board / default host NIC (using MAC address\n"
     "                macaddr) and connect it to the given host network backend\n"
-    "--nic none      use it alone to have zero network devices (the default is to\n"
+    "-nic none       use it alone to have zero network devices (the default is to\n"
     "                provided a 'user' network connection)\n",
     QEMU_ARCH_ALL)
 DEF("net", HAS_ARG, QEMU_OPTION_net,
@@ -3339,7 +3339,7 @@ mlocking qemu and guest memory can be enabled via @option{mlock=on}
 ETEXI
 
 DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit,
-    "--overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
+    "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
     "                run qemu with overcommit hints\n"
     "                mem-lock=on|off controls memory lock support (default: off)\n"
     "                cpu-pm=on|off controls cpu power management (default: off)\n",
-- 
2.7.6

Re: [Qemu-devel] [PATCH] Document command line options with single dash

Posted by Thomas Huth 7 years, 3 months ago

On 16.07.2018 21:12, BALATON Zoltan wrote:
> QEMU options have a single dash (but also work as double dash for
> convenience and compatibility). Most options are listed with single
> dash in command line help but some were listed with two dashes.
> Normalize these to have the same format as the others.
> 
> Left --preconfig as that is mentioned as double dash everywhere so I
> assume that is the preferred form for that.
> 
> Signed-off-by: BALATON Zoltan <balaton@eik.bme.hu>
> ---
>  qemu-options.hx | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 371c427..b1bf0f4 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -471,7 +471,7 @@ STEXI
>  @item -balloon virtio[,addr=@var{addr}]
>  @findex -balloon
>  Enable virtio balloon device, optionally with PCI address @var{addr}. This
> -option is deprecated, use @option{--device virtio-balloon} instead.
> +option is deprecated, use @option{-device virtio-balloon} instead.
>  ETEXI
>  
>  DEF("device", HAS_ARG, QEMU_OPTION_device,
> @@ -2005,7 +2005,7 @@ DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
>      "-netdev hubport,id=str,hubid=n[,netdev=nd]\n"
>      "                configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL)
>  DEF("nic", HAS_ARG, QEMU_OPTION_nic,
> -    "--nic [tap|bridge|"
> +    "-nic [tap|bridge|"
>  #ifdef CONFIG_SLIRP
>      "user|"
>  #endif
> @@ -2024,7 +2024,7 @@ DEF("nic", HAS_ARG, QEMU_OPTION_nic,
>      "socket][,option][,...][mac=macaddr]\n"
>      "                initialize an on-board / default host NIC (using MAC address\n"
>      "                macaddr) and connect it to the given host network backend\n"
> -    "--nic none      use it alone to have zero network devices (the default is to\n"
> +    "-nic none       use it alone to have zero network devices (the default is to\n"
>      "                provided a 'user' network connection)\n",
>      QEMU_ARCH_ALL)
>  DEF("net", HAS_ARG, QEMU_OPTION_net,
> @@ -3339,7 +3339,7 @@ mlocking qemu and guest memory can be enabled via @option{mlock=on}
>  ETEXI
>  
>  DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit,
> -    "--overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
> +    "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
>      "                run qemu with overcommit hints\n"
>      "                mem-lock=on|off controls memory lock support (default: off)\n"
>      "                cpu-pm=on|off controls cpu power management (default: off)\n",
> 

Acked-by: Thomas Huth <thuth@redhat.com>

... I'm in favour for consistency for the 3.0 release. But in the long
run, we should really come to a conclusion what we prefer (we still got
the double dash task at
https://wiki.qemu.org/BiteSizedTasks#Consistent_option_usage_in_documentation
)

Re: [Qemu-devel] [PATCH] Document command line options with single dash

Posted by Paolo Bonzini 7 years, 3 months ago

On 17/07/2018 09:43, Thomas Huth wrote:
> On 16.07.2018 21:12, BALATON Zoltan wrote:
>> QEMU options have a single dash (but also work as double dash for
>> convenience and compatibility). Most options are listed with single
>> dash in command line help but some were listed with two dashes.
>> Normalize these to have the same format as the others.
>>
>> Left --preconfig as that is mentioned as double dash everywhere so I
>> assume that is the preferred form for that.
>>
>> Signed-off-by: BALATON Zoltan <balaton@eik.bme.hu>
>> ---
>>  qemu-options.hx | 8 ++++----
>>  1 file changed, 4 insertions(+), 4 deletions(-)
>>
>> diff --git a/qemu-options.hx b/qemu-options.hx
>> index 371c427..b1bf0f4 100644
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
>> @@ -471,7 +471,7 @@ STEXI
>>  @item -balloon virtio[,addr=@var{addr}]
>>  @findex -balloon
>>  Enable virtio balloon device, optionally with PCI address @var{addr}. This
>> -option is deprecated, use @option{--device virtio-balloon} instead.
>> +option is deprecated, use @option{-device virtio-balloon} instead.
>>  ETEXI
>>  
>>  DEF("device", HAS_ARG, QEMU_OPTION_device,
>> @@ -2005,7 +2005,7 @@ DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
>>      "-netdev hubport,id=str,hubid=n[,netdev=nd]\n"
>>      "                configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL)
>>  DEF("nic", HAS_ARG, QEMU_OPTION_nic,
>> -    "--nic [tap|bridge|"
>> +    "-nic [tap|bridge|"
>>  #ifdef CONFIG_SLIRP
>>      "user|"
>>  #endif
>> @@ -2024,7 +2024,7 @@ DEF("nic", HAS_ARG, QEMU_OPTION_nic,
>>      "socket][,option][,...][mac=macaddr]\n"
>>      "                initialize an on-board / default host NIC (using MAC address\n"
>>      "                macaddr) and connect it to the given host network backend\n"
>> -    "--nic none      use it alone to have zero network devices (the default is to\n"
>> +    "-nic none       use it alone to have zero network devices (the default is to\n"
>>      "                provided a 'user' network connection)\n",
>>      QEMU_ARCH_ALL)
>>  DEF("net", HAS_ARG, QEMU_OPTION_net,
>> @@ -3339,7 +3339,7 @@ mlocking qemu and guest memory can be enabled via @option{mlock=on}
>>  ETEXI
>>  
>>  DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit,
>> -    "--overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
>> +    "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
>>      "                run qemu with overcommit hints\n"
>>      "                mem-lock=on|off controls memory lock support (default: off)\n"
>>      "                cpu-pm=on|off controls cpu power management (default: off)\n",
>>
> 
> Acked-by: Thomas Huth <thuth@redhat.com>
> 
> ... I'm in favour for consistency for the 3.0 release. But in the long
> run, we should really come to a conclusion what we prefer (we still got
> the double dash task at
> https://wiki.qemu.org/BiteSizedTasks#Consistent_option_usage_in_documentation
> )
> 

Queued, thanks.

Paolo