[PATCH 0/4] docs: Remove bogus mailto links, minor cleanups

[PATCH 0/4] docs: Remove bogus mailto links, minor cleanups

[Peter Maydell]

I noticed while reviewing a patch to add documentation for
a new Arm board that an unescaped '@' character resulted in
an unintended mailto: hyperlink. This prompted me to grep
to see if we had any others of those, which we do. This
series fixes them, plus some other things I noticed along
the way.
 
The first patch cleans up some awkward rendering in the
xilinx-zynq-a9 board docs, including dropping a hex
address that was triggering a mailto: hyperlink.
 
Patch 2 is all the easy cases which we can just escape
or put into ``...`` preformatted text.
 
Patch 3 removes some uses of "@var{...}" in qemu-options.hx
which may be there because the authors had the impression
that that would be rendered into italics -- it isn't.
I've replaced them with uses of "<...>" as the most
common way we currently mark up "my-option=<something>".
These aren't mis-rendering as mailto links because they
all happen to already be in preformatted text.
 
Patch 4 makes a bigger cleanup to the colo-compare
option docs: it also uses "@var{...}" and here it is
causing mailto links to be generated.

thanks
-- PMM

Peter Maydell (4):
  docs/system/arm/xlnx-zynq.rst: Improve docs rendering
  docs: avoid unintended mailto: hyperlinks
  qemu-options.hx: Drop uses of @var
  qemu-options.hx: Improve formatting in colo-compare docs

 docs/devel/submitting-a-patch.rst     |  2 +-
 docs/system/arm/xlnx-zynq.rst         | 51 ++++++++++++++-------------
 docs/system/device-url-syntax.rst.inc |  4 +--
 docs/system/vnc-security.rst          |  6 ++--
 qemu-options.hx                       | 51 ++++++++++++++++-----------
 5 files changed, 63 insertions(+), 51 deletions(-)

-- 
2.47.3

[PATCH 1/4] docs/system/arm/xlnx-zynq.rst: Improve docs rendering

[Peter Maydell]

Make some minor improvements to the rendering of the docs for
the xlnx-zynq-a9 board:

 * use a proper hyperlink rather than a bare URL for the
   link to the reference manual
 * drop the hex address of the SMC SRAM: the bare '@' is
   rendered as bogus mailto: hyperlink, and the information
   is not very interesting to the user anyway
 * expand out the abbreviations in the list of Cortex-A9
   per-CPU devices
 * correct the bullet-point list markup so it doesn't render
   with odd highlighted lines
 * capitalize 'Arm' correctly

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/system/arm/xlnx-zynq.rst | 51 ++++++++++++++++++-----------------
 1 file changed, 27 insertions(+), 24 deletions(-)

diff --git a/docs/system/arm/xlnx-zynq.rst b/docs/system/arm/xlnx-zynq.rst
index ade18a3fe1..aa37df2926 100644
--- a/docs/system/arm/xlnx-zynq.rst
+++ b/docs/system/arm/xlnx-zynq.rst
@@ -4,32 +4,35 @@ The Zynq 7000 family is based on the AMD SoC architecture. These products
 integrate a feature-rich dual or single-core Arm Cortex-A9 MPCore based
 processing system (PS) and AMD programmable logic (PL) in a single device.
 
-More details here:
-https://docs.amd.com/r/en-US/ug585-zynq-7000-SoC-TRM/Zynq-7000-SoC-Technical-Reference-Manual
-
-QEMU xilinx-zynq-a9 board supports following devices:
-    - A9 MPCORE
-        - cortex-a9
-        - GIC v1
-        - Generic timer
-        - wdt
-    - OCM 256KB
-    - SMC SRAM@0xe2000000 64MB
-    - Zynq SLCR
-    - SPI x2
-    - QSPI
-    - UART
-    - TTC x2
-    - Gigabit Ethernet Controller x2
-    - SD Controller x2
-    - XADC
-    - Arm PrimeCell DMA Controller
-    - DDR Memory
-    - USB 2.0 x2
+The SoC is documented in the
+`Zynq 7000 Technical Reference manual <https://docs.amd.com/r/en-US/ug585-zynq-7000-SoC-TRM/Zynq-7000-SoC-Technical-Reference-Manual>`__.
+
+The QEMU xilinx-zynq-a9 board supports the following devices:
+
+- Arm Cortex-A9 MPCore CPU
+
+  - Cortex-A9 CPUs
+  - GIC v1 interrupt controller
+  - Generic timer
+  - Watchdog timer
+
+- OCM 256KB
+- SMC SRAM 64MB
+- Zynq SLCR
+- SPI x2
+- QSPI
+- UART
+- TTC x2
+- Gigabit Ethernet Controller x2
+- SD Controller x2
+- XADC
+- Arm PrimeCell DMA Controller
+- DDR Memory
+- USB 2.0 x2
 
 Running
 """""""
