[PATCH v3 27/33] qemu-options.hx: Fix up the autogenerated rST

[Peter Maydell]

This commit contains hand-written fixes for some issues with the
autogenerated rST fragments in qemu-options.hx:

 * Sphinx complains about the UTF-8 art table in the documentation of
   the -drive option.  Replace it with a proper rST format table.

 * rST does not like definition list entries with no actual
   definition, but it is possible to work around this by putting a
   single escaped literal space as the definition line.

 * The "-g widthxheight" option documentation suffers particularly
   badly from losing the distinction between italics and fixed-width
   as a result of the auto conversion, so put it back in again.

 * The script missed some places that use the |qemu_system| etc
   macros and need to be marked up as parsed-literal blocks.

 * The script autogenerated an expanded out version of the
   contents of qemu-option-trace.texi; replace it with an
   qemu-option-trace.rst.inc include.

This is sufficient that we can enable inclusion of the
option documentation from invocation.rst.

Signed-off-by: Peter Maydell <address@hidden>
---
I opted not to try to reinstate all the italics-vs-fixed
distinctions in the option headings, in the interests
of expediency. I'm happy to go back and add this in later
once the whole conversion has landed but I think we are
better off doing a mostly-good-enough conversion quickly
and then refining it in-tree rather than having it out
of tree for a long time and getting hit by problems as
documentation is updated by other patches...
---
 Makefile                   |   2 +-
 docs/system/invocation.rst |   2 +
 qemu-options.hx            | 143 +++++++++++++++++++++----------------
 3 files changed, 84 insertions(+), 63 deletions(-)

diff --git a/Makefile b/Makefile
index 98ef06ab8e8..f7d08997dbf 100644
--- a/Makefile
+++ b/Makefile
@@ -1071,7 +1071,7 @@ $(MANUAL_BUILDDIR)/interop/index.html: $(call 
manual-deps,interop)
 $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
        $(call build-manual,specs,html)
 
-$(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system) 
$(SRC_PATH)/hmp-commands.hx $(SRC_PATH)/hmp-commands-info.hx
+$(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system) 
$(SRC_PATH)/hmp-commands.hx $(SRC_PATH)/hmp-commands-info.hx 
$(SRC_PATH)/qemu-options.hx
        $(call build-manual,system,html)
 
 $(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools) 
$(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc
diff --git a/docs/system/invocation.rst b/docs/system/invocation.rst
index c112bcb45a4..d77dd13d4f7 100644
--- a/docs/system/invocation.rst
+++ b/docs/system/invocation.rst
@@ -10,6 +10,8 @@ Invocation
 disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
 not need a disk image.
 
+.. hxtool-doc:: qemu-options.hx
+
 Device URL Syntax
 ~~~~~~~~~~~~~~~~~
 
diff --git a/qemu-options.hx b/qemu-options.hx
index 043e425b61e..f7061212ceb 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -448,7 +448,17 @@ cache, size is 10KB, policy is write-back, the cache Line 
size is 8 bytes:
 
 ETEXI
 SRST
-``-numa 
node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``;
 \ ``-numa 
node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``;
 \ ``-numa dist,src=source,dst=destination,val=distance``; \ ``-numa 
cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]``; \ ``-numa 
hmat-lb,initiator=node,target=node,hierarchy=hierarchy,data-type=tpye[,latency=lat][,bandwidth=bw]``;
 \ ``-numa 
hmat-cache,node-id=node,size=size,level=level[,associativity=str][,policy=str][,line=size]``
+``-numa 
node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``
+  \ 
+``-numa 
node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``
+  \
+``-numa dist,src=source,dst=destination,val=distance``
+  \ 
+``-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]``
+  \ 
+``-numa 
hmat-lb,initiator=node,target=node,hierarchy=hierarchy,data-type=tpye[,latency=lat][,bandwidth=bw]``
+  \ 
+``-numa 
hmat-cache,node-id=node,size=size,level=level[,associativity=str][,policy=str][,line=size]``
     Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA
     distance from a source node to a destination node. Set the ACPI
     Heterogeneous Memory Attributes for the given nodes.
@@ -687,7 +697,9 @@ driver=@var{driver},property=@var{prop},value=@var{value}.  
The
 longhand syntax works even when @var{driver} contains a dot.
 ETEXI
 SRST
