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.3Peter 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.
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
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
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!
© 2016 - 2026 Red Hat, Inc.