-Direct Linux boot of a generic ARM upstream Linux kernel:
+Direct Linux boot of a generic Arm upstream Linux kernel:
 
 .. code-block:: bash
 
@@ -44,4 +47,4 @@ For configuring the boot-mode provide the following on the command line:
 
    -machine boot-mode=qspi
 
-Supported values are jtag, sd, qspi, nor.
+Supported values are ``jtag``, ``sd``, ``qspi`` and ``nor``.
-- 
2.47.3

[PATCH 2/4] docs: avoid unintended mailto: hyperlinks

[Peter Maydell]

In rST documents, an '@' character in normal text or a parsed-literal is
assumed to be an email address and will result in a 'mailto:' hyperlink in
the generated HTML.  In several places we have mailto: hyperlinks that are
unintended nonsense; correct these by either escaping the @ character or
making the text use ``...`` preformatted rendering.

This commit covers only the simple cases which can be trivially fixed
with escaping or ``..``; the remaining cases will be handled in
separate commits.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/devel/submitting-a-patch.rst     | 2 +-
 docs/system/device-url-syntax.rst.inc | 4 ++--
 docs/system/vnc-security.rst          | 6 +++---
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-patch.rst
index dd1cf32ad3..5ccd09a397 100644
--- a/docs/devel/submitting-a-patch.rst
+++ b/docs/devel/submitting-a-patch.rst
@@ -18,7 +18,7 @@ one-shot fix, the bare minimum we ask is that:
 
    * - Check
      - Reason
-   * - Patches contain Signed-off-by: Your Name <author@email>
+   * - Patches contain ``Signed-off-by: Your Name <author@email>``
      - States you are legally able to contribute the code. See :ref:`patch_emails_must_include_a_signed_off_by_line`
    * - Sent as patch emails to ``qemu-devel@nongnu.org``
      - The project uses an email list based workflow. See :ref:`submitting_your_patches`
diff --git a/docs/system/device-url-syntax.rst.inc b/docs/system/device-url-syntax.rst.inc
index 43b5c2596b..aae65d138c 100644
--- a/docs/system/device-url-syntax.rst.inc
+++ b/docs/system/device-url-syntax.rst.inc
@@ -33,7 +33,7 @@ These are specified using a special URL syntax.
 
    .. parsed-literal::
 
-      |qemu_system| -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
+      |qemu_system| -drive file=iscsi://user%password\@192.0.2.1/iqn.2001-04.com.example/1
 
    Example (CHAP username/password via environment variables):
 
@@ -79,7 +79,7 @@ These are specified using a special URL syntax.
 
    .. parsed-literal::
 
-      |qemu_system| -drive file=ssh://user@host/path/to/disk.img
+      |qemu_system| -drive file=ssh://user\@host/path/to/disk.img
       |qemu_system| -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
 
    Currently authentication must be done using ssh-agent. Other
diff --git a/docs/system/vnc-security.rst b/docs/system/vnc-security.rst
index 4c1769eeb8..97e94ff407 100644
--- a/docs/system/vnc-security.rst
+++ b/docs/system/vnc-security.rst
@@ -182,9 +182,9 @@ When not using TLS the recommended configuration is
 This says to use the 'GSSAPI' mechanism with the Kerberos v5 protocol,
 with the server principal stored in /etc/qemu/krb5.tab. For this to work
 the administrator of your KDC must generate a Kerberos principal for the
-server, with a name of 'qemu/somehost.example.com@EXAMPLE.COM' replacing
-'somehost.example.com' with the fully qualified host name of the machine
-running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
+server, with a name of ``qemu/somehost.example.com@EXAMPLE.COM`` replacing
+``somehost.example.com`` with the fully qualified host name of the machine
+running QEMU, and ``EXAMPLE.COM`` with the Kerberos Realm.
 
 When using TLS, if username+password authentication is desired, then a
 reasonable configuration is
-- 
2.47.3

Re: [PATCH 2/4] docs: avoid unintended mailto: hyperlinks

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> In rST documents, an '@' character in normal text or a parsed-literal is
> assumed to be an email address and will result in a 'mailto:' hyperlink in
> the generated HTML.  In several places we have mailto: hyperlinks that are
> unintended nonsense; correct these by either escaping the @ character or
> making the text use ``...`` preformatted rendering.
>
> This commit covers only the simple cases which can be trivially fixed
> with escaping or ``..``; the remaining cases will be handled in
> separate commits.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Markus Armbruster <armbru@redhat.com>

Re: [PATCH 2/4] docs: avoid unintended mailto: hyperlinks

[Philippe Mathieu-Daudé]

