On Mon, 19 Jan 2026 at 14:55, Markus Armbruster <[email protected]> wrote:
>
> Peter Maydell <[email protected]> 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 <[email protected]>
> > ---
> > 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
