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