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

[Markus Armbruster <armbru@redhat.com>]

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>.

> 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.