On 15/1/26 15:26, Peter Maydell wrote:
> In rST documents, an '@' character in normal text or a parsed-literal is
> assumed to be an email address and will result in a 'mailto:' hyperlink in
> the generated HTML.  In several places we have mailto: hyperlinks that are
> unintended nonsense; correct these by either escaping the @ character or
> making the text use ``...`` preformatted rendering.
> 
> This commit covers only the simple cases which can be trivially fixed
> with escaping or ``..``; the remaining cases will be handled in
> separate commits.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>   docs/devel/submitting-a-patch.rst     | 2 +-
>   docs/system/device-url-syntax.rst.inc | 4 ++--
>   docs/system/vnc-security.rst          | 6 +++---
>   3 files changed, 6 insertions(+), 6 deletions(-)

Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>

[PATCH 3/4] qemu-options.hx: Drop uses of @var

[Peter Maydell]

A few entries in qemu-options.hx use the syntax "my-option=@var{name}"
when documenting an option that takes an argument. This syntax isn't
consistently used, and the documentation generation has no support for
it: it just appears literally in the HTML output.

Switch these uses to the more common "my-option=<name>". This also
doesn't have any particular support in the documentation generation
and so appears literally in the output, but it is a little less odd
looking to the end-user.

The other common pattern we have is "my-option=name" with no marking
at all that the right hand side of the '=' is not literal text;
using <> seems preferable to me, as it makes it more distinct from
cases where the right hand side is documenting that only certain
values are permitted, as in "my-option=on|off".

We don't change the uses of @var in the colo-compare documentation,
as that part deserves a slightly more wide-ranging overhaul that
is better in its own commit.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 qemu-options.hx | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index ec92723f10..aca9dba8b9 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -36,7 +36,7 @@ DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
     "                dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n"
     "                suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
     "                nvdimm=on|off controls NVDIMM support (default=off)\n"
-    "                memory-encryption=@var{} memory encryption object to use (default=none)\n"
+    "                memory-encryption=<id> memory encryption object to use (default=none)\n"
     "                hmat=on|off controls ACPI HMAT support (default=off)\n"
     "                spcr=on|off controls ACPI SPCR support (default=on)\n"
 #ifdef CONFIG_POSIX
@@ -100,7 +100,7 @@ SRST
     ``nvdimm=on|off``
         Enables or disables NVDIMM support. The default is off.
 
-    ``memory-encryption=``
+    ``memory-encryption=<id>``
         Memory encryption object to use. The default is none.
 
     ``hmat=on|off``
@@ -180,7 +180,7 @@ SRST
 
             -machine cxl-fmw.0.targets.0=cxl.0,cxl-fmw.0.targets.1=cxl.1,cxl-fmw.0.size=128G,cxl-fmw.0.interleave-granularity=512
 
-    ``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
+    ``sgx-epc.0.memdev=<memid>,sgx-epc.0.node=<numaid>``
         Define an SGX EPC section.
 
     ``smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel``
@@ -4530,7 +4530,7 @@ DEF("compat", HAS_ARG, QEMU_OPTION_compat,
     "                Policy for handling unstable management interfaces\n",
     QEMU_ARCH_ALL)
 SRST
-``-compat [deprecated-input=@var{input-policy}][,deprecated-output=@var{output-policy}]``
+``-compat [deprecated-input=<input-policy>][,deprecated-output=<output-policy>]``
     Set policy for handling deprecated management interfaces (experimental):
 
     ``deprecated-input=accept`` (default)
@@ -4546,7 +4546,7 @@ SRST
 
     Limitation: covers only syntactic aspects of QMP.
 
-``-compat [unstable-input=@var{input-policy}][,unstable-output=@var{output-policy}]``
+``-compat [unstable-input=<input-policy>][,unstable-output=<output-policy>]``
     Set policy for handling unstable management interfaces (experimental):
 
     ``unstable-input=accept`` (default)
-- 
2.47.3

Re: [PATCH 3/4] qemu-options.hx: Drop uses of @var

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> A few entries in qemu-options.hx use the syntax "my-option=@var{name}"
> when documenting an option that takes an argument. This syntax isn't
> consistently used, and the documentation generation has no support for
> it: it just appears literally in the HTML output.

TexInfo leftovers?

> Switch these uses to the more common "my-option=<name>". This also
> doesn't have any particular support in the documentation generation
> and so appears literally in the output, but it is a little less odd
> looking to the end-user.

Note for later: rewrite 1 is from KEY=@var{VALUE} to KEY=<VALUE>.

> The other common pattern we have is "my-option=name" with no marking
> at all that the right hand side of the '=' is not literal text;
> using <> seems preferable to me, as it makes it more distinct from
> cases where the right hand side is documenting that only certain
> values are permitted, as in "my-option=on|off".

Rewrite 2 is from KEY=VALUE to KEY=<VALUE>.

