Merge pull request #41342 from samueldr/fix/doc/formatting-oopsies

Fixes doc auto-formatting oopsies

doc/Makefile

@@ -12,6 +12,11 @@ format:
 	find . -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \
 		xmlformat --config-file "$$XMLFORMAT_CONFIG" -i {}
 
+.PHONY: fix-misc-xml
+fix-misc-xml:
+	find . -iname '*.xml' -type f \
+		-exec ../nixos/doc/varlistentry-fixer.rb {} ';'
+
 .PHONY: clean
 clean:
 	rm -f ${MD_TARGETS} .version manual-full.xml

doc/coding-conventions.xml

@@ -312,11 +312,15 @@ args.stdenv.mkDerivation (args // {
 
    <variablelist>
     <varlistentry>
-     <term>If it’s used to support <emphasis>software development</emphasis>:</term>
+     <term>
+      If it’s used to support <emphasis>software development</emphasis>:
+     </term>
      <listitem>
       <variablelist>
        <varlistentry>
-        <term>If it’s a <emphasis>library</emphasis> used by other packages:</term>
+        <term>
+         If it’s a <emphasis>library</emphasis> used by other packages:
+        </term>
         <listitem>
          <para>
           <filename>development/libraries</filename> (e.g.
@@ -325,7 +329,9 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>If it’s a <emphasis>compiler</emphasis>:</term>
+        <term>
+         If it’s a <emphasis>compiler</emphasis>:
+        </term>
         <listitem>
          <para>
           <filename>development/compilers</filename> (e.g.
@@ -334,7 +340,9 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>If it’s an <emphasis>interpreter</emphasis>:</term>
+        <term>
+         If it’s an <emphasis>interpreter</emphasis>:
+        </term>
         <listitem>
          <para>
           <filename>development/interpreters</filename> (e.g.
@@ -343,11 +351,15 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>If it’s a (set of) development <emphasis>tool(s)</emphasis>:</term>
+        <term>
+         If it’s a (set of) development <emphasis>tool(s)</emphasis>:
+        </term>
         <listitem>
          <variablelist>
           <varlistentry>
-           <term>If it’s a <emphasis>parser generator</emphasis> (including lexers):</term>
+           <term>
+            If it’s a <emphasis>parser generator</emphasis> (including lexers):
+           </term>
            <listitem>
             <para>
              <filename>development/tools/parsing</filename> (e.g.
@@ -356,7 +368,9 @@ args.stdenv.mkDerivation (args // {
            </listitem>
           </varlistentry>
           <varlistentry>
-           <term>If it’s a <emphasis>build manager</emphasis>:</term>
+           <term>
+            If it’s a <emphasis>build manager</emphasis>:
+           </term>
            <listitem>
             <para>
              <filename>development/tools/build-managers</filename> (e.g.
@@ -365,7 +379,9 @@ args.stdenv.mkDerivation (args // {
            </listitem>
           </varlistentry>
           <varlistentry>
-           <term>Else:</term>
+           <term>
+            Else:
+           </term>
            <listitem>
             <para>
              <filename>development/tools/misc</filename> (e.g.
@@ -377,7 +393,9 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>Else:</term>
+        <term>
+         Else:
+        </term>
         <listitem>
          <para>
           <filename>development/misc</filename>
@@ -388,7 +406,9 @@ args.stdenv.mkDerivation (args // {
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term>If it’s a (set of) <emphasis>tool(s)</emphasis>:</term>
+     <term>
+      If it’s a (set of) <emphasis>tool(s)</emphasis>:
+     </term>
      <listitem>
       <para>
        (A tool is a relatively small program, especially one intended to be
@@ -396,7 +416,9 @@ args.stdenv.mkDerivation (args // {
       </para>
       <variablelist>
        <varlistentry>
-        <term>If it’s for <emphasis>networking</emphasis>:</term>
+        <term>
+         If it’s for <emphasis>networking</emphasis>:
+        </term>
         <listitem>
          <para>
           <filename>tools/networking</filename> (e.g.
@@ -405,7 +427,9 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>If it’s for <emphasis>text processing</emphasis>:</term>
+        <term>
+         If it’s for <emphasis>text processing</emphasis>:
+        </term>
         <listitem>
          <para>
           <filename>tools/text</filename> (e.g. <filename>diffutils</filename>)
@@ -413,9 +437,9 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>If it’s a <emphasis>system utility</emphasis>, i.e.,
+        <term>
-          something related or essential to the operation of a
+         If it’s a <emphasis>system utility</emphasis>, i.e., something related or essential to the operation of a system:
-          system:</term>
+        </term>
         <listitem>
          <para>
           <filename>tools/system</filename> (e.g. <filename>cron</filename>)
@@ -423,8 +447,9 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>If it’s an <emphasis>archiver</emphasis> (which may
+        <term>
-          include a compression function):</term>
+         If it’s an <emphasis>archiver</emphasis> (which may include a compression function):
+        </term>
         <listitem>
          <para>
           <filename>tools/archivers</filename> (e.g. <filename>zip</filename>,
@@ -433,7 +458,9 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>If it’s a <emphasis>compression</emphasis> program:</term>
+        <term>
+         If it’s a <emphasis>compression</emphasis> program:
+        </term>
         <listitem>
          <para>
           <filename>tools/compression</filename> (e.g.
@@ -442,7 +469,9 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>If it’s a <emphasis>security</emphasis>-related program:</term>
+        <term>
+         If it’s a <emphasis>security</emphasis>-related program:
+        </term>
         <listitem>
          <para>
           <filename>tools/security</filename> (e.g. <filename>nmap</filename>,
@@ -451,7 +480,9 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>Else:</term>
+        <term>
+         Else:
+        </term>
         <listitem>
          <para>
           <filename>tools/misc</filename>
@@ -462,7 +493,9 @@ args.stdenv.mkDerivation (args // {
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term>If it’s a <emphasis>shell</emphasis>:</term>
+     <term>
+      If it’s a <emphasis>shell</emphasis>:
+     </term>
      <listitem>
       <para>
        <filename>shells</filename> (e.g. <filename>bash</filename>)
@@ -470,11 +503,15 @@ args.stdenv.mkDerivation (args // {
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term>If it’s a <emphasis>server</emphasis>:</term>
+     <term>
+      If it’s a <emphasis>server</emphasis>:
+     </term>
      <listitem>
       <variablelist>
        <varlistentry>
-        <term>If it’s a web server:</term>
+        <term>
+         If it’s a web server:
+        </term>
         <listitem>
          <para>
           <filename>servers/http</filename> (e.g.
@@ -483,7 +520,9 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>If it’s an implementation of the X Windowing System:</term>
+        <term>
+         If it’s an implementation of the X Windowing System:
+        </term>
         <listitem>
          <para>
           <filename>servers/x11</filename> (e.g. <filename>xorg</filename> —
@@ -492,7 +531,9 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>Else:</term>
+        <term>
+         Else:
+        </term>
         <listitem>
          <para>
           <filename>servers/misc</filename>
@@ -503,7 +544,9 @@ args.stdenv.mkDerivation (args // {
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term>If it’s a <emphasis>desktop environment</emphasis>:</term>
+     <term>
+      If it’s a <emphasis>desktop environment</emphasis>:
+     </term>
      <listitem>
       <para>
        <filename>desktops</filename> (e.g. <filename>kde</filename>,
@@ -512,7 +555,9 @@ args.stdenv.mkDerivation (args // {
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term>If it’s a <emphasis>window manager</emphasis>:</term>
+     <term>
+      If it’s a <emphasis>window manager</emphasis>:
+     </term>
      <listitem>
       <para>
        <filename>applications/window-managers</filename> (e.g.
@@ -521,7 +566,9 @@ args.stdenv.mkDerivation (args // {
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term>If it’s an <emphasis>application</emphasis>:</term>
+     <term>
+      If it’s an <emphasis>application</emphasis>:
+     </term>
      <listitem>
       <para>
        A (typically large) program with a distinct user interface, primarily
@@ -529,7 +576,9 @@ args.stdenv.mkDerivation (args // {
       </para>
       <variablelist>
        <varlistentry>
-        <term>If it’s a <emphasis>version management system</emphasis>:</term>
+        <term>
+         If it’s a <emphasis>version management system</emphasis>:
+        </term>
         <listitem>
          <para>
           <filename>applications/version-management</filename> (e.g.
@@ -538,7 +587,9 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>If it’s for <emphasis>video playback / editing</emphasis>:</term>
+        <term>
+         If it’s for <emphasis>video playback / editing</emphasis>:
+        </term>
         <listitem>
          <para>
           <filename>applications/video</filename> (e.g.
@@ -547,7 +598,9 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>If it’s for <emphasis>graphics viewing / editing</emphasis>:</term>
+        <term>
+         If it’s for <emphasis>graphics viewing / editing</emphasis>:
+        </term>
         <listitem>
          <para>
           <filename>applications/graphics</filename> (e.g.
@@ -556,11 +609,15 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>If it’s for <emphasis>networking</emphasis>:</term>
+        <term>
+         If it’s for <emphasis>networking</emphasis>:
+        </term>
         <listitem>
          <variablelist>
           <varlistentry>
-           <term>If it’s a <emphasis>mailreader</emphasis>:</term>
+           <term>
+            If it’s a <emphasis>mailreader</emphasis>:
+           </term>
            <listitem>
             <para>
              <filename>applications/networking/mailreaders</filename> (e.g.
@@ -569,7 +626,9 @@ args.stdenv.mkDerivation (args // {
            </listitem>
           </varlistentry>
           <varlistentry>
-           <term>If it’s a <emphasis>newsreader</emphasis>:</term>
+           <term>
+            If it’s a <emphasis>newsreader</emphasis>:
+           </term>
            <listitem>
             <para>
              <filename>applications/networking/newsreaders</filename> (e.g.
@@ -578,7 +637,9 @@ args.stdenv.mkDerivation (args // {
            </listitem>
           </varlistentry>
           <varlistentry>
-           <term>If it’s a <emphasis>web browser</emphasis>:</term>
+           <term>
+            If it’s a <emphasis>web browser</emphasis>:
+           </term>
            <listitem>
             <para>
              <filename>applications/networking/browsers</filename> (e.g.
@@ -587,7 +648,9 @@ args.stdenv.mkDerivation (args // {
            </listitem>
           </varlistentry>
           <varlistentry>
-           <term>Else:</term>
+           <term>
+            Else:
+           </term>
            <listitem>
             <para>
              <filename>applications/networking/misc</filename>
@@ -598,7 +661,9 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>Else:</term>
+        <term>
+         Else:
+        </term>
         <listitem>
          <para>
           <filename>applications/misc</filename>
@@ -609,12 +674,15 @@ args.stdenv.mkDerivation (args // {
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term>If it’s <emphasis>data</emphasis> (i.e., does not have a
+     <term>
-    straight-forward executable semantics):</term>
+      If it’s <emphasis>data</emphasis> (i.e., does not have a straight-forward executable semantics):
+     </term>
      <listitem>
       <variablelist>
        <varlistentry>
-        <term>If it’s a <emphasis>font</emphasis>:</term>
+        <term>
+         If it’s a <emphasis>font</emphasis>:
+        </term>
         <listitem>
          <para>
           <filename>data/fonts</filename>
@@ -622,11 +690,15 @@ args.stdenv.mkDerivation (args // {
         </listitem>
        </varlistentry>
        <varlistentry>
-        <term>If it’s related to <emphasis>SGML/XML processing</emphasis>:</term>
+        <term>
+         If it’s related to <emphasis>SGML/XML processing</emphasis>:
+        </term>
         <listitem>
          <variablelist>
           <varlistentry>
-           <term>If it’s an <emphasis>XML DTD</emphasis>:</term>
+           <term>
+            If it’s an <emphasis>XML DTD</emphasis>:
+           </term>
            <listitem>
             <para>
              <filename>data/sgml+xml/schemas/xml-dtd</filename> (e.g.
@@ -635,7 +707,9 @@ args.stdenv.mkDerivation (args // {
            </listitem>
           </varlistentry>
           <varlistentry>
-           <term>If it’s an <emphasis>XSLT stylesheet</emphasis>:</term>
+           <term>
+            If it’s an <emphasis>XSLT stylesheet</emphasis>:
+           </term>
            <listitem>
             <para>
              (Okay, these are executable...)
@@ -653,7 +727,9 @@ args.stdenv.mkDerivation (args // {
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term>If it’s a <emphasis>game</emphasis>:</term>
+     <term>
+      If it’s a <emphasis>game</emphasis>:
+     </term>
      <listitem>
       <para>
        <filename>games</filename>
@@ -661,7 +737,9 @@ args.stdenv.mkDerivation (args // {
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term>Else:</term>
+     <term>
+      Else:
+     </term>
      <listitem>
       <para>
        <filename>misc</filename>

doc/cross-compilation.xml

@@ -60,7 +60,8 @@
 
    <variablelist>
     <varlistentry>
-     <term><varname>buildPlatform</varname>
+     <term>
+      <varname>buildPlatform</varname>
      </term>
      <listitem>
       <para>
@@ -71,7 +72,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>hostPlatform</varname>
+     <term>
+      <varname>hostPlatform</varname>
      </term>
      <listitem>
       <para>
@@ -82,7 +84,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>targetPlatform</varname>
+     <term>
+      <varname>targetPlatform</varname>
      </term>
      <listitem>
       <para>
@@ -128,7 +131,8 @@
 
    <variablelist>
     <varlistentry>
-     <term><varname>system</varname>
+     <term>
+      <varname>system</varname>
      </term>
      <listitem>
       <para>
@@ -141,7 +145,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>config</varname>
+     <term>
+      <varname>config</varname>
      </term>
      <listitem>
       <para>
@@ -157,7 +162,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>parsed</varname>
+     <term>
+      <varname>parsed</varname>
      </term>
      <listitem>
       <para>
@@ -171,7 +177,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>libc</varname>
+     <term>
+      <varname>libc</varname>
      </term>
      <listitem>
       <para>
@@ -183,7 +190,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>is*</varname>
+     <term>
+      <varname>is*</varname>
      </term>
      <listitem>
       <para>
@@ -195,7 +203,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>platform</varname>
+     <term>
+      <varname>platform</varname>
      </term>
      <listitem>
       <para>

doc/functions.xml

@@ -321,7 +321,8 @@ merge:"diff3"
 
   <variablelist>
    <varlistentry>
-    <term><literal>name</literal>
+    <term>
+     <literal>name</literal>
     </term>
     <listitem>
      <para>
@@ -330,7 +331,8 @@ merge:"diff3"
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><literal>targetPkgs</literal>
+    <term>
+     <literal>targetPkgs</literal>
     </term>
     <listitem>
      <para>
@@ -340,7 +342,8 @@ merge:"diff3"
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><literal>multiPkgs</literal>
+    <term>
+     <literal>multiPkgs</literal>
     </term>
     <listitem>
      <para>
@@ -351,7 +354,8 @@ merge:"diff3"
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><literal>extraBuildCommands</literal>
+    <term>
+     <literal>extraBuildCommands</literal>
     </term>
     <listitem>
      <para>
@@ -361,7 +365,8 @@ merge:"diff3"
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><literal>extraBuildCommandsMulti</literal>
+    <term>
+     <literal>extraBuildCommandsMulti</literal>
     </term>
     <listitem>
      <para>
@@ -371,7 +376,8 @@ merge:"diff3"
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><literal>extraOutputsToInstall</literal>
+    <term>
+     <literal>extraOutputsToInstall</literal>
     </term>
     <listitem>
      <para>
@@ -381,7 +387,8 @@ merge:"diff3"
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><literal>extraInstallCommands</literal>
+    <term>
+     <literal>extraInstallCommands</literal>
     </term>
     <listitem>
      <para>
@@ -391,7 +398,8 @@ merge:"diff3"
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><literal>runScript</literal>
+    <term>
+     <literal>runScript</literal>
     </term>
     <listitem>
      <para>
@@ -624,9 +632,9 @@ merge:"diff3"
 
    <para>
     This function is analogous to the <command>docker pull</command> command,
-    in that can be used to pull a Docker image from a Docker registry.
+    in that can be used to pull a Docker image from a Docker registry. By
-    By default <link xlink:href="https://hub.docker.com/">Docker Hub</link>
+    default <link xlink:href="https://hub.docker.com/">Docker Hub</link> is
-    is used to pull images.
+    used to pull images.
    </para>
 
    <para>
@@ -648,15 +656,15 @@ merge:"diff3"
    <calloutlist>
     <callout arearefs='ex-dockerTools-pullImage-1'>
      <para>
-      <varname>imageName</varname> specifies the name of the image to be downloaded,
+      <varname>imageName</varname> specifies the name of the image to be
-      which can also include the registry namespace (e.g. <literal>nixos</literal>).
+      downloaded, which can also include the registry namespace (e.g.
-      This argument is required.
+      <literal>nixos</literal>). This argument is required.
      </para>
     </callout>
     <callout arearefs='ex-dockerTools-pullImage-2'>
      <para>
-      <varname>imageDigest</varname> specifies the digest of the image
+      <varname>imageDigest</varname> specifies the digest of the image to be
-      to be downloaded. Skopeo can be used to get the digest of an image
+      downloaded. Skopeo can be used to get the digest of an image
 <programlisting>
   $ skopeo inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest'
   sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b
@@ -666,10 +674,10 @@ merge:"diff3"
     </callout>
     <callout arearefs='ex-dockerTools-pullImage-3'>
      <para>
-      <varname>finalImageTag</varname>, if specified, this is the tag of
+      <varname>finalImageTag</varname>, if specified, this is the tag of the
-      the image to be created. Note it is never used to fetch the image
+      image to be created. Note it is never used to fetch the image since we
-      since we prefer to rely on the immutable digest ID. By default
+      prefer to rely on the immutable digest ID. By default it's
-      it's <literal>latest</literal>.
+      <literal>latest</literal>.
      </para>
     </callout>
     <callout arearefs='ex-dockerTools-pullImage-4'>

doc/languages-frameworks/bower.xml

@@ -205,8 +205,8 @@ pkgs.stdenv.mkDerivation {
 
   <variablelist>
    <varlistentry>
-    <term><literal>ENOCACHE</literal> errors from
+    <term>
-    <varname>buildBowerComponents</varname>
+     <literal>ENOCACHE</literal> errors from <varname>buildBowerComponents</varname>
     </term>
     <listitem>
      <para>

doc/meta.xml

@@ -83,7 +83,8 @@ hello-2.3  A program that produces a familiar, friendly greeting
 
   <variablelist>
    <varlistentry>
-    <term><varname>description</varname>
+    <term>
+     <varname>description</varname>
     </term>
     <listitem>
      <para>
@@ -106,7 +107,8 @@ hello-2.3  A program that produces a familiar, friendly greeting
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>longDescription</varname>
+    <term>
+     <varname>longDescription</varname>
     </term>
     <listitem>
      <para>
@@ -115,7 +117,8 @@ hello-2.3  A program that produces a familiar, friendly greeting
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>branch</varname>
+    <term>
+     <varname>branch</varname>
     </term>
     <listitem>
      <para>
@@ -126,7 +129,8 @@ hello-2.3  A program that produces a familiar, friendly greeting
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>homepage</varname>
+    <term>
+     <varname>homepage</varname>
     </term>
     <listitem>
      <para>
@@ -136,7 +140,8 @@ hello-2.3  A program that produces a familiar, friendly greeting
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>downloadPage</varname>
+    <term>
+     <varname>downloadPage</varname>
     </term>
     <listitem>
      <para>
@@ -146,7 +151,8 @@ hello-2.3  A program that produces a familiar, friendly greeting
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>license</varname>
+    <term>
+     <varname>license</varname>
     </term>
     <listitem>
      <para>
@@ -198,7 +204,8 @@ hello-2.3  A program that produces a familiar, friendly greeting
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>maintainers</varname>
+    <term>
+     <varname>maintainers</varname>
     </term>
     <listitem>
      <para>
@@ -213,7 +220,8 @@ hello-2.3  A program that produces a familiar, friendly greeting
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>priority</varname>
+    <term>
+     <varname>priority</varname>
     </term>
     <listitem>
      <para>
@@ -225,7 +233,8 @@ hello-2.3  A program that produces a familiar, friendly greeting
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>platforms</varname>
+    <term>
+     <varname>platforms</varname>
     </term>
     <listitem>
      <para>
@@ -242,7 +251,8 @@ meta.platforms = stdenv.lib.platforms.linux;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>hydraPlatforms</varname>
+    <term>
+     <varname>hydraPlatforms</varname>
     </term>
     <listitem>
      <para>
@@ -261,7 +271,8 @@ meta.hydraPlatforms = [];
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>broken</varname>
+    <term>
+     <varname>broken</varname>
     </term>
     <listitem>
      <para>
@@ -273,7 +284,8 @@ meta.hydraPlatforms = [];
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>updateWalker</varname>
+    <term>
+     <varname>updateWalker</varname>
     </term>
     <listitem>
      <para>
@@ -305,8 +317,8 @@ meta.hydraPlatforms = [];
    generic options are available:
    <variablelist>
     <varlistentry>
-     <term><varname>stdenv.lib.licenses.free</varname>,
+     <term>
-    <varname>"free"</varname>
+      <varname>stdenv.lib.licenses.free</varname>, <varname>"free"</varname>
      </term>
      <listitem>
       <para>
@@ -315,8 +327,8 @@ meta.hydraPlatforms = [];
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>stdenv.lib.licenses.unfreeRedistributable</varname>,
+     <term>
-    <varname>"unfree-redistributable"</varname>
+      <varname>stdenv.lib.licenses.unfreeRedistributable</varname>, <varname>"unfree-redistributable"</varname>
      </term>
      <listitem>
       <para>
@@ -336,8 +348,8 @@ meta.hydraPlatforms = [];
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>stdenv.lib.licenses.unfree</varname>,
+     <term>
-    <varname>"unfree"</varname>
+      <varname>stdenv.lib.licenses.unfree</varname>, <varname>"unfree"</varname>
      </term>
      <listitem>
       <para>
@@ -348,8 +360,8 @@ meta.hydraPlatforms = [];
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>stdenv.lib.licenses.unfreeRedistributableFirmware</varname>,
+     <term>
-    <varname>"unfree-redistributable-firmware"</varname>
+      <varname>stdenv.lib.licenses.unfreeRedistributableFirmware</varname>, <varname>"unfree-redistributable-firmware"</varname>
      </term>
      <listitem>
       <para>

doc/multiple-output.xml

@@ -188,8 +188,8 @@
 
    <variablelist>
     <varlistentry>
-     <term><varname>
+     <term>
-         $outputDev</varname>
+      <varname> $outputDev</varname>
      </term>
      <listitem>
       <para>
@@ -200,8 +200,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>
+     <term>
-        $outputBin</varname>
+      <varname> $outputBin</varname>
      </term>
      <listitem>
       <para>
@@ -211,8 +211,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>
+     <term>
-        $outputLib</varname>
+      <varname> $outputLib</varname>
      </term>
      <listitem>
       <para>
@@ -223,8 +223,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>
+     <term>
-        $outputDoc</varname>
+      <varname> $outputDoc</varname>
      </term>
      <listitem>
       <para>
@@ -235,8 +235,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>
+     <term>
-        $outputDevdoc</varname>
+      <varname> $outputDevdoc</varname>
      </term>
      <listitem>
       <para>
@@ -248,8 +248,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>
+     <term>
-        $outputMan</varname>
+      <varname> $outputMan</varname>
      </term>
      <listitem>
       <para>
@@ -259,8 +259,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>
+     <term>
-        $outputDevman</varname>
+      <varname> $outputDevman</varname>
      </term>
      <listitem>
       <para>
@@ -270,8 +270,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><varname>
+     <term>
-        $outputInfo</varname>
+      <varname> $outputInfo</varname>
      </term>
      <listitem>
       <para>

doc/package-notes.xml

@@ -428,7 +428,9 @@ packageOverrides = pkgs: {
    <para>
     <variablelist>
      <varlistentry>
-      <term>Steam fails to start. What do I do?</term>
+      <term>
+       Steam fails to start. What do I do?
+      </term>
       <listitem>
        <para>
         Try to run
@@ -438,7 +440,9 @@ packageOverrides = pkgs: {
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term>Using the FOSS Radeon or nouveau (nvidia) drivers</term>
+      <term>
+       Using the FOSS Radeon or nouveau (nvidia) drivers
+      </term>
       <listitem>
        <itemizedlist>
         <listitem>
@@ -462,7 +466,9 @@ packageOverrides = pkgs: {
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term>Java</term>
+      <term>
+       Java
+      </term>
       <listitem>
        <orderedlist>
         <listitem>

doc/shell.nix

@@ -1,5 +1,5 @@
 { pkgs ? import ../. {} }:
 (import ./default.nix).overrideAttrs (x: {
-  buildInputs = x.buildInputs ++ [ pkgs.xmloscopy ];
+  buildInputs = x.buildInputs ++ [ pkgs.xmloscopy pkgs.ruby ];
 
 })

nixos/doc/manual/Makefile

@@ -14,6 +14,11 @@ format:
 	find . -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \
 		xmlformat --config-file "../xmlformat.conf" -i {}
 
+.PHONY: fix-misc-xml
+fix-misc-xml:
+	find . -iname '*.xml' -type f \
+		-exec ../varlistentry-fixer.rb {} ';'
+
 .PHONY: clean
 clean:
 	rm -f manual-combined.xml generated

nixos/doc/manual/administration/boot-problems.xml

@@ -14,7 +14,8 @@
   NixOS boot scripts or by systemd:
   <variablelist>
    <varlistentry>
-    <term><literal>boot.shell_on_fail</literal>
+    <term>
+     <literal>boot.shell_on_fail</literal>
     </term>
     <listitem>
      <para>
@@ -25,7 +26,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><literal>boot.debug1</literal>
+    <term>
+     <literal>boot.debug1</literal>
     </term>
     <listitem>
      <para>
@@ -37,7 +39,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><literal>boot.trace</literal>
+    <term>
+     <literal>boot.trace</literal>
     </term>
     <listitem>
      <para>
@@ -46,7 +49,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><literal>single</literal>
+    <term>
+     <literal>single</literal>
     </term>
     <listitem>
      <para>
@@ -59,7 +63,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><literal>systemd.log_level=debug systemd.log_target=console</literal>
+    <term>
+     <literal>systemd.log_level=debug systemd.log_target=console</literal>
     </term>
     <listitem>
      <para>

nixos/doc/manual/configuration/config-file.xml

@@ -80,7 +80,9 @@ The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is no
   Options have various types of values. The most important are:
   <variablelist>
    <varlistentry>
-    <term>Strings</term>
+    <term>
+     Strings
+    </term>
     <listitem>
      <para>
       Strings are enclosed in double quotes, e.g.
@@ -112,7 +114,9 @@ The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is no
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term>Booleans</term>
+    <term>
+     Booleans
+    </term>
     <listitem>
      <para>
       These can be <literal>true</literal> or <literal>false</literal>, e.g.
@@ -124,7 +128,9 @@ The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is no
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term>Integers</term>
+    <term>
+     Integers
+    </term>
     <listitem>
      <para>
       For example,
@@ -141,7 +147,9 @@ The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is no
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term>Sets</term>
+    <term>
+     Sets
+    </term>
     <listitem>
      <para>
       Sets were introduced above. They are name/value pairs enclosed in braces,
@@ -157,7 +165,9 @@ The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is no
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term>Lists</term>
+    <term>
+     Lists
+    </term>
     <listitem>
      <para>
       The important thing to note about lists is that list elements are
@@ -173,7 +183,9 @@ swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term>Packages</term>
+    <term>
+     Packages
+    </term>
     <listitem>
      <para>
       Usually, the packages you need are already part of the Nix Packages

nixos/doc/manual/development/building-parts.xml

@@ -15,7 +15,8 @@ $ nix-build -A config.<replaceable>option</replaceable></screen>
   include:
   <variablelist>
    <varlistentry>
-    <term><varname>system.build.toplevel</varname>
+    <term>
+     <varname>system.build.toplevel</varname>
     </term>
     <listitem>
      <para>
@@ -32,7 +33,8 @@ $ nix-build -A system</screen>
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>system.build.manual.manual</varname>
+    <term>
+     <varname>system.build.manual.manual</varname>
     </term>
     <listitem>
      <para>
@@ -41,7 +43,8 @@ $ nix-build -A system</screen>
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>system.build.etc</varname>
+    <term>
+     <varname>system.build.etc</varname>
     </term>
     <listitem>
      <para>
@@ -51,9 +54,11 @@ $ nix-build -A system</screen>
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>system.build.initialRamdisk</varname>
+    <term>
+     <varname>system.build.initialRamdisk</varname>
     </term>
-    <term><varname>system.build.kernel</varname>
+    <term>
+     <varname>system.build.kernel</varname>
     </term>
     <listitem>
      <para>
@@ -69,11 +74,14 @@ $ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>system.build.nixos-rebuild</varname>
+    <term>
+     <varname>system.build.nixos-rebuild</varname>
     </term>
-    <term><varname>system.build.nixos-install</varname>
+    <term>
+     <varname>system.build.nixos-install</varname>
     </term>
-    <term><varname>system.build.nixos-generate-config</varname>
+    <term>
+     <varname>system.build.nixos-generate-config</varname>
     </term>
     <listitem>
      <para>
@@ -82,7 +90,8 @@ $ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>systemd.units.<replaceable>unit-name</replaceable>.unit</varname>
+    <term>
+     <varname>systemd.units.<replaceable>unit-name</replaceable>.unit</varname>
     </term>
     <listitem>
      <para>

nixos/doc/manual/development/option-declarations.xml

@@ -32,7 +32,8 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming">
   The function <varname>mkOption</varname> accepts the following arguments.
   <variablelist>
    <varlistentry>
-    <term><varname>type</varname>
+    <term>
+     <varname>type</varname>
     </term>
     <listitem>
      <para>
@@ -43,7 +44,8 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming">
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>default</varname>
+    <term>
+     <varname>default</varname>
     </term>
     <listitem>
      <para>
@@ -55,7 +57,8 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming">
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>example</varname>
+    <term>
+     <varname>example</varname>
     </term>
     <listitem>
      <para>
@@ -64,7 +67,8 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming">
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>description</varname>
+    <term>
+     <varname>description</varname>
     </term>
     <listitem>
      <para>

nixos/doc/manual/development/option-types.xml

@@ -22,7 +22,8 @@
 
   <variablelist>
    <varlistentry>
-    <term><varname>types.attrs</varname>
+    <term>
+     <varname>types.attrs</varname>
     </term>
     <listitem>
      <para>
@@ -31,7 +32,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.bool</varname>
+    <term>
+     <varname>types.bool</varname>
     </term>
     <listitem>
      <para>
@@ -41,7 +43,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.path</varname>
+    <term>
+     <varname>types.path</varname>
     </term>
     <listitem>
      <para>
@@ -52,7 +55,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.package</varname>
+    <term>
+     <varname>types.package</varname>
     </term>
     <listitem>
      <para>
@@ -68,7 +72,8 @@
 
   <variablelist>
    <varlistentry>
-    <term><varname>types.int</varname>
+    <term>
+     <varname>types.int</varname>
     </term>
     <listitem>
      <para>
@@ -77,7 +82,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.ints.{s8, s16, s32}</varname>
+    <term>
+     <varname>types.ints.{s8, s16, s32}</varname>
     </term>
     <listitem>
      <para>
@@ -91,7 +97,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.ints.unsigned</varname>
+    <term>
+     <varname>types.ints.unsigned</varname>
     </term>
     <listitem>
      <para>
@@ -100,7 +107,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.ints.{u8, u16, u32}</varname>
+    <term>
+     <varname>types.ints.{u8, u16, u32}</varname>
     </term>
     <listitem>
      <para>
@@ -114,7 +122,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.ints.positive</varname>
+    <term>
+     <varname>types.ints.positive</varname>
     </term>
     <listitem>
      <para>
@@ -130,7 +139,8 @@
 
   <variablelist>
    <varlistentry>
-    <term><varname>types.str</varname>
+    <term>
+     <varname>types.str</varname>
     </term>
     <listitem>
      <para>
@@ -139,7 +149,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.lines</varname>
+    <term>
+     <varname>types.lines</varname>
     </term>
     <listitem>
      <para>
@@ -149,7 +160,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.commas</varname>
+    <term>
+     <varname>types.commas</varname>
     </term>
     <listitem>
      <para>
@@ -159,7 +171,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.envVar</varname>
+    <term>
+     <varname>types.envVar</varname>
     </term>
     <listitem>
      <para>
@@ -169,7 +182,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.strMatching</varname>
+    <term>
+     <varname>types.strMatching</varname>
     </term>
     <listitem>
      <para>
@@ -191,7 +205,8 @@
 
   <variablelist>
    <varlistentry>
-    <term><varname>types.enum</varname><replaceable>l</replaceable>
+    <term>
+     <varname>types.enum</varname> <replaceable>l</replaceable>
     </term>
     <listitem>
      <para>
@@ -202,7 +217,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.separatedString</varname><replaceable>sep</replaceable>
+    <term>
+     <varname>types.separatedString</varname> <replaceable>sep</replaceable>
     </term>
     <listitem>
      <para>
@@ -212,7 +228,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.ints.between</varname><replaceable>lowest</replaceable><replaceable>highest</replaceable>
+    <term>
+     <varname>types.ints.between</varname> <replaceable>lowest</replaceable> <replaceable>highest</replaceable>
     </term>
     <listitem>
      <para>
@@ -223,7 +240,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.submodule</varname><replaceable>o</replaceable>
+    <term>
+     <varname>types.submodule</varname> <replaceable>o</replaceable>
     </term>
     <listitem>
      <para>
@@ -250,7 +268,8 @@
 
   <variablelist>
    <varlistentry>
-    <term><varname>types.listOf</varname><replaceable>t</replaceable>
+    <term>
+     <varname>types.listOf</varname> <replaceable>t</replaceable>
     </term>
     <listitem>
      <para>
@@ -260,7 +279,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.attrsOf</varname><replaceable>t</replaceable>
+    <term>
+     <varname>types.attrsOf</varname> <replaceable>t</replaceable>
     </term>
     <listitem>
      <para>
@@ -271,7 +291,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.loaOf</varname><replaceable>t</replaceable>
+    <term>
+     <varname>types.loaOf</varname> <replaceable>t</replaceable>
     </term>
     <listitem>
      <para>
@@ -281,7 +302,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.nullOr</varname><replaceable>t</replaceable>
+    <term>
+     <varname>types.nullOr</varname> <replaceable>t</replaceable>
     </term>
     <listitem>
      <para>
@@ -291,7 +313,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.uniq</varname><replaceable>t</replaceable>
+    <term>
+     <varname>types.uniq</varname> <replaceable>t</replaceable>
     </term>
     <listitem>
      <para>
@@ -301,7 +324,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.either</varname><replaceable>t1</replaceable><replaceable>t2</replaceable>
+    <term>
+     <varname>types.either</varname> <replaceable>t1</replaceable> <replaceable>t2</replaceable>
     </term>
     <listitem>
      <para>
@@ -312,7 +336,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>types.coercedTo</varname><replaceable>from</replaceable><replaceable>f</replaceable><replaceable>to</replaceable>
+    <term>
+     <varname>types.coercedTo</varname> <replaceable>from</replaceable> <replaceable>f</replaceable> <replaceable>to</replaceable>
     </term>
     <listitem>
      <para>
@@ -468,7 +493,8 @@ config.mod.two = { foo = 2; bar = "two"; };</screen>
 
   <variablelist>
    <varlistentry>
-    <term><varname>check</varname>
+    <term>
+     <varname>check</varname>
     </term>
     <listitem>
      <para>
@@ -501,7 +527,8 @@ nixThings = mkOption {
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>merge</varname>
+    <term>
+     <varname>merge</varname>
     </term>
     <listitem>
      <para>
@@ -534,7 +561,8 @@ nixThings = mkOption {
 
   <variablelist>
    <varlistentry>
-    <term><varname>name</varname>
+    <term>
+     <varname>name</varname>
     </term>
     <listitem>
      <para>
@@ -543,7 +571,8 @@ nixThings = mkOption {
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>definition</varname>
+    <term>
+     <varname>definition</varname>
     </term>
     <listitem>
      <para>
@@ -553,7 +582,8 @@ nixThings = mkOption {
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>check</varname>
+    <term>
+     <varname>check</varname>
     </term>
     <listitem>
      <para>
@@ -565,7 +595,8 @@ nixThings = mkOption {
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>merge</varname>
+    <term>
+     <varname>merge</varname>
     </term>
     <listitem>
      <para>
@@ -573,7 +604,8 @@ nixThings = mkOption {
      </para>
      <variablelist>
       <varlistentry>
-       <term><replaceable>loc</replaceable>
+       <term>
+        <replaceable>loc</replaceable>
        </term>
        <listitem>
         <para>
@@ -583,7 +615,8 @@ nixThings = mkOption {
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term><replaceable>defs</replaceable>
+       <term>
+        <replaceable>defs</replaceable>
        </term>
        <listitem>
         <para>
@@ -600,7 +633,8 @@ nixThings = mkOption {
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>getSubOptions</varname>
+    <term>
+     <varname>getSubOptions</varname>
     </term>
     <listitem>
      <para>
@@ -615,7 +649,8 @@ nixThings = mkOption {
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>getSubModules</varname>
+    <term>
+     <varname>getSubModules</varname>
     </term>
     <listitem>
      <para>
@@ -628,7 +663,8 @@ nixThings = mkOption {
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>substSubModules</varname>
+    <term>
+     <varname>substSubModules</varname>
     </term>
     <listitem>
      <para>
@@ -644,7 +680,8 @@ nixThings = mkOption {
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>typeMerge</varname>
+    <term>
+     <varname>typeMerge</varname>
     </term>
     <listitem>
      <para>
@@ -654,7 +691,8 @@ nixThings = mkOption {
      </para>
      <variablelist>
       <varlistentry>
-       <term><replaceable>f</replaceable>
+       <term>
+        <replaceable>f</replaceable>
        </term>
        <listitem>
         <para>
@@ -670,7 +708,8 @@ nixThings = mkOption {
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><varname>functor</varname>
+    <term>
+     <varname>functor</varname>
     </term>
     <listitem>
      <para>
@@ -679,7 +718,8 @@ nixThings = mkOption {
      </para>
      <variablelist>
       <varlistentry>
-       <term><varname>type</varname>
+       <term>
+        <varname>type</varname>
        </term>
        <listitem>
         <para>
@@ -688,7 +728,8 @@ nixThings = mkOption {
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term><varname>wrapped</varname>
+       <term>
+        <varname>wrapped</varname>
        </term>
        <listitem>
         <para>
@@ -697,7 +738,8 @@ nixThings = mkOption {
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term><varname>payload</varname>
+       <term>
+        <varname>payload</varname>
        </term>
        <listitem>
         <para>
@@ -709,7 +751,8 @@ nixThings = mkOption {
        </listitem>
       </varlistentry>
       <varlistentry>
-       <term><varname>binOp</varname>
+       <term>
+        <varname>binOp</varname>
        </term>
        <listitem>
         <para>

nixos/doc/manual/development/writing-nixos-tests.xml

@@ -54,7 +54,8 @@ xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs.nix">nf
 <!-- FIXME: would be nice to generate this automatically. -->
   <variablelist>
    <varlistentry>
-    <term><option>virtualisation.memorySize</option>
+    <term>
+     <option>virtualisation.memorySize</option>
     </term>
     <listitem>
      <para>
@@ -63,7 +64,8 @@ xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs.nix">nf
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>virtualisation.vlans</option>
+    <term>
+     <option>virtualisation.vlans</option>
     </term>
     <listitem>
      <para>
@@ -75,7 +77,8 @@ xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs.nix">nf
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>virtualisation.writableStore</option>
+    <term>
+     <option>virtualisation.writableStore</option>
     </term>
     <listitem>
      <para>
@@ -120,7 +123,8 @@ startAll;
   The following methods are available on machine objects:
   <variablelist>
    <varlistentry>
-    <term><methodname>start</methodname>
+    <term>
+     <methodname>start</methodname>
     </term>
     <listitem>
      <para>
@@ -130,7 +134,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>shutdown</methodname>
+    <term>
+     <methodname>shutdown</methodname>
     </term>
     <listitem>
      <para>
@@ -139,7 +144,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>crash</methodname>
+    <term>
+     <methodname>crash</methodname>
     </term>
     <listitem>
      <para>
@@ -148,7 +154,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>block</methodname>
+    <term>
+     <methodname>block</methodname>
     </term>
     <listitem>
      <para>
@@ -158,7 +165,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>unblock</methodname>
+    <term>
+     <methodname>unblock</methodname>
     </term>
     <listitem>
      <para>
@@ -167,7 +175,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>screenshot</methodname>
+    <term>
+     <methodname>screenshot</methodname>
     </term>
     <listitem>
      <para>
@@ -177,7 +186,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>getScreenText</methodname>
+    <term>
+     <methodname>getScreenText</methodname>
     </term>
     <listitem>
      <para>
@@ -193,7 +203,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>sendMonitorCommand</methodname>
+    <term>
+     <methodname>sendMonitorCommand</methodname>
     </term>
     <listitem>
      <para>
@@ -203,7 +214,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>sendKeys</methodname>
+    <term>
+     <methodname>sendKeys</methodname>
     </term>
     <listitem>
      <para>
@@ -213,7 +225,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>sendChars</methodname>
+    <term>
+     <methodname>sendChars</methodname>
     </term>
     <listitem>
      <para>
@@ -224,7 +237,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>execute</methodname>
+    <term>
+     <methodname>execute</methodname>
     </term>
     <listitem>
      <para>
@@ -235,7 +249,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>succeed</methodname>
+    <term>
+     <methodname>succeed</methodname>
     </term>
     <listitem>
      <para>
@@ -245,7 +260,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>fail</methodname>
+    <term>
+     <methodname>fail</methodname>
     </term>
     <listitem>
      <para>
@@ -255,7 +271,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>waitUntilSucceeds</methodname>
+    <term>
+     <methodname>waitUntilSucceeds</methodname>
     </term>
     <listitem>
      <para>
@@ -264,7 +281,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>waitUntilFails</methodname>
+    <term>
+     <methodname>waitUntilFails</methodname>
     </term>
     <listitem>
      <para>
@@ -273,7 +291,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>waitForUnit</methodname>
+    <term>
+     <methodname>waitForUnit</methodname>
     </term>
     <listitem>
      <para>
@@ -282,7 +301,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>waitForFile</methodname>
+    <term>
+     <methodname>waitForFile</methodname>
     </term>
     <listitem>
      <para>
@@ -291,7 +311,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>waitForOpenPort</methodname>
+    <term>
+     <methodname>waitForOpenPort</methodname>
     </term>
     <listitem>
      <para>
@@ -301,7 +322,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>waitForClosedPort</methodname>
+    <term>
+     <methodname>waitForClosedPort</methodname>
     </term>
     <listitem>
      <para>
@@ -310,7 +332,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>waitForX</methodname>
+    <term>
+     <methodname>waitForX</methodname>
     </term>
     <listitem>
      <para>
@@ -319,7 +342,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>waitForText</methodname>
+    <term>
+     <methodname>waitForText</methodname>
     </term>
     <listitem>
      <para>
@@ -336,7 +360,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>waitForWindow</methodname>
+    <term>
+     <methodname>waitForWindow</methodname>
     </term>
     <listitem>
      <para>
@@ -346,7 +371,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>copyFileFromHost</methodname>
+    <term>
+     <methodname>copyFileFromHost</methodname>
     </term>
     <listitem>
      <para>
@@ -361,7 +387,8 @@ startAll;
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><methodname>systemctl</methodname>
+    <term>
+     <methodname>systemctl</methodname>
     </term>
     <listitem>
      <para>

nixos/doc/manual/installation/installing.xml

@@ -16,7 +16,9 @@
    </para>
    <variablelist>
     <varlistentry>
-     <term>UEFI systems</term>
+     <term>
+      UEFI systems
+     </term>
      <listitem>
       <para>
        You should boot the live CD in UEFI mode (consult your specific
@@ -138,7 +140,9 @@
      <listitem>
       <variablelist>
        <varlistentry>
-        <term>UEFI systems</term>
+        <term>
+         UEFI systems
+        </term>
         <listitem>
          <para>
           For creating boot partitions: <command>mkfs.fat</command>. Again
@@ -178,7 +182,9 @@
   <listitem>
    <variablelist>
     <varlistentry>
-     <term>UEFI systems</term>
+     <term>
+      UEFI systems
+     </term>
      <listitem>
       <para>
        Mount the boot file system on <filename>/mnt/boot</filename>, e.g.
@@ -234,7 +240,9 @@
    </para>
    <variablelist>
     <varlistentry>
-     <term>BIOS systems</term>
+     <term>
+      BIOS systems
+     </term>
      <listitem>
       <para>
        You <emphasis>must</emphasis> set the option
@@ -244,7 +252,9 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term>UEFI systems</term>
+     <term>
+      UEFI systems
+     </term>
      <listitem>
       <para>
        You <emphasis>must</emphasis> set the option

nixos/doc/manual/man-nixos-build-vms.xml

@@ -12,14 +12,22 @@
   </refname><refpurpose>build a network of virtual machines from a network of NixOS configurations</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
-  <cmdsynopsis><command>nixos-build-vms</command>
+  <cmdsynopsis>
-   <arg><option>--show-trace</option>
+   <command>nixos-build-vms</command> 
+   <arg>
+    <option>--show-trace</option>
    </arg>
-   <arg><option>--no-out-link</option>
+    
+   <arg>
+    <option>--no-out-link</option>
    </arg>
-   <arg><option>--help</option>
+    
+   <arg>
+    <option>--help</option>
    </arg>
-   <arg choice="plain"><replaceable>network.nix</replaceable>
+    
+   <arg choice="plain">
+    <replaceable>network.nix</replaceable>
    </arg>
   </cmdsynopsis>
  </refsynopsisdiv>
@@ -78,7 +86,8 @@
   </para>
   <variablelist>
    <varlistentry>
-    <term><option>--show-trace</option>
+    <term>
+     <option>--show-trace</option>
     </term>
     <listitem>
      <para>
@@ -87,7 +96,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--no-out-link</option>
+    <term>
+     <option>--no-out-link</option>
     </term>
     <listitem>
      <para>
@@ -96,7 +106,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>-h</option>, <option>--help</option>
+    <term>
+     <option>-h</option>, <option>--help</option>
     </term>
     <listitem>
      <para>

nixos/doc/manual/man-nixos-enter.xml

@@ -12,26 +12,40 @@
   </refname><refpurpose>run a command in a NixOS chroot environment</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
-  <cmdsynopsis><command>nixos-enter</command>
+  <cmdsynopsis>
+   <command>nixos-enter</command> 
    <arg>
-    <arg choice='plain'><option>--root</option>
+    <arg choice='plain'>
-    </arg><replaceable>root</replaceable>
+     <option>--root</option>
     </arg>
-   <arg>
+     <replaceable>root</replaceable>
-    <arg choice='plain'><option>--system</option>
-    </arg><replaceable>system</replaceable>
    </arg>
+    
    <arg>
-    <arg choice='plain'><option>-c</option>
+    <arg choice='plain'>
-    </arg><replaceable>shell-command</replaceable>
+     <option>--system</option>
     </arg>
+     <replaceable>system</replaceable>
+   </arg>
+    
    <arg>
-    <arg choice='plain'><option>--help</option>
+    <arg choice='plain'>
+     <option>-c</option>
+    </arg>
+     <replaceable>shell-command</replaceable>
+   </arg>
+    
+   <arg>
+    <arg choice='plain'>
+     <option>--help</option>
     </arg>
    </arg>
+    
    <arg>
-    <arg choice='plain'><option>--</option>
+    <arg choice='plain'>
-    </arg><replaceable>arguments</replaceable>
+     <option>--</option>
+    </arg>
+     <replaceable>arguments</replaceable>
    </arg>
   </cmdsynopsis>
  </refsynopsisdiv>
@@ -50,7 +64,8 @@
   </para>
   <variablelist>
    <varlistentry>
-    <term><option>--root</option>
+    <term>
+     <option>--root</option>
     </term>
     <listitem>
      <para>
@@ -60,7 +75,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--system</option>
+    <term>
+     <option>--system</option>
     </term>
     <listitem>
      <para>
@@ -72,9 +88,11 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--command</option>
+    <term>
+     <option>--command</option>
     </term>
-    <term><option>-c</option>
+    <term>
+     <option>-c</option>
     </term>
     <listitem>
      <para>
@@ -83,7 +101,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--</option>
+    <term>
+     <option>--</option>
     </term>
     <listitem>
      <para>

nixos/doc/manual/man-nixos-generate-config.xml

@@ -12,16 +12,24 @@
   </refname><refpurpose>generate NixOS configuration modules</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
-  <cmdsynopsis><command>nixos-generate-config</command>
+  <cmdsynopsis>
-   <arg><option>--force</option>
+   <command>nixos-generate-config</command> 
-   </arg>
    <arg>
-    <arg choice='plain'><option>--root</option>
+    <option>--force</option>
-    </arg><replaceable>root</replaceable>
    </arg>
+    
    <arg>
-    <arg choice='plain'><option>--dir</option>
+    <arg choice='plain'>
-    </arg><replaceable>dir</replaceable>
+     <option>--root</option>
+    </arg>
+     <replaceable>root</replaceable>
+   </arg>
+    
+   <arg>
+    <arg choice='plain'>
+     <option>--dir</option>
+    </arg>
+     <replaceable>dir</replaceable>
    </arg>
   </cmdsynopsis>
  </refsynopsisdiv>
@@ -31,7 +39,8 @@
    This command writes two NixOS configuration modules:
    <variablelist>
     <varlistentry>
-     <term><option>/etc/nixos/hardware-configuration.nix</option>
+     <term>
+      <option>/etc/nixos/hardware-configuration.nix</option>
      </term>
      <listitem>
       <para>
@@ -53,7 +62,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><option>/etc/nixos/configuration.nix</option>
+     <term>
+      <option>/etc/nixos/configuration.nix</option>
      </term>
      <listitem>
       <para>
@@ -74,7 +84,8 @@
   </para>
   <variablelist>
    <varlistentry>
-    <term><option>--root</option>
+    <term>
+     <option>--root</option>
     </term>
     <listitem>
      <para>
@@ -88,7 +99,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--dir</option>
+    <term>
+     <option>--dir</option>
     </term>
     <listitem>
      <para>
@@ -99,7 +111,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--force</option>
+    <term>
+     <option>--force</option>
     </term>
     <listitem>
      <para>
@@ -109,7 +122,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--no-filesystems</option>
+    <term>
+     <option>--no-filesystems</option>
     </term>
     <listitem>
      <para>
@@ -119,7 +133,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--show-hardware-config</option>
+    <term>
+     <option>--show-hardware-config</option>
     </term>
     <listitem>
      <para>

nixos/doc/manual/man-nixos-install.xml

@@ -12,47 +12,76 @@
   </refname><refpurpose>install bootloader and NixOS</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
-  <cmdsynopsis><command>nixos-install</command>
+  <cmdsynopsis>
+   <command>nixos-install</command> 
    <arg>
-    <arg choice='plain'><option>-I</option>
+    <arg choice='plain'>
-    </arg><replaceable>path</replaceable>
+     <option>-I</option>
     </arg>
+     <replaceable>path</replaceable>
+   </arg>
+    
    <arg>
-    <arg choice='plain'><option>--root</option>
+    <arg choice='plain'>
-    </arg><replaceable>root</replaceable>
+     <option>--root</option>
     </arg>
+     <replaceable>root</replaceable>
+   </arg>
+    
    <arg>
-    <arg choice='plain'><option>--system</option>
+    <arg choice='plain'>
-    </arg><replaceable>path</replaceable>
+     <option>--system</option>
     </arg>
+     <replaceable>path</replaceable>
+   </arg>
+    
    <arg>
-    <arg choice='plain'><option>--no-channel-copy</option>
+    <arg choice='plain'>
+     <option>--no-channel-copy</option>
     </arg>
    </arg>
+    
    <arg>
-    <arg choice='plain'><option>--no-root-passwd</option>
+    <arg choice='plain'>
+     <option>--no-root-passwd</option>
     </arg>
    </arg>
+    
    <arg>
-    <arg choice='plain'><option>--no-bootloader</option>
+    <arg choice='plain'>
+     <option>--no-bootloader</option>
     </arg>
    </arg>
-   <arg><group choice='req'>
+    
-    <arg choice='plain'><option>--max-jobs</option>
-    </arg>
-    <arg choice='plain'><option>-j</option>
-    </arg></group><replaceable>number</replaceable>
-   </arg>
-   <arg><option>--cores</option><replaceable>number</replaceable>
-   </arg>
-   <arg><option>--option</option><replaceable>name</replaceable><replaceable>value</replaceable>
-   </arg>
    <arg>
-    <arg choice='plain'><option>--show-trace</option>
+    <group choice='req'> 
+    <arg choice='plain'>
+     <option>--max-jobs</option>
     </arg>
+     
+    <arg choice='plain'>
+     <option>-j</option>
     </arg>
+     </group> <replaceable>number</replaceable>
+   </arg>
+    
    <arg>
-    <arg choice='plain'><option>--help</option>
+    <option>--cores</option> <replaceable>number</replaceable>
+   </arg>
+    
+   <arg>
+    <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>
+   </arg>
+    
+   <arg>
+    <arg choice='plain'>
+     <option>--show-trace</option>
+    </arg>
+   </arg>
+    
+   <arg>
+    <arg choice='plain'>
+     <option>--help</option>
     </arg>
    </arg>
   </cmdsynopsis>
@@ -106,7 +135,8 @@
   </para>
   <variablelist>
    <varlistentry>
-    <term><option>--root</option>
+    <term>
+     <option>--root</option>
     </term>
     <listitem>
      <para>
@@ -117,7 +147,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--system</option>
+    <term>
+     <option>--system</option>
     </term>
     <listitem>
      <para>
@@ -135,7 +166,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>-I</option>
+    <term>
+     <option>-I</option>
     </term>
     <listitem>
      <para>
@@ -147,9 +179,11 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--max-jobs</option>
+    <term>
+     <option>--max-jobs</option>
     </term>
-    <term><option>-j</option>
+    <term>
+     <option>-j</option>
     </term>
     <listitem>
      <para>
@@ -160,7 +194,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--cores</option>
+    <term>
+     <option>--cores</option>
     </term>
     <listitem>
      <para>
@@ -177,7 +212,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--option</option><replaceable>name</replaceable><replaceable>value</replaceable>
+    <term>
+     <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>
     </term>
     <listitem>
      <para>
@@ -187,7 +223,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--show-trace</option>
+    <term>
+     <option>--show-trace</option>
     </term>
     <listitem>
      <para>
@@ -197,7 +234,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--help</option>
+    <term>
+     <option>--help</option>
     </term>
     <listitem>
      <para>

nixos/doc/manual/man-nixos-option.xml

@@ -12,14 +12,22 @@
   </refname><refpurpose>inspect a NixOS configuration</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
-  <cmdsynopsis><command>nixos-option</command>
+  <cmdsynopsis>
-   <arg><option>-I</option><replaceable>path</replaceable>
+   <command>nixos-option</command> 
+   <arg>
+    <option>-I</option> <replaceable>path</replaceable>
    </arg>
-   <arg><option>--verbose</option>
+    
+   <arg>
+    <option>--verbose</option>
    </arg>
-   <arg><option>--xml</option>
+    
+   <arg>
+    <option>--xml</option>
    </arg>
-   <arg choice="plain"><replaceable>option.name</replaceable>
+    
+   <arg choice="plain">
+    <replaceable>option.name</replaceable>
    </arg>
   </cmdsynopsis>
  </refsynopsisdiv>
@@ -42,7 +50,8 @@
   </para>
   <variablelist>
    <varlistentry>
-    <term><option>-I</option><replaceable>path</replaceable>
+    <term>
+     <option>-I</option> <replaceable>path</replaceable>
     </term>
     <listitem>
      <para>
@@ -52,7 +61,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--verbose</option>
+    <term>
+     <option>--verbose</option>
     </term>
     <listitem>
      <para>
@@ -62,7 +72,8 @@
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--xml</option>
+    <term>
+     <option>--xml</option>
     </term>
     <listitem>
      <para>
@@ -76,7 +87,8 @@
   <title>Environment</title>
   <variablelist>
    <varlistentry>
-    <term><envar>NIXOS_CONFIG</envar>
+    <term>
+     <envar>NIXOS_CONFIG</envar>
     </term>
     <listitem>
      <para>

nixos/doc/manual/man-nixos-rebuild.xml

@@ -12,43 +12,75 @@
   </refname><refpurpose>reconfigure a NixOS machine</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
-  <cmdsynopsis><command>nixos-rebuild</command><group choice='req'>
+  <cmdsynopsis>
-   <arg choice='plain'><option>switch</option>
+   <command>nixos-rebuild</command><group choice='req'> 
+   <arg choice='plain'>
+    <option>switch</option>
    </arg>
-   <arg choice='plain'><option>boot</option>
+    
+   <arg choice='plain'>
+    <option>boot</option>
    </arg>
-   <arg choice='plain'><option>test</option>
+    
+   <arg choice='plain'>
+    <option>test</option>
    </arg>
-   <arg choice='plain'><option>build</option>
+    
+   <arg choice='plain'>
+    <option>build</option>
    </arg>
-   <arg choice='plain'><option>dry-build</option>
+    
+   <arg choice='plain'>
+    <option>dry-build</option>
    </arg>
-   <arg choice='plain'><option>dry-activate</option>
+    
+   <arg choice='plain'>
+    <option>dry-activate</option>
    </arg>
-   <arg choice='plain'><option>build-vm</option>
+    
+   <arg choice='plain'>
+    <option>build-vm</option>
    </arg>
-   <arg choice='plain'><option>build-vm-with-bootloader</option>
+    
-   </arg></group>
+   <arg choice='plain'>
+    <option>build-vm-with-bootloader</option>
+   </arg>
+    </group>
    <sbr />
-   <arg><option>--upgrade</option>
+   <arg>
+    <option>--upgrade</option>
    </arg>
-   <arg><option>--install-bootloader</option>
+    
+   <arg>
+    <option>--install-bootloader</option>
    </arg>
-   <arg><option>--no-build-nix</option>
+    
+   <arg>
+    <option>--no-build-nix</option>
    </arg>
-   <arg><option>--fast</option>
+    
+   <arg>
+    <option>--fast</option>
    </arg>
-   <arg><option>--rollback</option>
+    
+   <arg>
+    <option>--rollback</option>
    </arg>
    <sbr />
-   <arg><group choice='req'>
+   <arg>
-    <arg choice='plain'><option>--profile-name</option>
+    <group choice='req'> 
+    <arg choice='plain'>
+     <option>--profile-name</option>
     </arg>
-    <arg choice='plain'><option>-p</option>
+     
-    </arg></group><replaceable>name</replaceable>
+    <arg choice='plain'>
+     <option>-p</option>
+    </arg>
+     </group> <replaceable>name</replaceable>
    </arg>
    <sbr />
-   <arg><option>--show-trace</option>
+   <arg>
+    <option>--show-trace</option>
    </arg>
   </cmdsynopsis>
  </refsynopsisdiv>
@@ -68,7 +100,8 @@
    operation. It must be one of the following:
    <variablelist>
     <varlistentry>
-     <term><option>switch</option>
+     <term>
+      <option>switch</option>
      </term>
      <listitem>
       <para>
@@ -82,7 +115,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><option>boot</option>
+     <term>
+      <option>boot</option>
      </term>
      <listitem>
       <para>
@@ -94,7 +128,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><option>test</option>
+     <term>
+      <option>test</option>
      </term>
      <listitem>
       <para>
@@ -107,7 +142,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><option>build</option>
+     <term>
+      <option>build</option>
      </term>
      <listitem>
       <para>
@@ -124,7 +160,8 @@ $ nix-build /path/to/nixpkgs/nixos -A system
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><option>dry-build</option>
+     <term>
+      <option>dry-build</option>
      </term>
      <listitem>
       <para>
@@ -134,7 +171,8 @@ $ nix-build /path/to/nixpkgs/nixos -A system
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><option>dry-activate</option>
+     <term>
+      <option>dry-activate</option>
      </term>
      <listitem>
       <para>
@@ -147,7 +185,8 @@ $ nix-build /path/to/nixpkgs/nixos -A system
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><option>build-vm</option>
+     <term>
+      <option>build-vm</option>
      </term>
      <listitem>
       <para>
@@ -186,7 +225,8 @@ $ ./result/bin/run-*-vm
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><option>build-vm-with-bootloader</option>
+     <term>
+      <option>build-vm-with-bootloader</option>
      </term>
      <listitem>
       <para>
@@ -213,7 +253,8 @@ $ ./result/bin/run-*-vm
   </para>
   <variablelist>
    <varlistentry>
-    <term><option>--upgrade</option>
+    <term>
+     <option>--upgrade</option>
     </term>
     <listitem>
      <para>
@@ -222,7 +263,8 @@ $ ./result/bin/run-*-vm
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--install-bootloader</option>
+    <term>
+     <option>--install-bootloader</option>
     </term>
     <listitem>
      <para>
@@ -232,7 +274,8 @@ $ ./result/bin/run-*-vm
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--no-build-nix</option>
+    <term>
+     <option>--no-build-nix</option>
     </term>
     <listitem>
      <para>
@@ -246,7 +289,8 @@ $ ./result/bin/run-*-vm
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--fast</option>
+    <term>
+     <option>--fast</option>
     </term>
     <listitem>
      <para>
@@ -258,7 +302,8 @@ $ ./result/bin/run-*-vm
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--rollback</option>
+    <term>
+     <option>--rollback</option>
     </term>
     <listitem>
      <para>
@@ -271,9 +316,11 @@ $ ./result/bin/run-*-vm
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--profile-name</option>
+    <term>
+     <option>--profile-name</option>
     </term>
-    <term><option>-p</option>
+    <term>
+     <option>-p</option>
     </term>
     <listitem>
      <para>
@@ -299,7 +346,8 @@ $ nixos-rebuild switch -p test -I nixos-config=./test.nix
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--build-host</option>
+    <term>
+     <option>--build-host</option>
     </term>
     <listitem>
      <para>
@@ -323,7 +371,8 @@ $ nixos-rebuild switch -p test -I nixos-config=./test.nix
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><option>--target-host</option>
+    <term>
+     <option>--target-host</option>
     </term>
     <listitem>
      <para>
@@ -361,7 +410,8 @@ $ nixos-rebuild switch -p test -I nixos-config=./test.nix
   <title>Environment</title>
   <variablelist>
    <varlistentry>
-    <term><envar>NIXOS_CONFIG</envar>
+    <term>
+     <envar>NIXOS_CONFIG</envar>
     </term>
     <listitem>
      <para>
@@ -371,7 +421,8 @@ $ nixos-rebuild switch -p test -I nixos-config=./test.nix
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><envar>NIX_SSHOPTS</envar>
+    <term>
+     <envar>NIX_SSHOPTS</envar>
     </term>
     <listitem>
      <para>
@@ -386,7 +437,8 @@ $ nixos-rebuild switch -p test -I nixos-config=./test.nix
   <title>Files</title>
   <variablelist>
    <varlistentry>
-    <term><filename>/run/current-system</filename>
+    <term>
+     <filename>/run/current-system</filename>
     </term>
     <listitem>
      <para>
@@ -395,7 +447,8 @@ $ nixos-rebuild switch -p test -I nixos-config=./test.nix
     </listitem>
    </varlistentry>
    <varlistentry>
-    <term><filename>/nix/var/nix/profiles/system</filename>
+    <term>
+     <filename>/nix/var/nix/profiles/system</filename>
     </term>
     <listitem>
      <para>

nixos/doc/manual/man-nixos-version.xml

@@ -11,10 +11,14 @@
   </refname><refpurpose>show the NixOS version</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
-  <cmdsynopsis><command>nixos-version</command>
+  <cmdsynopsis>
-   <arg><option>--hash</option>
+   <command>nixos-version</command> 
+   <arg>
+    <option>--hash</option>
    </arg>
-   <arg><option>--revision</option>
+    
+   <arg>
+    <option>--revision</option>
    </arg>
   </cmdsynopsis>
  </refsynopsisdiv>
@@ -29,7 +33,8 @@
    The version consists of the following elements:
    <variablelist>
     <varlistentry>
-     <term><literal>16.03</literal>
+     <term>
+      <literal>16.03</literal>
      </term>
      <listitem>
       <para>
@@ -39,7 +44,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><literal>1011</literal>
+     <term>
+      <literal>1011</literal>
      </term>
      <listitem>
       <para>
@@ -53,7 +59,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><literal>6317da4</literal>
+     <term>
+      <literal>6317da4</literal>
      </term>
      <listitem>
       <para>
@@ -63,7 +70,8 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><literal>Emu</literal>
+     <term>
+      <literal>Emu</literal>
      </term>
      <listitem>
       <para>
@@ -83,9 +91,11 @@
   </para>
   <variablelist>
    <varlistentry>
-    <term><option>--hash</option>
+    <term>
+     <option>--hash</option>
     </term>
-    <term><option>--revision</option>
+    <term>
+     <option>--revision</option>
     </term>
     <listitem>
      <para>

nixos/doc/manual/release-notes/rl-1509.xml

@@ -435,11 +435,11 @@ system.autoUpgrade.enable = true;
 <programlisting>
 system.nixos.stateVersion = "14.12";
 </programlisting>
-     The new option <option>system.nixos.stateVersion</option> ensures that certain
+     The new option <option>system.nixos.stateVersion</option> ensures that
-     configuration changes that could break existing systems (such as the
+     certain configuration changes that could break existing systems (such as
-     <command>sshd</command> host key setting) will maintain compatibility with
+     the <command>sshd</command> host key setting) will maintain compatibility
-     the specified NixOS release. NixOps sets the state version of existing
+     with the specified NixOS release. NixOps sets the state version of
-     deployments automatically.
+     existing deployments automatically.
     </para>
    </listitem>
    <listitem>

nixos/doc/manual/release-notes/rl-1809.xml

@@ -53,10 +53,12 @@ $ nix-instantiate -E '(import <nixpkgsunstable> {}).gitFull'
 
   <itemizedlist>
    <listitem>
-     <para>When enabled the <literal>iproute2</literal> will copy the files
+    <para>
-       expected by ip route (e.g., <filename>rt_tables</filename>) in
+     When enabled the <literal>iproute2</literal> will copy the files expected
+     by ip route (e.g., <filename>rt_tables</filename>) in
      <filename>/run/iproute2</filename>. This allows to write aliases for
-       routing tables for instance.</para>
+     routing tables for instance.
+    </para>
    </listitem>
   </itemizedlist>
  </section>
@@ -99,20 +101,24 @@ $ nix-instantiate -E '(import &lt;nixpkgsunstable&gt; {}).gitFull'
    </listitem>
    <listitem>
     <para>
-     The <varname>services.docker-registry.extraConfig</varname> object doesn't contain
+     The <varname>services.docker-registry.extraConfig</varname> object doesn't
-     environment variables anymore. Instead it needs to provide an object structure
+     contain environment variables anymore. Instead it needs to provide an
-     that can be mapped onto the YAML configuration defined in <link xlink:href="https://github.com/docker/distribution/blob/v2.6.2/docs/configuration.md">the <varname>docker/distribution</varname> docs</link>.
+     object structure that can be mapped onto the YAML configuration defined in
+     <link xlink:href="https://github.com/docker/distribution/blob/v2.6.2/docs/configuration.md">the
+     <varname>docker/distribution</varname> docs</link>.
     </para>
    </listitem>
    <listitem>
     <para>
-     <literal>gnucash</literal> has changed from version 2.4 to 3.x.
+     <literal>gnucash</literal> has changed from version 2.4 to 3.x. If you've
-     If you've been using <literal>gnucash</literal> (version 2.4) instead of
+     been using <literal>gnucash</literal> (version 2.4) instead of
-     <literal>gnucash26</literal> (version 2.6) you must open your Gnucash 
+     <literal>gnucash26</literal> (version 2.6) you must open your Gnucash data
-     data file(s) with <literal>gnucash26</literal> and then save them to
+     file(s) with <literal>gnucash26</literal> and then save them to upgrade
-     upgrade the file format. Then you may use your data file(s) with
+     the file format. Then you may use your data file(s) with Gnucash 3.x. See
-     Gnucash 3.x. See the upgrade <link xlink:href="https://wiki.gnucash.org/wiki/FAQ#Using_Different_Versions.2C_Up_And_Downgrade">documentation</link>.
+     the upgrade
-     Gnucash 2.4 is still available under the attribute <literal>gnucash24</literal>.
+     <link xlink:href="https://wiki.gnucash.org/wiki/FAQ#Using_Different_Versions.2C_Up_And_Downgrade">documentation</link>.
+     Gnucash 2.4 is still available under the attribute
+     <literal>gnucash24</literal>.
     </para>
    </listitem>
   </itemizedlist>
@@ -128,9 +134,9 @@ $ nix-instantiate -E '(import &lt;nixpkgsunstable&gt; {}).gitFull'
   <itemizedlist>
    <listitem>
     <para>
-     <literal>dockerTools.pullImage</literal> relies on image digest
+     <literal>dockerTools.pullImage</literal> relies on image digest instead of
-     instead of image tag to download the image. The
+     image tag to download the image. The <literal>sha256</literal> of a pulled
-     <literal>sha256</literal> of a pulled image has to be updated.
+     image has to be updated.
     </para>
    </listitem>
    <listitem>
@@ -187,32 +193,40 @@ $ nix-instantiate -E '(import &lt;nixpkgsunstable&gt; {}).gitFull'
     <para>
      The module for <option>security.dhparams</option> has two new options now:
     </para>
-
     <variablelist>
      <varlistentry>
-      <term><option>security.dhparams.stateless</option></term>
+      <term>
-      <listitem><para>
+       <option>security.dhparams.stateless</option>
+      </term>
+      <listitem>
+       <para>
         Puts the generated Diffie-Hellman parameters into the Nix store instead
         of managing them in a stateful manner in
         <filename class="directory">/var/lib/dhparams</filename>.
-      </para></listitem>
+       </para>
+      </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>security.dhparams.defaultBitSize</option></term>
+      <term>
-      <listitem><para>
+       <option>security.dhparams.defaultBitSize</option>
-       The default bit size to use for the generated Diffie-Hellman parameters.
+      </term>
-      </para></listitem>
+      <listitem>
+       <para>
+        The default bit size to use for the generated Diffie-Hellman
+        parameters.
+       </para>
+      </listitem>
      </varlistentry>
     </variablelist>
-
+    <note>
-    <note><para>
+     <para>
       The path to the actual generated parameter files should now be queried
       using
       <literal>config.security.dhparams.params.<replaceable>name</replaceable>.path</literal>
       because it might be either in the Nix store or in a directory configured
       by <option>security.dhparams.path</option>.
-    </para></note>
+     </para>
-
+    </note>
     <note>
      <title>For developers:</title>
      <para>
@@ -237,20 +251,23 @@ $ nix-instantiate -E '(import &lt;nixpkgsunstable&gt; {}).gitFull'
    </listitem>
    <listitem>
     <para>
-     <literal>networking.networkmanager.useDnsmasq</literal> has been deprecated. Use
+     <literal>networking.networkmanager.useDnsmasq</literal> has been
-     <literal>networking.networkmanager.dns</literal> instead.
+     deprecated. Use <literal>networking.networkmanager.dns</literal> instead.
     </para>
    </listitem>
    <listitem>
     <para>
-     The option <varname>services.kubernetes.apiserver.admissionControl</varname>
+     The option
-     was renamed to <varname>services.kubernetes.apiserver.enableAdmissionPlugins</varname>.
+     <varname>services.kubernetes.apiserver.admissionControl</varname> was
+     renamed to
+     <varname>services.kubernetes.apiserver.enableAdmissionPlugins</varname>.
     </para>
    </listitem>
    <listitem>
     <para>
      Recommented way to access the Kubernetes Dashboard is with HTTPS (TLS)
-     Therefore; public service port for the dashboard has changed to 443 (container port 8443) and scheme to https.
+     Therefore; public service port for the dashboard has changed to 443
+     (container port 8443) and scheme to https.
     </para>
    </listitem>
   </itemizedlist>

nixos/doc/manual/shell.nix

@@ -4,5 +4,5 @@ in
 pkgs.mkShell {
   name = "nixos-manual";
 
-  buildInputs = with pkgs; [ xmlformat jing xmloscopy ];
+  buildInputs = with pkgs; [ xmlformat jing xmloscopy ruby ];
 }

nixos/doc/varlistentry-fixer.rb

@@ -0,0 +1,124 @@
+#!/usr/bin/env ruby
+
+# This script is written intended as a living, evolving tooling
+# to fix oopsies within the docbook documentation.
+#
+# This is *not* a formatter. It, instead, handles some known cases
+# where something bad happened, and fixing it manually is tedious.
+#
+# Read the code to see the different cases it handles.
+#
+# ALWAYS `make format` after fixing with this!
+# ALWAYS read the changes, this tool isn't yet proven to be always right.
+
+require "rexml/document"
+include REXML
+
+if ARGV.length < 1 then
+	$stderr.puts "Needs a filename."
+	exit 1
+end
+
+filename = ARGV.shift
+doc = Document.new(File.open(filename))
+
+$touched = false
+
+# Fixing varnames having a sibling element without spacing.
+# This is to fix an initial `xmlformat` issue where `term`
+# would mangle as spaces.
+#
+#   <varlistentry>
+#    <term><varname>types.separatedString</varname><replaceable>sep</replaceable> <----
+#    </term>
+#    ...
+#
+# Generates: types.separatedStringsep
+#                               ^^^^
+#
+# <varlistentry xml:id='fun-makeWrapper'>
+#  <term>
+#   <function>makeWrapper</function><replaceable>executable</replaceable><replaceable>wrapperfile</replaceable><replaceable>args</replaceable>  <----
+#  </term>
+#
+# Generates: makeWrapperexecutablewrapperfileargs
+#                     ^^^^      ^^^^    ^^  ^^
+#
+#    <term>
+#     <option>--option</option><replaceable>name</replaceable><replaceable>value</replaceable> <-----
+#    </term>
+#
+# Generates: --optionnamevalue
+#                   ^^  ^^
+doc.elements.each("//varlistentry/term") do |term|
+	["varname", "function", "option", "replaceable"].each do |prev_name|
+		term.elements.each(prev_name) do |el|
+			if el.next_element and
+					el.next_element.name == "replaceable" and
+					el.next_sibling_node.class == Element
+				then
+				$touched = true
+				term.insert_after(el, Text.new(" "))
+			end
+		end
+	end
+end
+
+
+
+#  <cmdsynopsis>
+#   <command>nixos-option</command>
+#   <arg>
+#    <option>-I</option><replaceable>path</replaceable>        <------
+#   </arg>
+#
+# Generates: -Ipath
+#             ^^
+doc.elements.each("//cmdsynopsis/arg") do |term|
+	["option", "replaceable"].each do |prev_name|
+		term.elements.each(prev_name) do |el|
+			if el.next_element and
+				el.next_element.name == "replaceable" and
+				el.next_sibling_node.class == Element
+			then
+				$touched = true
+				term.insert_after(el, Text.new(" "))
+			end
+		end
+	end
+end
+
+#  <cmdsynopsis>
+#   <arg>
+#    <group choice='req'>
+#    <arg choice='plain'>
+#     <option>--profile-name</option>
+#    </arg>
+#
+#    <arg choice='plain'>
+#     <option>-p</option>
+#    </arg>
+#     </group><replaceable>name</replaceable>   <----
+#   </arg>
+#
+# Generates: [{--profile-name | -p }name]
+#                                   ^^^^
+doc.elements.each("//cmdsynopsis/arg") do |term|
+	["group"].each do |prev_name|
+		term.elements.each(prev_name) do |el|
+			if el.next_element and
+				el.next_element.name == "replaceable" and
+				el.next_sibling_node.class == Element
+			then
+				$touched = true
+				term.insert_after(el, Text.new(" "))
+			end
+		end
+	end
+end
+
+
+if $touched then
+	doc.context[:attribute_quote] = :quote
+	doc.write(output: File.open(filename, "w"))
+end

nixos/doc/xmlformat.conf

@@ -67,6 +67,7 @@ programlisting screen
   entry-break = 0
   exit-break = 0
 
-
+# This is needed so that the spacing inside those tags is kept.
-#term
+term cmdsynopsis arg
-#  format       inline
+  normalize yes
+  format    block