man-nixos-rebuild.xml: Improve layout

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

@@ -7,10 +7,12 @@
   <refmiscinfo class="source">NixOS</refmiscinfo>
 <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
  </refmeta>
+
  <refnamediv>
   <refname><command>nixos-rebuild</command>
   </refname><refpurpose>reconfigure a NixOS machine</refpurpose>
  </refnamediv>
+
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>nixos-rebuild</command><group choice='req'>
@@ -74,6 +76,7 @@
    <arg>
     <option>--builders</option> <replaceable>builder-spec</replaceable>
    </arg>
+
    <sbr />
    <arg>
     <group choice='req'>
@@ -121,8 +124,10 @@
    </arg>
   </cmdsynopsis>
  </refsynopsisdiv>
+
  <refsection>
   <title>Description</title>
+
   <para>
    This command updates the system so that it corresponds to the configuration
    specified in <filename>/etc/nixos/configuration.nix</filename>. Thus, every
@@ -133,9 +138,11 @@
    (re)starts any system services if needed. Please note that user services need
    to be started manually as they aren't detected by the activation script at the moment.
   </para>
+
   <para>
    This command has one required argument, which specifies the desired
    operation. It must be one of the following:
+
    <variablelist>
     <varlistentry>
      <term>
@@ -152,6 +159,7 @@
       </para>
      </listitem>
     </varlistentry>
+
     <varlistentry>
      <term>
       <option>boot</option>
@@ -165,6 +173,7 @@
       </para>
      </listitem>
     </varlistentry>
+
     <varlistentry>
      <term>
       <option>test</option>
@@ -179,6 +188,7 @@
       </para>
      </listitem>
     </varlistentry>
+
     <varlistentry>
      <term>
       <option>build</option>
@@ -197,6 +207,7 @@
       </para>
      </listitem>
     </varlistentry>
+
     <varlistentry>
      <term>
       <option>dry-build</option>
@@ -208,6 +219,7 @@
       </para>
      </listitem>
     </varlistentry>
+
     <varlistentry>
      <term>
       <option>dry-activate</option>
@@ -222,6 +234,7 @@
       </para>
      </listitem>
     </varlistentry>
+
     <varlistentry>
      <term>
       <option>edit</option>
@@ -232,6 +245,7 @@
       </para>
      </listitem>
     </varlistentry>
+
     <varlistentry>
      <term>
       <option>build-vm</option>
@@ -249,12 +263,14 @@
 <prompt>$ </prompt>./result/bin/run-*-vm
 </screen>
       </para>
+
       <para>
        The VM is implemented using the <literal>qemu</literal> package. For
        best performance, you should load the <literal>kvm-intel</literal> or
        <literal>kvm-amd</literal> kernel modules to get hardware
        virtualisation.
       </para>
+
       <para>
        The VM mounts the Nix store of the host through the 9P file system. The
        host Nix store is read-only, so Nix commands that modify the Nix store
@@ -262,6 +278,7 @@
        <command>nixos-rebuild</command>; to change the VM’s configuration,
        you must halt the VM and re-run the commands above.
       </para>
+
       <para>
        The VM has its own <literal>ext3</literal> root file system, which is
        automatically created when the VM is first started, and is persistent
@@ -272,6 +289,7 @@
       </para>
      </listitem>
     </varlistentry>
+
     <varlistentry>
      <term>
       <option>build-vm-with-bootloader</option>
@@ -294,11 +312,13 @@
    </variablelist>
   </para>
  </refsection>
+
  <refsection>
   <title>Options</title>
   <para>
    This command accepts the following options:
   </para>
+
   <variablelist>
    <varlistentry>
     <term>
@@ -310,6 +330,7 @@
      </para>
     </listitem>
    </varlistentry>
+
    <varlistentry>
     <term>
      <option>--install-bootloader</option>
@@ -321,6 +342,7 @@
      </para>
     </listitem>
    </varlistentry>
+
    <varlistentry>
     <term>
      <option>--no-build-nix</option>
@@ -336,6 +358,7 @@
      </para>
     </listitem>
    </varlistentry>
+
    <varlistentry>
     <term>
      <option>--fast</option>
@@ -349,6 +372,7 @@
      </para>
     </listitem>
    </varlistentry>
+
    <varlistentry>
     <term>
      <option>--rollback</option>
@@ -363,6 +387,7 @@
      </para>
     </listitem>
    </varlistentry>
+
    <varlistentry>
     <term>
      <option>--builders</option> <replaceable>builder-spec</replaceable>
@@ -382,6 +407,7 @@
      </para>
     </listitem>
    </varlistentry>
+
    <varlistentry>
     <term>
      <option>--profile-name</option>
@@ -412,6 +438,7 @@
      </para>
     </listitem>
    </varlistentry>
+
    <varlistentry>
     <term>
      <option>--build-host</option>
@@ -437,6 +464,7 @@
      </para>
     </listitem>
    </varlistentry>
+
    <varlistentry>
     <term>
      <option>--target-host</option>
@@ -449,6 +477,7 @@
       be accessible over ssh, and for the commands <option>switch</option>,
       <option>boot</option> and <option>test</option> you need root access.
      </para>
+
      <para>
       If <option>--build-host</option> is not explicitly specified,
       <option>--build-host</option> will implicitly be set to the same value as
@@ -457,6 +486,7 @@
       place remotely (and no build artifacts will be copied to the local
       machine).
      </para>
+
      <para>
       You can include a remote user name in the host name
       (<replaceable>user@host</replaceable>). You can also set ssh options by
@@ -465,6 +495,7 @@
     </listitem>
    </varlistentry>
   </variablelist>
+
   <para>
    In addition, <command>nixos-rebuild</command> accepts various Nix-related
    flags, including <option>--max-jobs</option> / <option>-j</option>,
@@ -473,8 +504,10 @@
    <option>-v</option>. See the Nix manual for details.
   </para>
  </refsection>
+
  <refsection>
   <title>Environment</title>
+
   <variablelist>
    <varlistentry>
     <term>
@@ -487,6 +520,7 @@
      </para>
     </listitem>
    </varlistentry>
+
    <varlistentry>
     <term>
      <envar>NIX_SSHOPTS</envar>
@@ -500,9 +534,12 @@
    </varlistentry>
   </variablelist>
  </refsection>
+
  <refsection>
   <title>Files</title>
+
   <variablelist>
+
    <varlistentry>
     <term>
      <filename>/run/current-system</filename>
@@ -513,6 +550,7 @@
      </para>
     </listitem>
    </varlistentry>
+
    <varlistentry>
     <term>
      <filename>/nix/var/nix/profiles/system</filename>
@@ -524,8 +562,10 @@
      </para>
     </listitem>
    </varlistentry>
+
   </variablelist>
  </refsection>
+
  <refsection>
   <title>Bugs</title>
   <para>