> We don't change the uses of @var in the colo-compare documentation,
> as that part deserves a slightly more wide-ranging overhaul that
> is better in its own commit.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  qemu-options.hx | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index ec92723f10..aca9dba8b9 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -36,7 +36,7 @@ DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
>      "                dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n"
>      "                suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
>      "                nvdimm=on|off controls NVDIMM support (default=off)\n"
> -    "                memory-encryption=@var{} memory encryption object to use (default=none)\n"
> +    "                memory-encryption=<id> memory encryption object to use (default=none)\n"

This is rewrite 1, except you additionally make up a missing VALUE.

>      "                hmat=on|off controls ACPI HMAT support (default=off)\n"
>      "                spcr=on|off controls ACPI SPCR support (default=on)\n"
>  #ifdef CONFIG_POSIX
> @@ -100,7 +100,7 @@ SRST
>      ``nvdimm=on|off``
>          Enables or disables NVDIMM support. The default is off.
>  
> -    ``memory-encryption=``
> +    ``memory-encryption=<id>``
>          Memory encryption object to use. The default is none.

This is rewrite 2, except you additionally make up a missing VALUE.

>  
>      ``hmat=on|off``
> @@ -180,7 +180,7 @@ SRST
>  
>              -machine cxl-fmw.0.targets.0=cxl.0,cxl-fmw.0.targets.1=cxl.1,cxl-fmw.0.size=128G,cxl-fmw.0.interleave-granularity=512
>  
> -    ``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
> +    ``sgx-epc.0.memdev=<memid>,sgx-epc.0.node=<numaid>``
>          Define an SGX EPC section.

This is rewrite 1.

>  
>      ``smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel``
> @@ -4530,7 +4530,7 @@ DEF("compat", HAS_ARG, QEMU_OPTION_compat,
>      "                Policy for handling unstable management interfaces\n",
>      QEMU_ARCH_ALL)
>  SRST
> -``-compat [deprecated-input=@var{input-policy}][,deprecated-output=@var{output-policy}]``
> +``-compat [deprecated-input=<input-policy>][,deprecated-output=<output-policy>]``

Rewrite 1.

>      Set policy for handling deprecated management interfaces (experimental):
>  
>      ``deprecated-input=accept`` (default)
> @@ -4546,7 +4546,7 @@ SRST
>  
>      Limitation: covers only syntactic aspects of QMP.
>  
> -``-compat [unstable-input=@var{input-policy}][,unstable-output=@var{output-policy}]``
> +``-compat [unstable-input=<input-policy>][,unstable-output=<output-policy>]``

Rewrite 1.

>      Set policy for handling unstable management interfaces (experimental):
>  
>      ``unstable-input=accept`` (default)

This patch and the next apply rewrite 1 exhaustively.

Not the case for rewrite 2, e.g. there's still

    "                cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]\n"

where the value size is not literal.  Many more.

So, what this patch actually does is rewrite 1 plus add missing values.
Could be separate patches, up to you.  Regardless, the commit message
should match what the patch does.

Re: [PATCH 3/4] qemu-options.hx: Drop uses of @var

[Peter Maydell]

On Mon, 19 Jan 2026 at 14:55, Markus Armbruster <armbru@redhat.com> wrote:
>
> Peter Maydell <peter.maydell@linaro.org> writes:
>
> > A few entries in qemu-options.hx use the syntax "my-option=@var{name}"
> > when documenting an option that takes an argument. This syntax isn't
> > consistently used, and the documentation generation has no support for
> > it: it just appears literally in the HTML output.
>
> TexInfo leftovers?
>
> > Switch these uses to the more common "my-option=<name>". This also
> > doesn't have any particular support in the documentation generation
> > and so appears literally in the output, but it is a little less odd
> > looking to the end-user.
>
> Note for later: rewrite 1 is from KEY=@var{VALUE} to KEY=<VALUE>.

More generally, any uses of @var{} to KEY=<VALUE>.

> > The other common pattern we have is "my-option=name" with no marking
> > at all that the right hand side of the '=' is not literal text;
> > using <> seems preferable to me, as it makes it more distinct from
> > cases where the right hand side is documenting that only certain
> > values are permitted, as in "my-option=on|off".
>
> Rewrite 2 is from KEY=VALUE to KEY=<VALUE>.

This patch is not trying to do any rewrite 2; this part of
the commit message is just noting that we are not consistent
about KEY=<VALUE> currently, and so we had another option for
how to fix the @var{} usage, and explaining why I didn't take
that other option.