-``-global driver.prop=value``; \ ``-global 
driver=driver,property=property,value=value``
+``-global driver.prop=value``
+  \ 
+``-global driver=driver,property=property,value=value``
     Set default value of driver's property prop to value, e.g.:
 
     .. parsed-literal::
@@ -788,7 +800,7 @@ SRST
     it. This only effects when boot priority is changed by bootindex
     options. The default is non-strict boot.
 
-    ::
+    .. parsed-literal::
 
         # try to boot from network first, then from hard disk
         |qemu_system_x86| -boot order=nc
@@ -1618,7 +1630,9 @@ STEXI
 Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}).
 ETEXI
 SRST
-``-fda file``; \ ``-fdb file``
+``-fda file``
+  \
+``-fdb file``
     Use file as floppy disk 0/1 image (see
     :ref:`disk_005fimages`).
 ERST
@@ -1641,7 +1655,13 @@ STEXI
 Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
 ETEXI
 SRST
-``-hda file``; \ ``-hdb file``; \ ``-hdc file``; \ ``-hdd file``
+``-hda file``
+  \
+``-hdb file``
+  \ 
+``-hdc file``
+  \ 
+``-hdd file``
     Use file as hard disk 0, 1, 2 or 3 image (see
     :ref:`disk_005fimages`).
 ERST
@@ -2295,15 +2315,15 @@ SRST
         the ``write-cache`` option of block guest devices (as in
         ``-device``). The modes correspond to the following settings:
 
-        ::
-
-            �            │ cache.writeback   cache.direct   cache.no-flush
-            ─────────────┼─────────────────────────────────────────────────
-            writeback    │ on                off            off
-            none         │ on                on             off
-            writethrough │ off               off            off
-            directsync   │ off               on             off
-            unsafe       │ on                off            on
+        =============  ===============   ============   ==============
+        \              cache.writeback   cache.direct   cache.no-flush
+        =============  ===============   ============   ==============
+        writeback      on                off            off
+        none           on                on             off
+        writethrough   off               off            off
+        directsync     off               on             off
+        unsafe         on                off            on
+        =============  ===============   ============   ==============
 
         The default mode is ``cache=writeback``.
 
@@ -2594,7 +2614,13 @@ Specifies the tag name to be used by the guest to mount 
this export point.
 
 ETEXI
 SRST
-``-fsdev local,id=id,path=path,security_model=security_model 
[,writeout=writeout][,readonly][,fmode=fmode][,dmode=dmode] 
[,throttling.option=value[,throttling.option=value[,...]]]``; \ ``-fsdev 
proxy,id=id,socket=socket[,writeout=writeout][,readonly]``; \ ``-fsdev 
proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly]``; \ ``-fsdev 
synth,id=id[,readonly]``
+``-fsdev local,id=id,path=path,security_model=security_model 
[,writeout=writeout][,readonly][,fmode=fmode][,dmode=dmode] 
[,throttling.option=value[,throttling.option=value[,...]]]``
+  \ 
+``-fsdev proxy,id=id,socket=socket[,writeout=writeout][,readonly]``
+  \
+``-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly]``
+  \
+``-fsdev synth,id=id[,readonly]``
     Define a new file system device. Valid options are:
 
     ``local``
@@ -2791,7 +2817,13 @@ would still return entries from other devices).
 @end table
 ETEXI
 SRST
-``-virtfs local,path=path,mount_tag=mount_tag 
,security_model=security_model[,writeout=writeout][,readonly] 
[,fmode=fmode][,dmode=dmode][,multidevs=multidevs]``; \ ``-virtfs 
proxy,socket=socket,mount_tag=mount_tag [,writeout=writeout][,readonly]``; \ 
``-virtfs proxy,sock_fd=sock_fd,mount_tag=mount_tag 
[,writeout=writeout][,readonly]``; \ ``-virtfs synth,mount_tag=mount_tag``
+``-virtfs local,path=path,mount_tag=mount_tag 
,security_model=security_model[,writeout=writeout][,readonly] 
[,fmode=fmode][,dmode=dmode][,multidevs=multidevs]``
+  \ 
+``-virtfs proxy,socket=socket,mount_tag=mount_tag 
[,writeout=writeout][,readonly]``
+  \ 
+``-virtfs proxy,sock_fd=sock_fd,mount_tag=mount_tag 
[,writeout=writeout][,readonly]``
+  \
+``-virtfs synth,mount_tag=mount_tag``
     Define a new filesystem device and expose it to the guest using a
     virtio-9p-device. The general form of a Virtual File system
     pass-through options are:
