docs: Rewrite a few awkward sections

Address several oddities, and bring them in line with the style
used for the vast majority of our documentation. In a couple of
cases, some of the possible values for an attribute were listed
with :since: information matching that off the attribute itself,
making it redundant.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>

docs/formatdomain.rst

@@ -50,9 +50,10 @@ General metadata
    The content of the ``uuid`` element provides a globally unique identifier for
    the virtual machine. The format must be RFC 4122 compliant, eg
    ``3e3fce45-4f53-4fa7-bb32-11f34168b82b``. If omitted when defining/creating a
-   new machine, a random UUID is generated. It is also possible to provide the
+   new machine, a random UUID is generated. :since:`Since 0.0.1`
-   UUID via a `SMBIOS System Information`_ specification. :since:`Since 0.0.1,
+
-   sysinfo since 0.8.7`
+   :since:`Since 0.8.7`, it is also possible to provide the UUID via a
+   `SMBIOS System Information`_ specification.
 ``genid``
    :since:`Since 4.4.0` , the ``genid`` element can be used to add a Virtual
    Machine Generation ID which exposes a 128-bit, cryptographically random,
@@ -338,8 +339,8 @@ them in production.
    This element has attribute ``useserial`` with possible values ``yes`` or
    ``no``. It enables or disables Serial Graphics Adapter which allows users to
    see BIOS messages on a serial port. Therefore, one needs to have `Serial port`_
-   defined. :since:`Since 0.9.4` . :since:`Since
+   defined. :since:`Since 0.9.4`.
-   0.10.2 (QEMU only)` there is another attribute, ``rebootTimeout`` that
+   The ``rebootTimeout`` attribute (:since:`since 0.10.2 (QEMU only)`)
    controls whether and after how long the guest should start booting again in
    case the boot fails (according to BIOS). The value is in milliseconds with
    maximum of ``65535`` and special value ``-1`` disables the reboot.
@@ -3285,20 +3286,23 @@ paravirtualized driver is specified via the ``disk`` element.
       "qcow2", and "qed".
    -  The optional ``cache`` attribute controls the cache mechanism, possible
       values are "default", "none", "writethrough", "writeback", "directsync"
-      (like "writethrough", but it bypasses the host page cache) and "unsafe"
+      (:since:`since 0.9.5`; like "writethrough", but it bypasses the host page
-      (host may cache all disk io, and sync requests from guest are ignored).
+      cache) and "unsafe" (:since:`since 0.9.7`; host may cache all disk io,
-      :since:`Since 0.6.0, "directsync" since 0.9.5, "unsafe" since 0.9.7`
+      and sync requests from guest are ignored).
+      :since:`Since 0.6.0`
    -  The optional ``error_policy`` attribute controls how the hypervisor will
       behave on a disk read or write error, possible values are "stop",
-      "report", "ignore", and "enospace". :since:`Since 0.8.0, "report" since
+      "report" (:since:`since 0.9.7`), "ignore", and "enospace".
-      0.9.7` The default is left to the discretion of the hypervisor. There is
+      The default is left to the discretion of the hypervisor.
-      also an optional ``rerror_policy`` that controls behavior for read errors
+      :since:`Since 0.8.0`.
-      only. :since:`Since 0.9.7` . If no rerror_policy is given, error_policy is
+   -  The optional ``rerror_policy`` attribute controls behavior for read
+      errors only. If no rerror_policy is given, error_policy is
       used for both read and write errors. If rerror_policy is given, it
       overrides the ``error_policy`` for read errors. Also note that "enospace"
       is not a valid policy for read errors, so if ``error_policy`` is set to
       "enospace" and no ``rerror_policy`` is given, the read error policy will
       be left at its default.
+      :since:`Since 0.9.7`
    -  The optional ``io`` attribute controls specific policies on I/O; qemu
       guests support "threads" and "native" :since:`Since 0.8.8` , io_uring
       :since:`Since 6.3.0 (QEMU 5.0)` .
@@ -4253,9 +4257,9 @@ Host device assignment
 USB / PCI / SCSI devices
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-USB, PCI and SCSI devices attached to the host can be passed through to the
+USB (:since:`since 0.4.4`), PCI (:since:`since 0.6.0, KVM only`) and
-guest using the ``hostdev`` element. :since:`since after 0.4.4 for USB, 0.6.0
+SCSI (:since:`since 1.0.6, KVM only`) devices attached to the host can be
-for PCI (KVM only) and 1.0.6 for SCSI (KVM only)` :
+passed through to the guest using the ``hostdev`` element.
 
 ::
 