> > We don't change the uses of @var in the colo-compare documentation,
> > as that part deserves a slightly more wide-ranging overhaul that
> > is better in its own commit.
> >
> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> > ---
> >  qemu-options.hx | 10 +++++-----
> >  1 file changed, 5 insertions(+), 5 deletions(-)
> >
> > diff --git a/qemu-options.hx b/qemu-options.hx
> > index ec92723f10..aca9dba8b9 100644
> > --- a/qemu-options.hx
> > +++ b/qemu-options.hx
> > @@ -36,7 +36,7 @@ DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
> >      "                dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n"
> >      "                suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
> >      "                nvdimm=on|off controls NVDIMM support (default=off)\n"
> > -    "                memory-encryption=@var{} memory encryption object to use (default=none)\n"
> > +    "                memory-encryption=<id> memory encryption object to use (default=none)\n"
>
> This is rewrite 1, except you additionally make up a missing VALUE.

The key=<value> syntax requires one, or it wouldn't be that syntax.

> >      "                hmat=on|off controls ACPI HMAT support (default=off)\n"
> >      "                spcr=on|off controls ACPI SPCR support (default=on)\n"
> >  #ifdef CONFIG_POSIX
> > @@ -100,7 +100,7 @@ SRST
> >      ``nvdimm=on|off``
> >          Enables or disables NVDIMM support. The default is off.
> >
> > -    ``memory-encryption=``
> > +    ``memory-encryption=<id>``
> >          Memory encryption object to use. The default is none.
>
> This is rewrite 2, except you additionally make up a missing VALUE.

This is just because we changed the memory-encryption suboption
in the --help output text above and so also should fix it up
in the RST docs here.

> This patch and the next apply rewrite 1 exhaustively.
>
> Not the case for rewrite 2, e.g. there's still
>
>     "                cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]\n"
>
> where the value size is not literal.  Many more.
>
> So, what this patch actually does is rewrite 1 plus add missing values.
> Could be separate patches, up to you.  Regardless, the commit message
> should match what the patch does.

I think it does. Perhaps it could be more clearly stated...

-- PMM

Re: [PATCH 3/4] qemu-options.hx: Drop uses of @var

[Peter Maydell]

On Mon, 19 Jan 2026 at 15:06, Peter Maydell <peter.maydell@linaro.org> wrote:
>
> On Mon, 19 Jan 2026 at 14:55, Markus Armbruster <armbru@redhat.com> wrote:
> >
> > Peter Maydell <peter.maydell@linaro.org> writes:
> >
> > > A few entries in qemu-options.hx use the syntax "my-option=@var{name}"
> > > when documenting an option that takes an argument. This syntax isn't
> > > consistently used, and the documentation generation has no support for
> > > it: it just appears literally in the HTML output.
> >
> > TexInfo leftovers?
> >
> > > Switch these uses to the more common "my-option=<name>". This also
> > > doesn't have any particular support in the documentation generation
> > > and so appears literally in the output, but it is a little less odd
> > > looking to the end-user.
> >
> > Note for later: rewrite 1 is from KEY=@var{VALUE} to KEY=<VALUE>.
>
> More generally, any uses of @var{} to KEY=<VALUE>.
>
> > > The other common pattern we have is "my-option=name" with no marking
> > > at all that the right hand side of the '=' is not literal text;
> > > using <> seems preferable to me, as it makes it more distinct from
> > > cases where the right hand side is documenting that only certain
> > > values are permitted, as in "my-option=on|off".
> >
> > Rewrite 2 is from KEY=VALUE to KEY=<VALUE>.
>
> This patch is not trying to do any rewrite 2; this part of
> the commit message is just noting that we are not consistent
> about KEY=<VALUE> currently, and so we had another option for
> how to fix the @var{} usage, and explaining why I didn't take
> that other option.
>
> > > We don't change the uses of @var in the colo-compare documentation,
> > > as that part deserves a slightly more wide-ranging overhaul that
> > > is better in its own commit.
> > >


> > So, what this patch actually does is rewrite 1 plus add missing values.
> > Could be separate patches, up to you.  Regardless, the commit message
> > should match what the patch does.
>
> I think it does. Perhaps it could be more clearly stated...

So if we make the commit message be this:

===begin===
A few entries in qemu-options.hx use the syntax "my-option=@var{name}"
(or @var{} with no name specified) when documenting an option that takes
an argument. This syntax isn't consistently used, and the documentation
generation has no support for it: it just appears literally in the
HTML output.

Switch these uses to the more common "my-option=<name>". This also
doesn't have any particular support in the documentation generation
and so appears literally in the output, but it is a little less odd
looking to the end-user.

The other common pattern we have is "my-option=name" with no marking
at all that the right hand side of the '=' is not literal text;
using <> seems preferable to me, as it makes it more distinct from
cases where the right hand side is documenting that only certain
values are permitted, as in "my-option=on|off". This patch doesn't
do anything about existing uses of this pattern (except in one case
which was so confused as to use "my-option=@var{}" in the --help
output and "my-option=" in the RST output, where we change both
for consistency), but prefers not to add more of them.

