On Mon, 19 Jan 2026 at 15:06, Peter Maydell <[email protected]> wrote:
>
> 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.
> > >
> > 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