@@ -3568,7 +3600,7 @@ of 1152x900x8 for people who wish to use OBP.
 
 ETEXI
 SRST
-``-g widthxheight[xdepth]``
+``-g`` *width*\ ``x``\ *height*\ ``[x``\ *depth*\ ``]``
     Set the initial graphical resolution and depth (PPC, SPARC only).
 
     For PPC the default is 800x600x32.
@@ -4847,7 +4879,7 @@ SRST
         For example, to redirect host X11 connection from screen 1 to
         guest screen 0, use the following:
 
-        ::
+        .. parsed-literal::
 
             # on the host
             |qemu_system| -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
@@ -4857,7 +4889,7 @@ SRST
         To redirect telnet connections from host port 5555 to telnet
         port on the guest, use the following:
 
-        ::
+        .. parsed-literal::
 
             # on the host
             |qemu_system| -nic user,hostfwd=tcp::5555-:23
@@ -4875,7 +4907,7 @@ SRST
         You can either use a chardev directly and have that one used
         throughout QEMU's lifetime, like in the following example:
 
-        ::
+        .. parsed-literal::
 
             # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it 
whenever
             # the guest accesses it
@@ -4885,7 +4917,7 @@ SRST
         by the guest, so that QEMU behaves similar to an inetd process
         for that virtual server:
 
-        ::
+        .. parsed-literal::
 
             # call "netcat 10.10.1.1 4321" on every TCP connection to 
10.0.2.100:1234
             # and connect the TCP stream to its stdin/stdout
@@ -4912,12 +4944,12 @@ SRST
 
     Examples:
 
-    ::
+    .. parsed-literal::
 
         #launch a QEMU instance with the default network script
         |qemu_system| linux.img -nic tap
 
-    ::
+    .. parsed-literal::
 
         #launch a QEMU instance with two NICs, each one connected
         #to a TAP device
@@ -4925,7 +4957,7 @@ SRST
                 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
                 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
 
-    ::
+    .. parsed-literal::
 
         #launch a QEMU instance with the default network helper to
         #connect a TAP device to bridge br0
@@ -4942,13 +4974,13 @@ SRST
 
     Examples:
 
-    ::
+    .. parsed-literal::
 
         #launch a QEMU instance with the default network helper to
         #connect a TAP device to bridge br0
         |qemu_system| linux.img -netdev bridge,id=n1 -device 
virtio-net,netdev=n1
 
-    ::
+    .. parsed-literal::
 
         #launch a QEMU instance with the default network helper to
         #connect a TAP device to bridge qemubr0
@@ -4964,7 +4996,7 @@ SRST
 
     Example:
 
-    ::
+    .. parsed-literal::
 
         # launch a first QEMU instance
         |qemu_system| linux.img \
@@ -4991,7 +5023,7 @@ SRST
 
     Example:
 
-    ::
+    .. parsed-literal::
 
         # launch one QEMU instance
         |qemu_system| linux.img \
@@ -5008,7 +5040,7 @@ SRST
 
     Example (User Mode Linux compat.):
 
-    ::
+    .. parsed-literal::
 
         # launch QEMU instance (note mcast address selected is UML's default)
         |qemu_system| linux.img \
@@ -5074,7 +5106,7 @@ SRST
     For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to
     the bridge br-lan on the remote Linux host 1.2.3.4:
 
-    ::
+    .. parsed-literal::
 
         # Setup tunnel on linux host using raw ip as encapsulation
         # on 1.2.3.4
@@ -5102,7 +5134,7 @@ SRST
 
     Example:
 
-    ::
+    .. parsed-literal::
 
         # launch vde switch
         vde_switch -F -sock /tmp/myswitch
@@ -5731,7 +5763,9 @@ The available backends are:
 
     ``path`` specifies the path to the tty. ``path`` is required.
 
-``-chardev parallel,id=id,path=path``; \ ``-chardev parport,id=id,path=path``
+``-chardev parallel,id=id,path=path``
+  \
+``-chardev parport,id=id,path=path``
     ``parallel`` is only available on Linux, FreeBSD and DragonFlyBSD
     hosts.
 
@@ -6569,6 +6603,7 @@ utilization will be incorrect, not taking into account 
guest idle time.
 ETEXI
 SRST
 ``-overcommit mem-lock=on|off``