We don't change the uses of @var in the colo-compare documentation,
as that part deserves a slightly more wide-ranging overhaul that
is better in its own commit.
===endit===

is that clearer ?

thanks
-- PMM

Re: [PATCH 3/4] qemu-options.hx: Drop uses of @var

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Mon, 19 Jan 2026 at 15:06, Peter Maydell <peter.maydell@linaro.org> wrote:
>>
>> On Mon, 19 Jan 2026 at 14:55, Markus Armbruster <armbru@redhat.com> wrote:
>> >
>> > Peter Maydell <peter.maydell@linaro.org> writes:
>> >
>> > > A few entries in qemu-options.hx use the syntax "my-option=@var{name}"
>> > > when documenting an option that takes an argument. This syntax isn't
>> > > consistently used, and the documentation generation has no support for
>> > > it: it just appears literally in the HTML output.
>> >
>> > TexInfo leftovers?
>> >
>> > > Switch these uses to the more common "my-option=<name>". This also
>> > > doesn't have any particular support in the documentation generation
>> > > and so appears literally in the output, but it is a little less odd
>> > > looking to the end-user.
>> >
>> > Note for later: rewrite 1 is from KEY=@var{VALUE} to KEY=<VALUE>.
>>
>> More generally, any uses of @var{} to KEY=<VALUE>.
>>
>> > > The other common pattern we have is "my-option=name" with no marking
>> > > at all that the right hand side of the '=' is not literal text;
>> > > using <> seems preferable to me, as it makes it more distinct from
>> > > cases where the right hand side is documenting that only certain
>> > > values are permitted, as in "my-option=on|off".
>> >
>> > Rewrite 2 is from KEY=VALUE to KEY=<VALUE>.
>>
>> This patch is not trying to do any rewrite 2; this part of
>> the commit message is just noting that we are not consistent
>> about KEY=<VALUE> currently, and so we had another option for
>> how to fix the @var{} usage, and explaining why I didn't take
>> that other option.

Ah, I didn't get that.

>> > > We don't change the uses of @var in the colo-compare documentation,
>> > > as that part deserves a slightly more wide-ranging overhaul that
>> > > is better in its own commit.
>> > >
>
>
>> > So, what this patch actually does is rewrite 1 plus add missing values.
>> > Could be separate patches, up to you.  Regardless, the commit message
>> > should match what the patch does.
>>
>> I think it does. Perhaps it could be more clearly stated...
>
> So if we make the commit message be this:
>
> ===begin===
> A few entries in qemu-options.hx use the syntax "my-option=@var{name}"
> (or @var{} with no name specified) when documenting an option that takes
> an argument. This syntax isn't consistently used, and the documentation
> generation has no support for it: it just appears literally in the
> HTML output.
>
> Switch these uses to the more common "my-option=<name>". This also
> doesn't have any particular support in the documentation generation
> and so appears literally in the output, but it is a little less odd
> looking to the end-user.
>
> The other common pattern we have is "my-option=name" with no marking
> at all that the right hand side of the '=' is not literal text;
> using <> seems preferable to me, as it makes it more distinct from
> cases where the right hand side is documenting that only certain
> values are permitted, as in "my-option=on|off". This patch doesn't
> do anything about existing uses of this pattern (except in one case
> which was so confused as to use "my-option=@var{}" in the --help
> output and "my-option=" in the RST output, where we change both
> for consistency), but prefers not to add more of them.
>
> We don't change the uses of @var in the colo-compare documentation,
> as that part deserves a slightly more wide-ranging overhaul that
> is better in its own commit.
> ===endit===
>
> is that clearer ?

Yes, it is.

Reviewed-by: Markus Armbruster <armbru@redhat.com>

Thanks!

[PATCH 4/4] qemu-options.hx: Improve formatting in colo-compare docs

[Peter Maydell]

The colo-compare option documentation has some formatting issues: it
uses a "@var{...}" syntax which is not used elsewhere and which is
rendered literally into the HTML documentation.  The bare "@" sign
also results in an unintended 'mailto:' hyperlink.

Rewrite this into the style we seem to use most in the rest of
the command line options, where an option which takes an argument
is written as "my-option=<thing>".

We take the opportunity to make the documentation a little clearer
by splitting up the long paragraph and using preformatted-text
markup for the names of the suboptions.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
As I don't know anything about colo-compare, I may have
accidentally introduced errors here; please check.
---
 qemu-options.hx | 41 +++++++++++++++++++++++++----------------
 1 file changed, 25 insertions(+), 16 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index aca9dba8b9..3883afb484 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -5972,22 +5972,31 @@ SRST
         stored. The file format is libpcap, so it can be analyzed with
         tools such as tcpdump or Wireshark.
 
