Commit 61b070cf20b5 cleaned up a number of cases where the <dt> element was used to document symbols, but the symbol itself was not inside a <code> element. To make sure we don't end up having to clean up again a few months from now, introduce a syntax-check rule that can spot such mistakes. All existing exceptions are marked as such, with either file or line granularity depending on the case. --- cfg.mk | 14 ++++++++++++++ docs/formatsnapshot.html.in | 6 +++--- docs/remote.html.in | 2 +- 3 files changed, 18 insertions(+), 4 deletions(-) diff --git a/cfg.mk b/cfg.mk index cc5ea9e..b277db1 100644 --- a/cfg.mk +++ b/cfg.mk @@ -1046,6 +1046,17 @@ sc_gettext_init: halt='the above files do not call virGettextInitialize' \ $(_sc_search_regexp) +# <dt> is mostly used to document symbols, in which case it should contain +# a <code> element. The regular expression below trades speed and readability +# for accuracy, and won't catch someone trying to stick a <canvas> inside a +# <dt>, but that's what code reviews are for :) +sc_prohibit_dt_without_code: + @prohibit='<dt>([^<]|<[^c])' \ + exclude='exempt from syntax-check' \ + in_vc_files='docs/.*$$' \ + halt='Use <code> inside <dt> when documenting symbols' \ + $(_sc_search_regexp) + # We don't use this feature of maint.mk. prev_version_file = /dev/null @@ -1282,3 +1293,6 @@ exclude_file_name_regexp--sc_prohibit_not_streq = \ exclude_file_name_regexp--sc_prohibit_not_strneq = \ ^tests/.*\.[ch]$$ + +exclude_file_name_regexp--sc_prohibit_dt_without_code = \ + ^docs/(newapi\.xsl|(apps|contact)\.html\.in)$$ diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in index c3ab516..8c66a9c 100644 --- a/docs/formatsnapshot.html.in +++ b/docs/formatsnapshot.html.in @@ -12,7 +12,7 @@ There are several types of snapshots: </p> <dl> - <dt>disk snapshot</dt> + <dt>disk snapshot</dt> <!-- exempt from syntax-check --> <dd>Contents of disks (whether a subset or all disks associated with the domain) are saved at a given point of time, and can be restored back to that state. On a running guest, a disk @@ -26,14 +26,14 @@ since the snapshot in a single file) and external (the snapshot is one file, and the changes since the snapshot are in another file).</dd> - <dt>memory state (or VM state)</dt> + <dt>memory state (or VM state)</dt> <!-- exempt from syntax-check --> <dd>Tracks only the state of RAM and all other resources in use by the VM. If the disks are unmodified between the time a VM state snapshot is taken and restored, then the guest will resume in a consistent state; but if the disks are modified externally in the meantime, this is likely to lead to data corruption.</dd> - <dt>system checkpoint</dt> + <dt>system checkpoint</dt> <!-- exempt from syntax-check --> <dd>A combination of disk snapshots for all disks as well as VM memory state, which can be used to resume the guest from where it left off with symptoms similar to hibernation (that is, TCP diff --git a/docs/remote.html.in b/docs/remote.html.in index ace1577..638fdae 100644 --- a/docs/remote.html.in +++ b/docs/remote.html.in @@ -712,7 +712,7 @@ cp clientcert.pem /etc/pki/libvirt/clientcert.pem <a name="Remote_TLS_troubleshooting">Troubleshooting TLS certificate problems</a> </h4> <dl> - <dt> failed to verify client's certificate </dt> + <dt>failed to verify client's certificate</dt> <!-- exempt from syntax-check --> <dd> <p> On the server side, run the libvirtd server with -- 2.5.5