+  \ 
 ``-overcommit cpu-pm=on|off``
     Run qemu with hints about host resource overcommit. The default is
     to assume that host overcommits all resources.
@@ -6607,7 +6642,7 @@ SRST
     use case. The latter is allowing to start QEMU from within gdb and
     establish the connection via a pipe:
 
-    ::
+    .. parsed-literal::
 
         (gdb) target remote | exec |qemu_system| -gdb stdio ...
 ERST
@@ -7196,7 +7231,9 @@ be used to change settings (such as migration parameters) 
prior to issuing
 the migrate_incoming to allow the migration to begin.
 ETEXI
 SRST
-``-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]``; \ ``-incoming 
rdma:host:port[,ipv4][,ipv6]``
+``-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]``
+  \ 
+``-incoming rdma:host:port[,ipv4][,ipv6]``
     Prepare for incoming migration, listen on a given tcp port.
 
 ``-incoming unix:socketpath``
@@ -7537,27 +7574,8 @@ HXCOMM HX does not support conditional compilation of 
text.
 ETEXI
 SRST
 ``-trace [[enable=]pattern][,events=file][,file=file]``
-    Specify tracing options.
+  .. include:: ../qemu-option-trace.rst.inc
 
-    ``[enable=]pattern``
-        Immediately enable events matching pattern (either event name or
-        a globbing pattern). This option is only available if QEMU has
-        been compiled with the simple, log or ftrace tracing backend. To
-        specify multiple events or patterns, specify the ``-trace``
-        option multiple times.
-
-        Use ``-trace help`` to print a list of names of trace points.
-
-    ``events=file``
-        Immediately enable events listed in file. The file must contain
-        one event name (as listed in the ``trace-events-all`` file) per
-        line; globbing patterns are accepted too. This option is only
-        available if QEMU has been compiled with the simple, log or
-        ftrace tracing backend.
-
-    ``file=file``
-        Log output traces to file. This option is only available if QEMU
-        has been compiled with the simple tracing backend.
 ERST
 DEF("plugin", HAS_ARG, QEMU_OPTION_plugin,
     "-plugin [file=]<file>[,arg=<string>]\n"
@@ -8707,7 +8725,7 @@ SRST
         which specify the queue number of cryptodev backend, the default
         of queues is 1.
 
-        ::
+        .. parsed-literal::
 
              # |qemu_system| \
                [...] \
@@ -8726,7 +8744,7 @@ SRST
         specify the queue number of cryptodev backend for multiqueue
         vhost-user, the default of queues is 1.
 
-        ::
+        .. parsed-literal::
 
              # |qemu_system| \
                [...] \
@@ -8736,6 +8754,7 @@ SRST
                [...]
 
     ``-object 
secret,id=id,data=string,format=raw|base64[,keyid=secretid,iv=string]``
+      \ 
     ``-object 
secret,id=id,file=filename,format=raw|base64[,keyid=secretid,iv=string]``
         Defines a secret to store a password, encryption key, or some
         other sensitive data. The sensitive data can either be passed
@@ -8763,7 +8782,7 @@ SRST
 
         The simplest (insecure) usage is to provide the secret inline
 
-        ::
+        .. parsed-literal::
 
              # |qemu_system| -object secret,id=sec0,data=letmein,format=raw
 
@@ -8807,7 +8826,7 @@ SRST
         ``key.b64`` and specify that to be used to decrypt the user
         password. Pass the contents of ``iv.b64`` to the second secret
 
-        ::
+        .. parsed-literal::
 
              # |qemu_system| \
                  -object secret,id=secmaster0,format=base64,file=key.b64 \
@@ -8856,7 +8875,7 @@ SRST
 
         e.g to launch a SEV guest
 
-        ::
+        .. parsed-literal::
 
              # |qemu_system_x86| \
                  ......
@@ -8877,7 +8896,7 @@ SRST
         An example authorization object to validate a x509 distinguished
         name would look like:
 
-        ::
+        .. parsed-literal::
 
              # |qemu_system| \
                  ...
@@ -8928,7 +8947,7 @@ SRST
         An example authorization object to validate a SASL username
         would look like:
 
-        ::
+        .. parsed-literal::
 
              # |qemu_system| \
                  ...
@@ -8947,7 +8966,7 @@ SRST
         An example authorization object to validate a TLS x509
         distinguished name would look like:
 
-        ::
+        .. parsed-literal::
 
              # |qemu_system| \
                  ...
-- 
2.20.1