@@ -5314,11 +5318,10 @@ requires QEMU 5.1.0 or newer)`
 Teaming a virtio/hostdev NIC pair
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-:since:`Since 6.1.0 (QEMU and KVM only, requires QEMU 4.2.0 or newer and a guest
+:since:`Since 6.1.0 (QEMU and KVM only)`, the ``<teaming>`` element of two
-virtio-net driver supporting the "failover" feature, such as the one included in
+interfaces can be used to connect them as a team/bond device in the guest.
-Linux kernel 4.18 and newer)` The ``<teaming>`` element of two interfaces can
+This requires a guest virtio-net driver supporting the "failover" feature,
-be used to connect them as a team/bond device in the guest (assuming proper
+such as the one included in Linux 4.18.
-support in the hypervisor and the guest network driver).
 
 ::
 
@@ -5917,11 +5920,12 @@ Setting VLAN tag (on supported network types only)
 If (and only if) the network connection used by the guest supports VLAN tagging
 transparent to the guest, an optional ``<vlan>`` element can specify one or more
 VLAN tags to apply to the guest's network traffic :since:`Since 0.10.0` .
-Network connections that support guest-transparent VLAN tagging include 1)
+
-type='bridge' interfaces connected to an Open vSwitch bridge :since:`Since
+Network connections that support guest-transparent VLAN tagging include
-0.10.0` , 2) SRIOV Virtual Functions (VF) used via type='hostdev' (direct device
+``type='bridge'`` interfaces connected to an Open vSwitch bridge, SRIOV
-assignment) :since:`Since 0.10.0` , and 3) SRIOV VFs used via type='direct' with
+Virtual Functions (VF) used via ``type='hostdev'`` (direct device assignment)
-mode='passthrough' (macvtap "passthru" mode) :since:`Since 1.3.5` . All other
+and, :since:`since 1.3.5`, SRIOV VFs used via ``type='direct'`` with
+``mode='passthrough'`` (macvtap "passthru" mode). All other
 connection types, including standard linux bridges and libvirt's own virtual
 networks, **do not** support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches
 provide their own way (outside of libvirt) to tag guest traffic onto a specific
@@ -8034,9 +8038,10 @@ Example: usage of the TPM passthrough device
 
 The emulator device type gives access to a TPM emulator providing TPM
 functionality for each VM. QEMU talks to it over a Unix socket. With the
-emulator device type each guest gets its own private TPM. :since:`'emulator'
+emulator device type each guest gets its own private TPM. :since:`Since 4.5.0`
-since 4.5.0` The state of the TPM emulator can be encrypted by providing an
+
-``encryption`` element. :since:`'encryption' since 5.6.0`
+:since:`Since 5.6.0`, the state of the TPM emulator can be encrypted by
+providing an ``encryption`` element.
 
 Example: usage of the TPM Emulator
 
@@ -8604,15 +8609,15 @@ Security label
 --------------
 
 The ``seclabel`` element allows control over the operation of the security
-drivers. There are three basic modes of operation, 'dynamic' where libvirt
+drivers. There are three basic modes of operation, 'dynamic'
-automatically generates a unique security label, 'static' where the
+(:since:`since 0.6.1`) where libvirt automatically generates a unique security
-application/administrator chooses the labels, or 'none' where confinement is
+label, 'static' (:since:`since 0.6.2`) where the application/administrator
+chooses the labels, or 'none' (:since:`since 0.9.10`) where confinement is
 disabled. With dynamic label generation, libvirt will always automatically
 relabel any resources associated with the virtual machine. With static label
 assignment, by default, the administrator or application must ensure labels are
 set correctly on any resources, however, automatic relabeling can be enabled if
-desired. :since:`'dynamic' since 0.6.1, 'static' since 0.6.2, and 'none' since
+desired.
-0.9.10.`
 
 If more than one security driver is used by libvirt, multiple ``seclabel`` tags
 can be used, one for each driver and the security driver referenced by each tag

docs/formatnetwork.rst

@@ -489,9 +489,7 @@ follows, where accepted values for each attribute is an integer number.
    ``peak`` and ``burst`` attributes still require ``average``. Currently, the
    Linux kernel doesn't allow ingress qdiscs to have any classes therefore
    ``floor`` can be applied only on ``inbound`` and not ``outbound``.
-
+   :since:`Since 1.0.1`
-Attributes ``average``, ``peak``, and ``burst`` are available :since:`since
-0.9.4` , while the ``floor`` attribute is available :since:`since 1.0.1` .
 
 Setting VLAN tag (on supported network types only)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -519,11 +517,12 @@ Setting VLAN tag (on supported network types only)
 If (and only if) the network connection used by the guest supports VLAN tagging
 transparent to the guest, an optional ``<vlan>`` element can specify one or more
 VLAN tags to apply to the guest's network traffic :since:`Since 0.10.0` .
-Network connections that support guest-transparent VLAN tagging include 1)
+
-type='bridge' interfaces connected to an Open vSwitch bridge :since:`Since
+Network connections that support guest-transparent VLAN tagging include
-0.10.0` , 2) SRIOV Virtual Functions (VF) used via type='hostdev' (direct device
+``type='bridge'`` interfaces connected to an Open vSwitch bridge, SRIOV
-assignment) :since:`Since 0.10.0` , and 3) SRIOV VFs used via type='direct' with
+Virtual Functions (VF) used via ``type='hostdev'`` (direct device assignment)
-mode='passthrough' (macvtap "passthru" mode) :since:`Since 1.3.5` . All other
+and, :since:`since 1.3.5`, SRIOV VFs used via ``type='direct'`` with
+``mode='passthrough'`` (macvtap "passthru" mode). All other
 connection types, including standard linux bridges and libvirt's own virtual
 networks, **do not** support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches
 provide their own way (outside of libvirt) to tag guest traffic onto a specific
@@ -844,12 +843,13 @@ of 'route' or 'nat'.
          The optional ``bootp`` element specifies BOOTP options to be provided
          by the DHCP server for IPv4 only. Two attributes are supported:
          ``file`` is mandatory and gives the file to be used for the boot image;
-         ``server`` is optional and gives the address of the TFTP server from
+         ``server`` (:since:`since 0.7.3`) is optional and
+         gives the address of the TFTP server from
          which the boot image will be fetched. ``server`` defaults to the same
          host that runs the DHCP server, as is the case when the ``tftp``
          element is used. The BOOTP options currently have to be the same for
          all address ranges and statically assigned addresses. :since:`Since
