Specifically:

  * use the correct notation and markup for commands, options
    and arguments;
  * rename arguments meta-variables;
  * document '--help' and '--version' options;
  * use consistent vertical spacing;
  * fix a typo.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
---
 docs/manpages/virt-qemu-run.rst | 53 +++++++++++++++++++--------------
 1 file changed, 31 insertions(+), 22 deletions(-)

diff --git a/docs/manpages/virt-qemu-run.rst b/docs/manpages/virt-qemu-run.rst
index 470de93168..a755b7fda9 100644
--- a/docs/manpages/virt-qemu-run.rst
+++ b/docs/manpages/virt-qemu-run.rst
@@ -11,10 +11,13 @@ Run a standalone QEMU guest
 
 .. contents::
 
+
 SYNOPSIS
 ========
 
-``virt-qemu-run [OPTIONS...] [GUEST-XML]``
+``virt-qemu-run`` [*OPTIONS...*] *GUEST-XML-FILE*
+``virt-qemu-run`` *OPTION*
+
 
 DESCRIPTION
 ===========
@@ -26,50 +29,54 @@ directory tree. When the guest is run with this tool it is invisible
 to libvirtd and thus also invisible to other libvirt tools such as
 virsh.
 
-The virt-qemu-run program will run the QEMU virtual machine, and then
-block until the guest OS shuts down, at which point it will exit.
+The ``virt-qemu-run`` program will run the QEMU virtual machine, and
+then block until the guest OS shuts down, at which point it will
+exit.
 
-If the virt-qemu-run program is interrupted (eg Ctrl-C) it will
-immediately terminate the virtual machine without giving the guest
-OS any opportunity to gracefully shutdown.
+If the ``virt-qemu-run`` program is interrupted (eg Ctrl-C) it will
+immediately terminate the virtual machine without giving the guest OS
+any opportunity to gracefully shutdown.
 
 **NOTE: this tool is currently considered experimental.** Its
 usage and behaviour is still subject to change in future libvirt
 releases. For further information on its usage consult the
 `QEMU driver documentation <https://libvirt.org/drvqemu.html#embedded-driver>`_.
 
+
 OPTIONS
 =======
 
-``GUEST-XML``
+*GUEST-XML-FILE*
 
 The full path to the XML file describing the guest virtual machine
 to be booted.
 
-``-h``, ``--help``
-
-Display the command line help
-
-``-v``, ``--verbose``
-
-Display verbose information about startup
-
-``-r DIR``, ``--root=DIR``
+``-r`` *DIR*, ``--root``\ =\ *DIR*
 
 Specify the root directory to use for storing state associated with
 the virtual machine. The caller is responsible for deleting this
 directory when it is no longer required.
 
 If this parameter is omitted, then a random temporary directory
-will be created, and its contents be automaticlaly deleted at
+will be created, and its contents be automatically deleted at
 VM shutdown.
 
-``-s XML-FILE,VALUE-FILE``, ``--secret=XML-FILE,VALUE-FILE``
+``-s`` *SECRET-XML-FILE*\ ,\ *SECRET-VALUE-FILE*,
+``--secret``\ =\ *SECRET-XML-FILE*\ ,\ *SECRET-VALUE-FILE*
+
+Specify a secret to be loaded into the secret driver.
+*SECRET-XML-FILE* is a path to the XML description of the secret,
+whose UUID should match a secret referenced in the guest domain XML.
+*SECRET-VALUE-FILE* is a path containing the raw value of the secret.
+
+``-h``, ``--help``
+
+Display the command line help
+
+``-v``, ``--verbose``
+
+Display verbose information about startup
 
-Specify a secret to be loaded into the secret driver. The ``XML-FILE``
-is a path to the XML description of the secret, whose UUID should
-match a secret referenced in the guest domain XML. The ``VALUE-FILE``
-is a path containing the raw value of the secret.
 
 EXIT STATUS
 ===========
