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

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
>

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