-    ``-object colo-compare,id=id,primary_in=chardevid,secondary_in=chardevid,outdev=chardevid,iothread=id[,vnet_hdr_support][,notify_dev=id][,compare_timeout=@var{ms}][,expired_scan_cycle=@var{ms}][,max_queue_size=@var{size}]``
-        Colo-compare gets packet from primary\_in chardevid and
-        secondary\_in, then compare whether the payload of primary packet
-        and secondary packet are the same. If same, it will output
-        primary packet to out\_dev, else it will notify COLO-framework to do
-        checkpoint and send primary packet to out\_dev. In order to
-        improve efficiency, we need to put the task of comparison in
-        another iothread. If it has the vnet\_hdr\_support flag,
-        colo compare will send/recv packet with vnet\_hdr\_len.
-        The compare\_timeout=@var{ms} determines the maximum time of the
-        colo-compare hold the packet. The expired\_scan\_cycle=@var{ms}
-        is to set the period of scanning expired primary node network packets.
-        The max\_queue\_size=@var{size} is to set the max compare queue
-        size depend on user environment.
-        If user want to use Xen COLO, need to add the notify\_dev to
-        notify Xen colo-frame to do checkpoint.
+    ``-object colo-compare,id=<id>,primary_in=<chardevid>,secondary_in=<chardevid>,outdev=<chardevid>,iothread=<id>[,vnet_hdr_support][,notify_dev=<id>][,compare_timeout=<time_ms>][,expired_scan_cycle=<time_ms>][,max_queue_size=<maxsize>]``
+        Colo-compare gets packets from the chardev backends specified by
+        ``primary_in`` and ``secondary_in``, and compares whether the payloads
+        of the primary packet and the secondary packet are the same.
+        If they match, it will output the primary packet to the chardev
+        backend specified by ``outdev``; otherwise it will notify COLO-framework
+        to do a checkpoint and send the primary packet to ``outdev``.
+
+        In order to improve efficiency, we need to put the task of comparison in
+        another iothread; the ``iothread`` option specifies that iothread object
+        (which your commandline should create).
+
+        The ``vnet_hdr_support`` flag tells
+        colo compare to pass the vnet header length when it sends and receives packets.
+
+        The ``compare_timeout`` option sets the maximum time that
+        colo-compare will hold the packet for, in ms.
+
+        The ``expired_scan_cycle`` option sets the period of scanning expired
+        primary node network packets, in ms.
+
+        The ``max_queue_size`` option sets the max compare queue size.
+
+        If you want to use Xen COLO, you need to specify ``notify_dev`` to
+        tell colo-compare how to notify Xen colo-frame to do a checkpoint.
 
         COLO-compare must be used with the help of filter-mirror,
         filter-redirector and filter-rewriter.
-- 
2.47.3

Re: [PATCH 4/4] qemu-options.hx: Improve formatting in colo-compare docs

[Zhang Chen]

On Thu, Jan 15, 2026 at 10:26 PM Peter Maydell <peter.maydell@linaro.org> wrote:
>
> The colo-compare option documentation has some formatting issues: it
> uses a "@var{...}" syntax which is not used elsewhere and which is
> rendered literally into the HTML documentation.  The bare "@" sign
> also results in an unintended 'mailto:' hyperlink.
>
> Rewrite this into the style we seem to use most in the rest of
> the command line options, where an option which takes an argument
> is written as "my-option=<thing>".
>
> We take the opportunity to make the documentation a little clearer
> by splitting up the long paragraph and using preformatted-text
> markup for the names of the suboptions.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> As I don't know anything about colo-compare, I may have
> accidentally introduced errors here; please check.

The format is more readable, LGTM.
Reviewed-by: Zhang Chen <zhangckid@gmail.com>