@@ -77,6 +84,7 @@ EXIT STATUS
 Upon successful shutdown, an exit status of 0 will be set. Upon
 failure a non-zero status will be set.
 
+
 AUTHOR
 ======
 
@@ -113,6 +121,7 @@ This is free software; see the source for copying conditions. There
 is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
 PURPOSE
 
+
 SEE ALSO
 ========
 
-- 
2.31.1

On a Friday in 2021, Andrea Bolognani wrote:
>Specifically:
>
>  * use the correct notation and markup for commands, options
>    and arguments;
>  * rename arguments meta-variables;
>  * document '--help' and '--version' options;
>  * use consistent vertical spacing;
>  * fix a typo.
>
>Signed-off-by: Andrea Bolognani <abologna@redhat.com>
>---
> docs/manpages/virt-qemu-run.rst | 53 +++++++++++++++++++--------------
> 1 file changed, 31 insertions(+), 22 deletions(-)
>
>diff --git a/docs/manpages/virt-qemu-run.rst b/docs/manpages/virt-qemu-run.rst
>index 470de93168..a755b7fda9 100644
>--- a/docs/manpages/virt-qemu-run.rst
>+++ b/docs/manpages/virt-qemu-run.rst
>@@ -11,10 +11,13 @@ Run a standalone QEMU guest
>
> .. contents::
>
>+
> SYNOPSIS
> ========
>
>-``virt-qemu-run [OPTIONS...] [GUEST-XML]``
>+``virt-qemu-run`` [*OPTIONS...*] *GUEST-XML-FILE*
>+``virt-qemu-run`` *OPTION*
>+

This puts them both on the same line in the resulting man page.

Prefixing both lines with '|' fixed that for me:
diff --git a/docs/manpages/virt-qemu-run.rst b/docs/manpages/virt-qemu-run.rst
index a755b7fda9..1bc1a7f6f7 100644
--- a/docs/manpages/virt-qemu-run.rst
+++ b/docs/manpages/virt-qemu-run.rst
@@ -15,8 +15,8 @@ Run a standalone QEMU guest
  SYNOPSIS
  ========

-``virt-qemu-run`` [*OPTIONS...*] *GUEST-XML-FILE*
-``virt-qemu-run`` *OPTION*
+| ``virt-qemu-run`` [*OPTIONS...*] *GUEST-XML-FILE*
+| ``virt-qemu-run`` *OPTION*


  DESCRIPTION



Reviewed-by: Ján Tomko <jtomko@redhat.com>

Jano

On Fri, Dec 10, 2021 at 06:16:06PM +0100, Ján Tomko wrote:
> On a Friday in 2021, Andrea Bolognani wrote:
> > -``virt-qemu-run [OPTIONS...] [GUEST-XML]``
> > +``virt-qemu-run`` [*OPTIONS...*] *GUEST-XML-FILE*
> > +``virt-qemu-run`` *OPTION*
>
> This puts them both on the same line in the resulting man page.

So it does! Great catch, I don't know how I failed to notice.

> Prefixing both lines with '|' fixed that for me:
>
> -``virt-qemu-run`` [*OPTIONS...*] *GUEST-XML-FILE*
> -``virt-qemu-run`` *OPTION*
> +| ``virt-qemu-run`` [*OPTIONS...*] *GUEST-XML-FILE*
> +| ``virt-qemu-run`` *OPTION*

I ended up adopting a slightly different approach: since the only
situations in which you would not pass some mandatory ARGUMENT to the
commands is for '--version' and '--help', which are extremely
widespread and well understood, I've just changed the usage to

  ``command`` [*OPTION*]... *ARGUMENT*

in all manual pages. I think this is a good solution, but if you'd
rather see the version with two separate lines just let me know and I
will prepare a follow-up patch.

Thank you for the review! :)

-- 
Andrea Bolognani / Red Hat / Virtualization