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

[Markus Armbruster <armbru@redhat.com>]

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!