When describing attributes and elements, we mostly stick to a certain pattern; however, there are a few cases when the information is not presented in the usual way. Since there doesn't seem to be any reason not to follow the tried and true formula, rework those bits to fit the rest of the documentation. --- docs/formatdomain.html.in | 193 ++++++++++++++++++++++++--------------------- docs/formatnetwork.html.in | 7 +- 2 files changed, 105 insertions(+), 95 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index a9c657d..a3cf866 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -2013,20 +2013,19 @@ <dl> <dt><code>disk</code></dt> - <dd>The <code>disk</code> element is the main container for describing - disks (<span class="since">since 0.0.3</span>). + <dd>The <code>disk</code> element is the main container for + describing disks and supports the following attributes: <dl> - <dt><code>type</code> attribute - <span class="since">since 0.0.3</span></dt> + <dt><code>type</code></dt> <dd> Valid values are "file", "block", "dir" (<span class="since">since 0.7.5</span>), "network" (<span class="since">since 0.8.7</span>), or "volume" (<span class="since">since 1.0.5</span>) and refer to the underlying source for the disk. + <span class="since">Since 0.0.3</span> </dd> - <dt><code>device</code> attribute - <span class="since">since 0.1.4</span></dt> + <dt><code>device</code></dt> <dd> Indicates how the disk is to be exposed to the guest OS. Possible values for this attribute are "floppy", "disk", "cdrom", and "lun", @@ -2046,10 +2045,10 @@ but never for individual partitions or LVM partitions (in those cases, the kernel will reject the generic SCSI commands, making it identical to device='disk'). + <span class="since">Since 0.1.4</span> </p> </dd> - <dt><code>rawio</code> attribute - <span class="since">since 0.9.10</span></dt> + <dt><code>rawio</code></dt> <dd> Indicates whether the disk needs rawio capability. Valid settings are "yes" or "no" (default is "no"). If any one disk @@ -2063,17 +2062,17 @@ To confine the capability as much as possible for QEMU driver as this stage, <code>sgio</code> is recommended, it's more secure than <code>rawio</code>. + <span class="since">Since 0.9.10</span> </dd> - <dt><code>sgio</code> attribute - <span class="since">since 1.0.2</span></dt> + <dt><code>sgio</code></dt> <dd> If supported by the hypervisor and OS, indicates whether unprivileged SG_IO commands are filtered for the disk. Valid settings are "filtered" or "unfiltered" where the default is "filtered". Only available when the <code>device</code> is 'lun'. + <span class="since">Since 1.0.2</span> </dd> - <dt><code>snapshot</code> attribute - <span class="since">since 0.9.5</span></dt> + <dt><code>snapshot</code></dt> <dd> Indicates the default behavior of the disk during disk snapshots: "internal" requires a file format such as qcow2 that can store @@ -2087,6 +2086,7 @@ Not all snapshot modes are supported; for example, <code>snapshot='yes'</code> with a transient disk generally does not make sense. + <span class="since">Since 0.9.5</span> </dd> </dl> </dd> @@ -2094,26 +2094,25 @@ <dd>Representation of the disk <code>source</code> depends on the disk <code>type</code> attribute value as follows: <dl> - <dt><code>type='file'</code> - <span class="since">since 0.0.3</span></dt> + <dt><code>file</code></dt> <dd> The <code>file</code> attribute specifies the fully-qualified path to the file holding the disk. + <span class="since">Since 0.0.3</span> </dd> - <dt><code>type='block'</code> - <span class="since">since 0.0.3</span></dt> + <dt><code>block</code></dt> <dd> The <code>dev</code> attribute specifies the fully-qualified path to the host device to serve as the disk. + <span class="since">Since 0.0.3</span> </dd> - <dt><code>type='dir'</code> - <span class="since">since 0.7.5</span></dt> + <dt><code>dir</code></dt> <dd> The <code>dir</code> attribute specifies the fully-qualified path to the directory to use as the disk. + <span class="since">Since 0.7.5</span> </dd> - <dt><code>type='network'</code> - <span class="since">since 0.8.7</span></dt> + <dt><code>network</code></dt> <dd> The <code>protocol</code> attribute specifies the protocol to access to the requested image. Possible values are "nbd", @@ -2127,9 +2126,9 @@ target's name by a slash (e.g., <code>iqn.2013-07.com.example:iscsi-pool/1</code>). If not specified, the default LUN is zero. + <span class="since">Since 0.8.7</span> </dd> - <dt><code>type='volume'</code> - <span class="since">since 1.0.5</span></dt> + <dt><code>volume</code></dt> <dd> The underlying disk source is represented by attributes <code>pool</code> and <code>volume</code>. Attribute @@ -2163,6 +2162,7 @@ of 'lun' with respect to how the LUN is presented to and may used by the guest. + <span class="since">Since 1.0.5</span> </p> </dd> </dl> @@ -2303,16 +2303,16 @@ each file of the chain (files created by libvirt satisfy this property, but using existing external files for snapshot or block copy operations requires the end user to pre-create the - file correctly). The following attributes and sub-elements are + file correctly). The following attributes are supported in <code>backingStore</code>: <dl> - <dt><code>type</code> attribute</dt> + <dt><code>type</code></dt> <dd> The <code>type</code> attribute represents the type of disk used by the backing store, see disk type attribute above for more details and possible values. </dd> - <dt><code>index</code> attribute</dt> + <dt><code>index</code></dt> <dd> This attribute is only valid in output (and ignored on input) and it can be used to refer to a specific part of the disk chain when @@ -2321,20 +2321,23 @@ <code>vda[2]</code> refers to the backing store with <code>index='2'</code> of the disk with <code>vda</code> target. </dd> - <dt><code>format</code> sub-element</dt> + </dl> + Moreover, <code>backingStore</code> supports the following sub-elements: + <dl> + <dt><code>format</code></dt> <dd> The <code>format</code> element contains <code>type</code> attribute which specifies the internal format of the backing store, such as <code>raw</code> or <code>qcow2</code>. </dd> - <dt><code>source</code> sub-element</dt> + <dt><code>source</code></dt> <dd> This element has the same structure as the <code>source</code> element in <code>disk</code>. It specifies which file, device, or network location contains the data of the described backing store. </dd> - <dt><code>backingStore</code> sub-element</dt> + <dt><code>backingStore</code></dt> <dd> If the backing store is not self-contained, the next element in the chain is described by nested <code>backingStore</code> @@ -2745,7 +2748,7 @@ <code>source</code>. The possible values are: <dl> - <dt><code>type='mount'</code></dt> + <dt><code>mount</code></dt> <dd> A host directory to mount in the guest. Used by LXC, OpenVZ <span class="since">(since 0.6.2)</span> @@ -2762,23 +2765,23 @@ is immediately triggered for all pages touched during a guest file write operation <span class="since">(since 0.9.10)</span>. </dd> - <dt><code>type='template'</code></dt> + <dt><code>template</code></dt> <dd> OpenVZ filesystem template. Only used by OpenVZ driver. </dd> - <dt><code>type='file'</code></dt> + <dt><code>file</code></dt> <dd> A host file will be treated as an image and mounted in the guest. The filesystem format will be autodetected. Only used by LXC driver. </dd> - <dt><code>type='block'</code></dt> + <dt><code>block</code></dt> <dd> A host block device to mount in the guest. The filesystem format will be autodetected. Only used by LXC driver <span class="since">(since 0.9.5)</span>. </dd> - <dt><code>type='ram'</code></dt> + <dt><code>ram</code></dt> <dd> An in-memory filesystem, using memory from the host OS. The source element has a single attribute <code>usage</code> @@ -2786,7 +2789,7 @@ are specified by the <code>units</code> attribute. Only used by LXC driver. <span class="since"> (since 0.9.13)</span></dd> - <dt><code>type='bind'</code></dt> + <dt><code>bind</code></dt> <dd> A directory inside the guest will be bound to another directory inside the guest. Only used by LXC driver @@ -2800,20 +2803,20 @@ values are: <dl> - <dt><code>accessmode='passthrough'</code></dt> + <dt><code>passthrough</code></dt> <dd> The <code>source</code> is accessed with the permissions of the user inside the guest. This is the default <code>accessmode</code> if one is not specified. <a href="http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.... info</a> </dd> - <dt><code>accessmode='mapped'</code></dt> + <dt><code>mapped</code></dt> <dd> The <code>source</code> is accessed with the permissions of the hypervisor (QEMU process). <a href="http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.... info</a> </dd> - <dt><code>accessmode='squash'</code></dt> + <dt><code>squash</code></dt> <dd> Similar to 'passthrough', the exception is that failure of privileged operations like 'chown' are ignored. This makes a @@ -2912,7 +2915,7 @@ </p> <dl> - <dt><code>type='pci'</code></dt> + <dt><code>pci</code></dt> <dd>PCI addresses have the following additional attributes: <code>domain</code> (a 2-byte hex integer, not currently used by qemu), <code>bus</code> (a hex value between @@ -2927,32 +2930,32 @@ but should be set to 'on' for function 0 of a slot that will have multiple functions used. </dd> - <dt><code>type='drive'</code></dt> + <dt><code>drive</code></dt> <dd>Drive addresses have the following additional attributes: <code>controller</code> (a 2-digit controller number), <code>bus</code> (a 2-digit bus number), <code>target</code> (a 2-digit target number), and <code>unit</code> (a 2-digit unit number on the bus). </dd> - <dt><code>type='virtio-serial'</code></dt> + <dt><code>virtio-serial</code></dt> <dd>Each virtio-serial address has the following additional attributes: <code>controller</code> (a 2-digit controller number), <code>bus</code> (a 2-digit bus number), and <code>slot</code> (a 2-digit slot within the bus). </dd> - <dt><code>type='ccid'</code></dt> + <dt><code>ccid</code></dt> <dd>A CCID address, for smart-cards, has the following additional attributes: <code>bus</code> (a 2-digit bus number), and <code>slot</code> attribute (a 2-digit slot within the bus). <span class="since">Since 0.8.8.</span> </dd> - <dt><code>type='usb'</code></dt> + <dt><code>usb</code></dt> <dd>USB addresses have the following additional attributes: <code>bus</code> (a hex value between 0 and 0xfff, inclusive), and <code>port</code> (a dotted notation of up to four octets, such as 1.2 or 2.1.3.1). </dd> - <dt><code>type='spapr-vio'</code></dt> + <dt><code>spapr-vio</code></dt> <dd>On PowerPC pseries guests, devices can be assigned to the SPAPR-VIO bus. It has a flat 64-bit address space; by convention, devices are generally assigned at a non-zero @@ -2962,7 +2965,7 @@ of the starting register). <span class="since">Since 0.9.9.</span> </dd> - <dt><code>type='ccw'</code></dt> + <dt><code>ccw</code></dt> <dd>s390 guests with a <code>machine</code> value of s390-ccw-virtio use the native CCW bus for I/O devices. CCW bus addresses have the following additional attributes: @@ -2975,7 +2978,7 @@ set to 0xfe. <span class="since">Since 1.0.4</span> </dd> - <dt><code>type='isa'</code></dt> + <dt><code>isa</code></dt> <dd>ISA addresses have the following additional attributes: <code>iobase</code> and <code>irq</code>. <span class="since">Since 1.2.1</span> @@ -3210,7 +3213,7 @@ downstream-port). </p> </dd> - <dt><code>&lt;node&gt;</code></dt> + <dt><code>node</code></dt> <dd> pci-expander-bus controllers can have an optional <code>&lt;node&gt;</code> subelement within @@ -3772,14 +3775,14 @@ </p> <dl> - <dt><code>mode='host'</code></dt> + <dt><code>host</code></dt> <dd>The simplest operation, where the hypervisor relays all requests from the guest into direct access to the host's smartcard via NSS. No other attributes or sub-elements are required. See below about the use of an optional <code>&lt;address&gt;</code> sub-element.</dd> - <dt><code>mode='host-certificates'</code></dt> + <dt><code>host-certificates</code></dt> <dd>Rather than requiring a smartcard to be plugged into the host, it is possible to provide three NSS certificate names residing in a database on the host. These certificates can be @@ -3793,7 +3796,7 @@ when creating the certificates); if not present, it defaults to /etc/pki/nssdb.</dd> - <dt><code>mode='passthrough'</code></dt> + <dt><code>passthrough</code></dt> <dd>Rather than having the hypervisor directly communicate with the host, it is possible to tunnel all requests through a secondary character device to a third-party provider (which may @@ -4557,7 +4560,13 @@ qemu-kvm -net nic,model=? /dev/null <span class="since">virtio-net since 1.0.6 (QEMU and KVM only)</span> <span class="since">vhost-user since 1.2.17 (QEMU and KVM only)</span> </dd> - <dt><code>host</code> offloading options</dt> + </dl> + <p> + Offloading options for the host and guest can be configured using + the following sub-elements: + </p> + <dl> + <dt><code>host</code></dt> <dd> The <code>csum</code>, <code>gso</code>, <code>tso4</code>, <code>tso6</code>, <code>ecn</code> and <code>ufo</code> @@ -4570,7 +4579,7 @@ qemu-kvm -net nic,model=? /dev/null <code>on</code> (default) and <code>off</code>. <span class="since">Since 1.2.13 (QEMU only)</span> </dd> - <dt><code>guest</code> offloading options</dt> + <dt><code>guest</code></dt> <dd> The <code>csum</code>, <code>tso4</code>, <code>tso6</code>, <code>ecn</code> and <code>ufo</code> @@ -5059,7 +5068,7 @@ qemu-kvm -net nic,model=? /dev/null <code>spice</code>, <code>rdp</code> or <code>desktop</code>: </p> <dl> - <dt><code>"sdl"</code></dt> + <dt><code>sdl</code></dt> <dd> <p> This displays a window on the host desktop, it can take 3 optional @@ -5069,7 +5078,7 @@ qemu-kvm -net nic,model=? /dev/null <code>yes</code> or <code>no</code>. </p> </dd> - <dt><code>"vnc"</code></dt> + <dt><code>vnc</code></dt> <dd> <p> Starts a VNC server. The <code>port</code> attribute specifies @@ -5110,7 +5119,7 @@ qemu-kvm -net nic,model=? /dev/null security reasons) <span class="since">Since 1.0.6</span>. </p> </dd> - <dt><code>"spice"</code> <span class="since">Since 0.8.6</span></dt> + <dt><code>spice</code> <span class="since">Since 0.8.6</span></dt> <dd> <p> Starts a SPICE server. The <code>port</code> attribute specifies @@ -5216,7 +5225,7 @@ qemu-kvm -net nic,model=? /dev/null property. (QEMU only, <span class="since">since 1.3.2</span>). </p> </dd> - <dt><code>"rdp"</code></dt> + <dt><code>rdp</code></dt> <dd> <p> Starts a RDP server. The <code>port</code> attribute specifies the @@ -5231,7 +5240,7 @@ qemu-kvm -net nic,model=? /dev/null single connection mode. </p> </dd> - <dt><code>"desktop"</code></dt> + <dt><code>desktop</code></dt> <dd> <p> This value is reserved for VirtualBox domains for the moment. It @@ -6230,29 +6239,27 @@ qemu-kvm -net nic,model=? /dev/null to be used for the domain. The source model is configured using the <code>model</code> attribute. Supported source models are: </p> - <ul> - <li>'random' &mdash; /dev/random (default) or /dev/hwrng - device as source (for now, no other sources are permitted)</li> - <li>'egd' &mdash; a EGD protocol backend</li> - </ul> - </dd> - <dt><code>backend model='random'</code></dt> - <dd> - <p> - This backend type expects a non-blocking character device as input. - The only accepted paths are /dev/random and /dev/hwrng. The file - name is specified as contents of the <code>backend</code> element. - When no file name is specified the hypervisor default is used. - </p> - </dd> - <dt><code>backend model='egd'</code></dt> - <dd> - <p> - This backend connects to a source using the EGD protocol. - The source is specified as a character device. Refer to - <a href='#elementsCharHostInterface'>character device host interface</a> - for more information. - </p> + <dl> + <dt><code>random</code></dt> + <dd> + <p> + This backend type expects a non-blocking character device as + input. The only accepted paths are /dev/random and /dev/hwrng. + The file name is specified as contents of the + <code>backend</code> element. When no file name is specified + the hypervisor default is used. + </p> + </dd> + <dt><code>egd</code></dt> + <dd> + <p> + This backend connects to a source using the EGD protocol. + The source is specified as a character device. Refer to + <a href='#elementsCharHostInterface'>character device host interface</a> + for more information. + </p> + </dd> + </dl> </dd> </dl> @@ -6299,19 +6306,21 @@ qemu-kvm -net nic,model=? /dev/null The <code>backend</code> element specifies the type of TPM device. The following types are supported: </p> - <ul> - <li>'passthrough' &mdash; use the host's TPM device.</li> - </ul> - </dd> - <dt><code>backend type='passthrough'</code></dt> - <dd> - <p> - This backend type requires exclusive access to a TPM device on - the host. - An example for such a device is /dev/tpm0. The fully qualified file - name is specified by path attribute of the <code>source</code> element. - If no file name is specified then /dev/tpm0 is automatically used. - </p> + <dl> + <dt><code>passthrough</code></dt> + <dd> + <p> + Use the host's TPM device. + </p> + <p> + This backend type requires exclusive access to a TPM device on + the host. An example for such a device is /dev/tpm0. The fully + qualified file name is specified by path attribute of the + <code>source</code> element. If no file name is specified then + /dev/tpm0 is automatically used. + </p> + </dd> + </dl> </dd> </dl> diff --git a/docs/formatnetwork.html.in b/docs/formatnetwork.html.in index 6abed8f..50dc751 100644 --- a/docs/formatnetwork.html.in +++ b/docs/formatnetwork.html.in @@ -54,13 +54,14 @@ The format must be RFC 4122 compliant, eg <code>3e3fce45-4f53-4fa7-bb32-11f34168b82b</code>. If omitted when defining/creating a new network, a random UUID is generated. <span class="since">Since 0.3.0</span></dd> - <dt><code>ipv6='yes'</code></dt> - <dd>The new, optional parameter <code>ipv6='yes'</code> enables + <dt><code>ipv6</code></dt> + <dd>When set to <code>yes</code>, the optional parameter + <code>ipv6</code> enables a network definition with no IPv6 gateway addresses specified to have guest-to-guest communications. For further information, see the example below for the example with no gateway addresses. <span class="since">Since 1.0.1</span></dd> - <dt><code>trustGuestRxFilters='yes'</code></dt> + <dt><code>trustGuestRxFilters</code></dt> <dd>The optional parameter <code>trustGuestRxFilters</code> can be used to set that attribute of the same name for each domain interface connected to this network (<span class="since">since -- 2.5.5

Our documentation contains a *lot* of symbols, and due to styling they actually look smaller than the surrounding text. The end result is that quickly scanning the documentation looking for a specific setting doesn't work very well. Make all symbols bold so they stand out more. Suggested-by: John Ferlan <jferlan(a)redhat.com&gt; --- docs/generic.css | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/generic.css b/docs/generic.css index 208e31e..ac39f32 100644 --- a/docs/generic.css +++ b/docs/generic.css @@ -27,6 +27,10 @@ dt { margin-right: 2em; } +dt code { + font-weight: bold; +} + dl dd { margin-left: 2em; margin-right: 2em; -- 2.5.5