> ---
>  qemu-options.hx | 41 +++++++++++++++++++++++++----------------
>  1 file changed, 25 insertions(+), 16 deletions(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index aca9dba8b9..3883afb484 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -5972,22 +5972,31 @@ SRST
>          stored. The file format is libpcap, so it can be analyzed with
>          tools such as tcpdump or Wireshark.
>
> -    ``-object colo-compare,id=id,primary_in=chardevid,secondary_in=chardevid,outdev=chardevid,iothread=id[,vnet_hdr_support][,notify_dev=id][,compare_timeout=@var{ms}][,expired_scan_cycle=@var{ms}][,max_queue_size=@var{size}]``
> -        Colo-compare gets packet from primary\_in chardevid and
> -        secondary\_in, then compare whether the payload of primary packet
> -        and secondary packet are the same. If same, it will output
> -        primary packet to out\_dev, else it will notify COLO-framework to do
> -        checkpoint and send primary packet to out\_dev. In order to
> -        improve efficiency, we need to put the task of comparison in
> -        another iothread. If it has the vnet\_hdr\_support flag,
> -        colo compare will send/recv packet with vnet\_hdr\_len.
> -        The compare\_timeout=@var{ms} determines the maximum time of the
> -        colo-compare hold the packet. The expired\_scan\_cycle=@var{ms}
> -        is to set the period of scanning expired primary node network packets.
> -        The max\_queue\_size=@var{size} is to set the max compare queue
> -        size depend on user environment.
> -        If user want to use Xen COLO, need to add the notify\_dev to
> -        notify Xen colo-frame to do checkpoint.
> +    ``-object colo-compare,id=<id>,primary_in=<chardevid>,secondary_in=<chardevid>,outdev=<chardevid>,iothread=<id>[,vnet_hdr_support][,notify_dev=<id>][,compare_timeout=<time_ms>][,expired_scan_cycle=<time_ms>][,max_queue_size=<maxsize>]``
> +        Colo-compare gets packets from the chardev backends specified by
> +        ``primary_in`` and ``secondary_in``, and compares whether the payloads
> +        of the primary packet and the secondary packet are the same.
> +        If they match, it will output the primary packet to the chardev
> +        backend specified by ``outdev``; otherwise it will notify COLO-framework
> +        to do a checkpoint and send the primary packet to ``outdev``.
> +
> +        In order to improve efficiency, we need to put the task of comparison in
> +        another iothread; the ``iothread`` option specifies that iothread object
> +        (which your commandline should create).
> +
> +        The ``vnet_hdr_support`` flag tells
> +        colo compare to pass the vnet header length when it sends and receives packets.
> +
> +        The ``compare_timeout`` option sets the maximum time that
> +        colo-compare will hold the packet for, in ms.
> +
> +        The ``expired_scan_cycle`` option sets the period of scanning expired
> +        primary node network packets, in ms.
> +
> +        The ``max_queue_size`` option sets the max compare queue size.
> +
> +        If you want to use Xen COLO, you need to specify ``notify_dev`` to
> +        tell colo-compare how to notify Xen colo-frame to do a checkpoint.
>
>          COLO-compare must be used with the help of filter-mirror,
>          filter-redirector and filter-rewriter.
> --
> 2.47.3
>

Re: [PATCH 0/4] docs: Remove bogus mailto links, minor cleanups

[Alex Bennée]

Peter Maydell <peter.maydell@linaro.org> writes:

> I noticed while reviewing a patch to add documentation for
> a new Arm board that an unescaped '@' character resulted in
> an unintended mailto: hyperlink. This prompted me to grep
> to see if we had any others of those, which we do. This
> series fixes them, plus some other things I noticed along
> the way.

For series:

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: [PATCH 0/4] docs: Remove bogus mailto links, minor cleanups

[Zhang Chen]

On Thu, Jan 15, 2026 at 10:26 PM Peter Maydell <peter.maydell@linaro.org> wrote:
>
> I noticed while reviewing a patch to add documentation for
> a new Arm board that an unescaped '@' character resulted in
> an unintended mailto: hyperlink. This prompted me to grep
> to see if we had any others of those, which we do. This
> series fixes them, plus some other things I noticed along
> the way.
>
> The first patch cleans up some awkward rendering in the
> xilinx-zynq-a9 board docs, including dropping a hex
> address that was triggering a mailto: hyperlink.
>
> Patch 2 is all the easy cases which we can just escape
> or put into ``...`` preformatted text.
>
> Patch 3 removes some uses of "@var{...}" in qemu-options.hx
> which may be there because the authors had the impression
> that that would be rendered into italics -- it isn't.
> I've replaced them with uses of "<...>" as the most
> common way we currently mark up "my-option=<something>".
> These aren't mis-rendering as mailto links because they
> all happen to already be in preformatted text.
>
> Patch 4 makes a bigger cleanup to the colo-compare
> option docs: it also uses "@var{...}" and here it is
> causing mailto links to be generated.
>

For this series:
Reviewed-by: Zhang Chen <zhangckid@gmail.com>


> thanks
> -- PMM
>
> Peter Maydell (4):
>   docs/system/arm/xlnx-zynq.rst: Improve docs rendering
>   docs: avoid unintended mailto: hyperlinks
>   qemu-options.hx: Drop uses of @var
>   qemu-options.hx: Improve formatting in colo-compare docs
>
>  docs/devel/submitting-a-patch.rst     |  2 +-
>  docs/system/arm/xlnx-zynq.rst         | 51 ++++++++++++++-------------
>  docs/system/device-url-syntax.rst.inc |  4 +--
>  docs/system/vnc-security.rst          |  6 ++--
>  qemu-options.hx                       | 51 ++++++++++++++++-----------
>  5 files changed, 63 insertions(+), 51 deletions(-)
>
> --
> 2.47.3
>