-         0.7.1` (``server`` :since:`since 0.7.3` )
+         0.7.1`
 
       Optionally, ``range`` and ``host`` elements can have ``lease`` child
       element which specifies the lease time through it's attributes ``expiry``

docs/formatnwfilter.rst

@@ -472,13 +472,14 @@ A traffic filtering rule starts with the ``rule`` node. This node may contain up
 to three attributes
 
 -  action -- mandatory; must either be ``drop`` (matching the rule silently
-   discards the packet with no further analysis), ``reject`` (matching the rule
+   discards the packet with no further analysis), ``reject``
-   generates an ICMP reject message with no further analysis) :since:`(since
+   (:since:`since 0.9.0`; matching the rule generates an ICMP reject message
-   0.9.0)` , ``accept`` (matching the rule accepts the packet with no further
+   with no further analysis),
-   analysis), ``return`` (matching the rule passes this filter, but returns
+   ``accept`` (matching the rule accepts the packet with no further
-   control to the calling filter for further analysis) :since:`(since 0.9.7)` ,
+   analysis), ``return`` (:since:`since 0.9.7`; matching the rule passes this
-   or ``continue`` (matching the rule goes on to the next rule for further
+   filter, but returns control to the calling filter for further analysis),
-   analysis) :since:`(since 0.9.7)` .
+   or ``continue`` (:since:`since 0.9.7`; matching the rule goes on to the next
+   rule for further analysis).
 
 -  direction -- mandatory; must either be ``in``, ``out`` or ``inout`` if the
    rule is for incoming, outgoing or incoming-and-outgoing traffic
@@ -1600,8 +1601,8 @@ Second example custom filter
 
 In this example we now want to build a similar filter as in the example above,
 but extend the list of requirements with an ftp server located inside the VM.
-Further, we will be using features that have been added in :since:`version
+Further, we will be using features that have been available
-0.8.5` . The requirements for this filter are:
+:since:`since 0.8.5`. The requirements for this filter are:
 
 -  prevents a VM's interface from MAC, IP and ARP spoofing