Man page improvements
cover Man page improvements
I was pointed to some places in the qemu man page where we have things like "file=file", with the placeholder "file" looking exactly the same as the option string "file". So I decided to go through it and mark all placeholders as such. While at it, I found that the msmouse description is in the wrong place.
Kevin Wolf (3):
Documentation: Highlight placeholders in suboptions
Documentation: Add missing tags to placeholders
Documentation: Move msmouse description to an appropriate place
qemu-doc.texi | 10 ++++---- qemu-options.hx | 65 ++++++++++++++++++++++++++++--------------------------- 2 files changed, 38 insertions(+), 37 deletions(-)
PATCH 1/3 Documentation: Highlight placeholders in suboptions
Currently, suboptions (i.e. something like file=file for -drive) are rendered as @code, so we're losing any @var highlighting in the man pages.
Replace them by @option, so that you actually can see what is a placeholder and what is meant verbatim.
--- qemu-options.hx | 18 +++++++++--------- 1 files changed, 9 insertions(+), 9 deletions(-)
qemu-options.hx +9 -9
@@ -114,7 +114,7 @@ STEXI Define a new drive. Valid options are: -@table @code +@table @option @item file=@var{file} This option defines which disk image (@pxref{disk_images}) to use with this drive. If the filename contains comma, you must double it
@@ -363,7 +363,7 @@ STEXI @item -usbdevice @var{devname} Add the USB device @var{devname}. @xref{usb_devices}. -@table @code +@table @option @item mouse Virtual Mouse. This will override the PS/2 mouse emulation when activated.
@@ -521,7 +521,7 @@ DEF("vga", HAS_ARG, QEMU_OPTION_vga, STEXI @item -vga @var{type} Select type of VGA card to emulate. Valid values for @var{type} are -@table @code +@table @option @item cirrus Cirrus Logic GD5446 Video card. All Windows versions starting from Windows 95 should recognize and use this graphic card. For optimal
@@ -568,7 +568,7 @@ tablet}). When using the VNC display, you must use the @option{-k} parameter to set the keyboard layout if you are not using en-us. Valid syntax for the @var{display} is -@table @code +@table @option @item @var{host}:@var{d}
@@ -591,7 +591,7 @@ can be used to later start the VNC server. Following the @var{display} value there may be one or more @var{option} flags separated by commas. Valid options are -@table @code +@table @option @item reverse
@@ -861,7 +861,7 @@ for a list of available devices for your target. Use the user mode network stack which requires no administrator privilege to run. Valid options are: -@table @code +@table @option @item vlan=@var{n} Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
@@ -1105,7 +1105,7 @@ machines have none. @anchor{bt-hcis} The following three types are recognized: -@table @code +@table @option @item -bt hci,null (default) The corresponding Bluetooth HCI assumes no internal logic and will not respond to any HCI commands or emit events.
@@ -1139,7 +1139,7 @@ Emulate a bluetooth device @var{dev} and place it in network @var{n} (default @code{0}). QEMU can only emulate one type of bluetooth devices currently: -@table @code +@table @option @item keyboard Virtual wireless keyboard implementing the HIDP bluetooth profile. @end table
@@ -1215,7 +1215,7 @@ ports. Use @code{-serial none} to disable all serial ports. Available character devices are: -@table @code +@table @option @item vc[:WxH] Virtual console. Optionally, a width and height can be given in pixel with @example
Signature · 1 line
1.6.2.5
PATCH 2/3 Documentation: Add missing tags to placeholders
In reply to Kevin WolfNot all placeholders in options descriptions had the @var tag on them. Add the tag so that it's clearly visible that they are placeholders.
--- qemu-doc.texi | 10 +++++----- qemu-options.hx | 43 ++++++++++++++++++++++--------------------- 2 files changed, 27 insertions(+), 26 deletions(-)
qemu-doc.texi +5 -5
@@ -1342,11 +1342,11 @@ The following options are specific to the PowerPC emulation: @table @option -@item -g WxH[xDEPTH] +@item -g @var{W}x@var{H}[x@var{DEPTH}] Set the initial VGA graphic mode. The default is 800x600x15. -@item -prom-env string +@item -prom-env @var{string} Set OpenBIOS variables in NVRAM, for example:
@@ -1442,12 +1442,12 @@ The following options are specific to the Sparc32 emulation: @table @option -@item -g WxHx[xDEPTH] +@item -g @var{W}x@var{H}x[x@var{DEPTH}] Set the initial TCX graphic mode. The default is 1024x768x8, currently the only other possible mode is 1024x768x24. -@item -prom-env string +@item -prom-env @var{string} Set OpenBIOS variables in NVRAM, for example:
@@ -1497,7 +1497,7 @@ The following options are specific to the Sparc64 emulation: @table @option -@item -prom-env string +@item -prom-env @var{string} Set OpenBIOS variables in NVRAM, for example:
qemu-options.hx +22 -21
118 lines not on this page · raw message
Signature · 1 line
1.6.2.5
PATCH 3/3 Documentation: Move msmouse description to an appropriate place
In reply to Kevin WolfPutting it right in the middle of the explanation for "-serial udp" probably wasn't the best idea.
--- qemu-options.hx | 4 ++-- 1 files changed, 2 insertions(+), 2 deletions(-)
qemu-options.hx +2 -2
@@ -1251,8 +1251,6 @@ This implements UDP Net Console. When @var{remote_host} or @var{src_ip} are not specified they default to @code{0.0.0.0}. When not using a specified @var{src_port} a random port is automatically chosen. -@item msmouse -Three button serial mouse. Configure the guest to use Microsoft protocol. If you just want a simple readonly console you can use @code{netcat} or @code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
@@ -1326,6 +1324,8 @@ listening on port 4444 would be: Braille device. This will use BrlAPI to display the braille output on a real or fake device. +@item msmouse +Three button serial mouse. Configure the guest to use Microsoft protocol. @end table ETEXI
Signature · 1 line
1.6.2.5