syntax-check: Enforce <code> inside <dt> elements

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.

diff --git a/cfg.mk b/cfg.mk
index cc5ea9ee1da692ff24088267ffd33dc3c73d51cf..b277db184a63cfb633f82a1147b177d39399c040 100644 (file)
--- 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 c3ab516fa4c728dbcf1e49704a910fe4324fa5cf..8c66a9cb4f8f2b7b4523948a75832a30431308ad 100644 (file)
--- 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 ace157721f63f8bbe6d4aa745165c995ed0d981d..638fdae6d0f2a4cc9101ba37a3e82b88d1643388 100644 (file)
--- 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