nixos/manual: translate manpages to mdoc

since we want to move away from docbook and having docbook manpages
around is going to block further progress we have to translate the
current nixos manpages from docbook it *something* else. mdoc seems the
most appropriate choice since markdown can't represent all the things
manpages can differentiate with even more extensions. if we ever need
html manpages we can render them using troff, like many of the online
manpage viewers, or rewrite them again. since we haven't had html
manpages for any of these in many years that seems unlikely to happen.

unlike most of the recent markdown conversions this comes with a lot of
minor rendering changes, mostly in spacing. docbook-xslt creates manual
pages in a very different dialect than mdoc (which is used here).

17 files changed, 1250 insertions, 1945 deletions

diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index 913058746b35c..264a8bcef27c2 100644
--- a/nixos/doc/manual/default.nix
+++ b/nixos/doc/manual/default.nix
@@ -254,12 +254,17 @@ in rec {
   # Generate the NixOS manpages.
   manpages = runCommand "nixos-manpages"
     { inherit sources;
-      nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
+      nativeBuildInputs = [
+        buildPackages.libxml2.bin
+        buildPackages.libxslt.bin
+        buildPackages.installShellFiles
+      ];
       allowedReferences = ["out"];
     }
     ''
       # Generate manpages.
-      mkdir -p $out/share/man
+      mkdir -p $out/share/man/man8
+      installManPage ${./manpages}/*
       xsltproc --nonet \
         --maxdepth 6000 \
         --param man.output.in.separate.dir 1 \
diff --git a/nixos/doc/manual/man-nixos-build-vms.xml b/nixos/doc/manual/man-nixos-build-vms.xml
deleted file mode 100644
index fa7c8c0c6d799..0000000000000
--- a/nixos/doc/manual/man-nixos-build-vms.xml
+++ /dev/null
@@ -1,138 +0,0 @@
-<refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude">
- <refmeta>
-  <refentrytitle><command>nixos-build-vms</command>
-  </refentrytitle><manvolnum>8</manvolnum>
-  <refmiscinfo class="source">NixOS</refmiscinfo>
-<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
- </refmeta>
- <refnamediv>
-  <refname><command>nixos-build-vms</command></refname>
-  <refpurpose>build a network of virtual machines from a network of NixOS configurations</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
-  <cmdsynopsis>
-   <command>nixos-build-vms</command>
-   <arg>
-    <option>--show-trace</option>
-   </arg>
-
-   <arg>
-    <option>--no-out-link</option>
-   </arg>
-
-   <arg>
-    <option>--help</option>
-  </arg>
-
-  <arg>
-    <option>--option</option>
-    <replaceable>name</replaceable>
-    <replaceable>value</replaceable>
-  </arg>
-
-   <arg choice="plain">
-    <replaceable>network.nix</replaceable>
-   </arg>
-  </cmdsynopsis>
- </refsynopsisdiv>
- <refsection>
-  <title>Description</title>
-  <para>
-   This command builds a network of QEMU-KVM virtual machines of a Nix
-   expression specifying a network of NixOS machines. The virtual network can
-   be started by executing the <filename>bin/run-vms</filename> shell script
-   that is generated by this command. By default, a <filename>result</filename>
-   symlink is produced that points to the generated virtual network.
-  </para>
-  <para>
-   A network Nix expression has the following structure:
-<screen>
-{
-  test1 = {pkgs, config, ...}:
-    {
-      services.openssh.enable = true;
-      nixpkgs.localSystem.system = "i686-linux";
-      deployment.targetHost = "test1.example.net";
-
-      # Other NixOS options
-    };
-
-  test2 = {pkgs, config, ...}:
-    {
-      services.openssh.enable = true;
-      services.httpd.enable = true;
-      environment.systemPackages = [ pkgs.lynx ];
-      nixpkgs.localSystem.system = "x86_64-linux";
-      deployment.targetHost = "test2.example.net";
-
-      # Other NixOS options
-    };
-}
-</screen>
-   Each attribute in the expression represents a machine in the network (e.g.
-   <varname>test1</varname> and <varname>test2</varname>) referring to a
-   function defining a NixOS configuration. In each NixOS configuration, two
-   attributes have a special meaning. The
-   <varname>deployment.targetHost</varname> specifies the address (domain name
-   or IP address) of the system which is used by <command>ssh</command> to
-   perform remote deployment operations. The
-   <varname>nixpkgs.localSystem.system</varname> attribute can be used to
-   specify an architecture for the target machine, such as
-   <varname>i686-linux</varname> which builds a 32-bit NixOS configuration.
-   Omitting this property will build the configuration for the same
-   architecture as the host system.
-  </para>
- </refsection>
- <refsection>
-  <title>Options</title>
-  <para>
-   This command accepts the following options:
-  </para>
-  <variablelist>
-   <varlistentry>
-    <term>
-     <option>--show-trace</option>
-    </term>
-    <listitem>
-     <para>
-      Shows a trace of the output.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--no-out-link</option>
-    </term>
-    <listitem>
-     <para>
-      Do not create a 'result' symlink.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>-h</option>, <option>--help</option>
-    </term>
-    <listitem>
-     <para>
-      Shows the usage of this command to the user.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>
-    </term>
-    <listitem>
-     <para>Set the Nix configuration option
-      <replaceable>name</replaceable> to <replaceable>value</replaceable>.
-      This overrides settings in the Nix configuration file (see
-      <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
- </refsection>
-</refentry>
diff --git a/nixos/doc/manual/man-nixos-enter.xml b/nixos/doc/manual/man-nixos-enter.xml
deleted file mode 100644
index 41f0e6b975159..0000000000000
--- a/nixos/doc/manual/man-nixos-enter.xml
+++ /dev/null
@@ -1,154 +0,0 @@
-<refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude">
- <refmeta>
-  <refentrytitle><command>nixos-enter</command>
-  </refentrytitle><manvolnum>8</manvolnum>
-  <refmiscinfo class="source">NixOS</refmiscinfo>
-<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
- </refmeta>
- <refnamediv>
-  <refname><command>nixos-enter</command></refname>
-  <refpurpose>run a command in a NixOS chroot environment</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
-  <cmdsynopsis>
-   <command>nixos-enter</command>
-   <arg>
-    <arg choice='plain'>
-     <option>--root</option>
-    </arg>
-     <replaceable>root</replaceable>
-   </arg>
-
-   <arg>
-    <arg choice='plain'>
-     <option>--system</option>
-    </arg>
-     <replaceable>system</replaceable>
-   </arg>
-
-   <arg>
-    <arg choice='plain'>
-     <option>-c</option>
-    </arg>
-     <replaceable>shell-command</replaceable>
-   </arg>
-
-   <arg>
-    <arg choice='plain'>
-     <option>--silent</option>
-    </arg>
-   </arg>
-
-   <arg>
-    <arg choice='plain'>
-     <option>--help</option>
-    </arg>
-   </arg>
-
-   <arg>
-    <arg choice='plain'>
-     <option>--</option>
-    </arg>
-     <replaceable>arguments</replaceable>
-   </arg>
-  </cmdsynopsis>
- </refsynopsisdiv>
- <refsection>
-  <title>Description</title>
-  <para>
-   This command runs a command in a NixOS chroot environment, that is, in a
-   filesystem hierarchy previously prepared using
-   <command>nixos-install</command>.
-  </para>
- </refsection>
- <refsection>
-  <title>Options</title>
-  <para>
-   This command accepts the following options:
-  </para>
-  <variablelist>
-   <varlistentry>
-    <term>
-     <option>--root</option>
-    </term>
-    <listitem>
-     <para>
-      The path to the NixOS system you want to enter. It defaults to
-      <filename>/mnt</filename>.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--system</option>
-    </term>
-    <listitem>
-     <para>
-      The NixOS system configuration to use. It defaults to
-      <filename>/nix/var/nix/profiles/system</filename>. You can enter a
-      previous NixOS configuration by specifying a path such as
-      <filename>/nix/var/nix/profiles/system-106-link</filename>.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--command</option>
-    </term>
-    <term>
-     <option>-c</option>
-    </term>
-    <listitem>
-     <para>
-      The bash command to execute.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--silent</option>
-    </term>
-    <listitem>
-     <para>
-       Suppresses all output from the activation script of the target system.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--</option>
-    </term>
-    <listitem>
-     <para>
-      Interpret the remaining arguments as the program name and arguments to be
-      invoked. The program is not executed in a shell.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
- </refsection>
- <refsection>
-  <title>Examples</title>
-  <para>
-   Start an interactive shell in the NixOS installation in
-   <filename>/mnt</filename>:
-  </para>
-<screen>
-<prompt># </prompt>nixos-enter --root /mnt
-</screen>
-  <para>
-   Run a shell command:
-  </para>
-<screen>
-<prompt># </prompt>nixos-enter -c 'ls -l /; cat /proc/mounts'
-</screen>
-  <para>
-   Run a non-shell command:
-  </para>
-<screen>
-# nixos-enter -- cat /proc/mounts
-</screen>
- </refsection>
-</refentry>
diff --git a/nixos/doc/manual/man-nixos-generate-config.xml b/nixos/doc/manual/man-nixos-generate-config.xml
deleted file mode 100644
index 9ac3b918ff693..0000000000000
--- a/nixos/doc/manual/man-nixos-generate-config.xml
+++ /dev/null
@@ -1,214 +0,0 @@
-<refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude">
- <refmeta>
-  <refentrytitle><command>nixos-generate-config</command>
-  </refentrytitle><manvolnum>8</manvolnum>
-  <refmiscinfo class="source">NixOS</refmiscinfo>
-<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
- </refmeta>
- <refnamediv>
-  <refname><command>nixos-generate-config</command></refname>
-  <refpurpose>generate NixOS configuration modules</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
-  <cmdsynopsis>
-   <command>nixos-generate-config</command>
-   <arg>
-    <option>--force</option>
-   </arg>
-
-   <arg>
-    <arg choice='plain'>
-     <option>--root</option>
-    </arg>
-     <replaceable>root</replaceable>
-   </arg>
-
-   <arg>
-    <arg choice='plain'>
-     <option>--dir</option>
-    </arg>
-     <replaceable>dir</replaceable>
-   </arg>
-  </cmdsynopsis>
- </refsynopsisdiv>
- <refsection>
-  <title>Description</title>
-  <para>
-   This command writes two NixOS configuration modules:
-   <variablelist>
-    <varlistentry>
-     <term>
-      <option>/etc/nixos/hardware-configuration.nix</option>
-     </term>
-     <listitem>
-      <para>
-       This module sets NixOS configuration options based on your current
-       hardware configuration. In particular, it sets the
-       <option>fileSystem</option> option to reflect all currently mounted file
-       systems, the <option>swapDevices</option> option to reflect active swap
-       devices, and the <option>boot.initrd.*</option> options to ensure that
-       the initial ramdisk contains any kernel modules necessary for mounting
-       the root file system.
-      </para>
-      <para>
-       If this file already exists, it is overwritten. Thus, you should not
-       modify it manually. Rather, you should include it from your
-       <filename>/etc/nixos/configuration.nix</filename>, and re-run
-       <command>nixos-generate-config</command> to update it whenever your
-       hardware configuration changes.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>
-      <option>/etc/nixos/configuration.nix</option>
-     </term>
-     <listitem>
-      <para>
-       This is the main NixOS system configuration module. If it already
-       exists, it’s left unchanged. Otherwise,
-       <command>nixos-generate-config</command> will write a template for you
-       to customise.
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
- </refsection>
- <refsection>
-  <title>Options</title>
-  <para>
-   This command accepts the following options:
-  </para>
-  <variablelist>
-   <varlistentry>
-    <term>
-     <option>--root</option>
-    </term>
-    <listitem>
-     <para>
-      If this option is given, treat the directory
-      <replaceable>root</replaceable> as the root of the file system. This
-      means that configuration files will be written to
-      <filename><replaceable>root</replaceable>/etc/nixos</filename>, and that
-      any file systems outside of <replaceable>root</replaceable> are ignored
-      for the purpose of generating the <option>fileSystems</option> option.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--dir</option>
-    </term>
-    <listitem>
-     <para>
-      If this option is given, write the configuration files to the directory
-      <replaceable>dir</replaceable> instead of
-      <filename>/etc/nixos</filename>.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--force</option>
-    </term>
-    <listitem>
-     <para>
-      Overwrite <filename>/etc/nixos/configuration.nix</filename> if it already
-      exists.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--no-filesystems</option>
-    </term>
-    <listitem>
-     <para>
-      Omit everything concerning file systems and swap devices from the
-      hardware configuration.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--show-hardware-config</option>
-    </term>
-    <listitem>
-     <para>
-      Don't generate <filename>configuration.nix</filename> or
-      <filename>hardware-configuration.nix</filename> and print the hardware
-      configuration to stdout only.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
- </refsection>
- <refsection>
-  <title>Examples</title>
-  <para>
-   This command is typically used during NixOS installation to write initial
-   configuration modules. For example, if you created and mounted the target
-   file systems on <filename>/mnt</filename> and
-   <filename>/mnt/boot</filename>, you would run:
-<screen>
-<prompt>$ </prompt>nixos-generate-config --root /mnt
-</screen>
-   The resulting file
-   <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> might look
-   like this:
-<programlisting>
-# Do not modify this file!  It was generated by ‘nixos-generate-config’
-# and may be overwritten by future invocations.  Please make changes
-# to /etc/nixos/configuration.nix instead.
-{ config, pkgs, ... }:
-
-{
-  imports =
-    [ &lt;nixos/modules/installer/scan/not-detected.nix&gt;
-    ];
-
-  boot.initrd.availableKernelModules = [ "ehci_hcd" "ahci" ];
-  boot.kernelModules = [ "kvm-intel" ];
-  boot.extraModulePackages = [ ];
-
-  fileSystems."/" =
-    { device = "/dev/disk/by-label/nixos";
-      fsType = "ext3";
-      options = [ "rw" "data=ordered" "relatime" ];
-    };
-
-  fileSystems."/boot" =
-    { device = "/dev/sda1";
-      fsType = "ext3";
-      options = [ "rw" "errors=continue" "user_xattr" "acl" "barrier=1" "data=writeback" "relatime" ];
-    };
-
-  swapDevices =
-    [ { device = "/dev/sda2"; }
-    ];
-
-  nix.maxJobs = 8;
-}
-</programlisting>
-   It will also create a basic
-   <filename>/mnt/etc/nixos/configuration.nix</filename>, which you should edit
-   to customise the logical configuration of your system. This file includes
-   the result of the hardware scan as follows:
-<programlisting>
-  imports = [ ./hardware-configuration.nix ];
-</programlisting>
-  </para>
-  <para>
-   After installation, if your hardware configuration changes, you can run:
-<screen>
-<prompt>$ </prompt>nixos-generate-config
-</screen>
-   to update <filename>/etc/nixos/hardware-configuration.nix</filename>. Your
-   <filename>/etc/nixos/configuration.nix</filename> will
-   <emphasis>not</emphasis> be overwritten.
-  </para>
- </refsection>
-</refentry>
diff --git a/nixos/doc/manual/man-nixos-install.xml b/nixos/doc/manual/man-nixos-install.xml
deleted file mode 100644
index eb6680b65677e..0000000000000
--- a/nixos/doc/manual/man-nixos-install.xml
+++ /dev/null
@@ -1,357 +0,0 @@
-<refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude">
- <refmeta>
-  <refentrytitle><command>nixos-install</command>
-  </refentrytitle><manvolnum>8</manvolnum>
-  <refmiscinfo class="source">NixOS</refmiscinfo>
-<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
- </refmeta>
- <refnamediv>
-  <refname><command>nixos-install</command></refname>
-  <refpurpose>install bootloader and NixOS</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
-  <cmdsynopsis>
-   <command>nixos-install</command>
-   <arg>
-    <group choice='req'>
-     <arg choice='plain'>
-      <option>--verbose</option>
-     </arg>
-     <arg choice='plain'>
-      <option>-v</option>
-     </arg>
-    </group>
-   </arg>
-   <arg>
-    <arg choice='plain'>
-     <option>-I</option>
-    </arg>
-     <replaceable>path</replaceable>
-   </arg>
-
-   <arg>
-    <arg choice='plain'>
-     <option>--root</option>
-    </arg>
-     <replaceable>root</replaceable>
-   </arg>
-
-   <arg>
-    <arg choice='plain'>
-     <option>--system</option>
-    </arg>
-     <replaceable>path</replaceable>
-   </arg>
-
-   <arg>
-    <option>--flake</option> <replaceable>flake-uri</replaceable>
-   </arg>
-
-   <arg>
-    <group choice='req'>
-     <arg choice='plain'><option>--impure</option></arg>
-    </group>
-   </arg>
-
-   <arg>
-     <arg choice='plain'>
-       <option>--channel</option>
-     </arg>
-     <replaceable>channel</replaceable>
-   </arg>
-
-   <arg>
-    <arg choice='plain'>
-     <option>--no-channel-copy</option>
-    </arg>
-   </arg>
-
-   <arg>
-    <group choice='req'>
-     <arg choice='plain'>
-      <option>--no-root-password</option>
-     </arg>
-     <arg choice='plain'>
-      <option>--no-root-passwd</option>
-     </arg>
-    </group>
-   </arg>
-
-   <arg>
-    <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>
-    </arg>
-   </arg>
-
-   <arg>
-    <arg choice='plain'>
-     <option>--keep-going</option>
-    </arg>
-   </arg>
-
-   <arg>
-    <arg choice='plain'>
-     <option>--help</option>
-    </arg>
-   </arg>
-  </cmdsynopsis>
- </refsynopsisdiv>
- <refsection>
-  <title>Description</title>
-  <para>
-   This command installs NixOS in the file system mounted on
-   <filename>/mnt</filename>, based on the NixOS configuration specified in
-   <filename>/mnt/etc/nixos/configuration.nix</filename>. It performs the
-   following steps:
-   <itemizedlist>
-    <listitem>
-     <para>
-      It copies Nix and its dependencies to
-      <filename>/mnt/nix/store</filename>.
-     </para>
-    </listitem>
-    <listitem>
-     <para>
-      It runs Nix in <filename>/mnt</filename> to build the NixOS configuration
-      specified in <filename>/mnt/etc/nixos/configuration.nix</filename>.
-     </para>
-    </listitem>
-    <listitem>
-      <para>
-        It installs the current channel <quote>nixos</quote> in the target channel
-        profile (unless <option>--no-channel-copy</option> is specified).
-      </para>
-    </listitem>
-    <listitem>
-     <para>
-      It installs the GRUB boot loader on the device specified in the option
-      <option>boot.loader.grub.device</option> (unless
-      <option>--no-bootloader</option> is specified), and generates a GRUB
-      configuration file that boots into the NixOS configuration just
-      installed.
-     </para>
-    </listitem>
-    <listitem>
-     <para>
-      It prompts you for a password for the root account (unless
-      <option>--no-root-password</option> is specified).
-     </para>
-    </listitem>
-   </itemizedlist>
-  </para>
-  <para>
-   This command is idempotent: if it is interrupted or fails due to a temporary
-   problem (e.g. a network issue), you can safely re-run it.
-  </para>
- </refsection>
- <refsection>
-  <title>Options</title>
-  <para>
-   This command accepts the following options:
-  </para>
-  <variablelist>
-   <varlistentry>
-    <term><option>--verbose</option> / <option>-v</option></term>
-    <listitem>
-     <para>Increases the level of verbosity of diagnostic messages
-     printed on standard error.  For each Nix operation, the information
-     printed on standard output is well-defined; any diagnostic
-     information is printed on standard error, never on standard
-     output.</para>
-     <para>Please note that this option may be specified repeatedly.</para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--root</option>
-    </term>
-    <listitem>
-     <para>
-      Defaults to <filename>/mnt</filename>. If this option is given, treat the
-      directory <replaceable>root</replaceable> as the root of the NixOS
-      installation.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--system</option>
-    </term>
-    <listitem>
-     <para>
-      If this option is provided, <command>nixos-install</command> will install
-      the specified closure rather than attempt to build one from
-      <filename>/mnt/etc/nixos/configuration.nix</filename>.
-     </para>
-     <para>
-      The closure must be an appropriately configured NixOS system, with boot
-      loader and partition configuration that fits the target host. Such a
-      closure is typically obtained with a command such as <command>nix-build
-      -I nixos-config=./configuration.nix '&lt;nixpkgs/nixos&gt;' -A system
-      --no-out-link</command>
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--flake</option> <replaceable>flake-uri</replaceable>#<replaceable>name</replaceable>
-    </term>
-    <listitem>
-     <para>
-      Build the NixOS system from the specified flake.
-      The flake must contain an output named
-      <literal>nixosConfigurations.<replaceable>name</replaceable></literal>.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-     <term>
-       <option>--channel</option>
-     </term>
-     <listitem>
-       <para>
-         If this option is provided, do not copy the current
-         <quote>nixos</quote> channel to the target host. Instead, use the
-         specified derivation.
-       </para>
-     </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>-I</option>
-    </term>
-    <listitem>
-     <para>
-      Add a path to the Nix expression search path. This option may be given
-      multiple times. See the NIX_PATH environment variable for information on
-      the semantics of the Nix search path. Paths added through
-      <replaceable>-I</replaceable> take precedence over NIX_PATH.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--max-jobs</option>
-    </term>
-    <term>
-     <option>-j</option>
-    </term>
-    <listitem>
-     <para>
-      Sets the maximum number of build jobs that Nix will perform in parallel
-      to the specified number. The default is <literal>1</literal>. A higher
-      value is useful on SMP systems or to exploit I/O latency.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--cores</option>
-    </term>
-    <listitem>
-     <para>
-      Sets the value of the <envar>NIX_BUILD_CORES</envar> environment variable
-      in the invocation of builders. Builders can use this variable at their
-      discretion to control the maximum amount of parallelism. For instance, in
-      Nixpkgs, if the derivation attribute
-      <varname>enableParallelBuilding</varname> is set to
-      <literal>true</literal>, the builder passes the
-      <option>-j<replaceable>N</replaceable></option> flag to GNU Make. The
-      value <literal>0</literal> means that the builder should use all
-      available CPU cores in the system.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>
-    </term>
-    <listitem>
-     <para>
-      Set the Nix configuration option <replaceable>name</replaceable> to
-      <replaceable>value</replaceable>.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--show-trace</option>
-    </term>
-    <listitem>
-     <para>
-      Causes Nix to print out a stack trace in case of Nix expression
-      evaluation errors.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--keep-going</option>
-    </term>
-    <listitem>
-     <para>
-      Causes Nix to continue building derivations as far as possible
-      in the face of failed builds.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>--help</option>
-    </term>
-    <listitem>
-     <para>
-      Synonym for <command>man nixos-install</command>.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
- </refsection>
- <refsection>
-  <title>Examples</title>
-  <para>
-   A typical NixOS installation is done by creating and mounting a file system
-   on <filename>/mnt</filename>, generating a NixOS configuration in
-   <filename>/mnt/etc/nixos/configuration.nix</filename>, and running
-   <command>nixos-install</command>. For instance, if we want to install NixOS
-   on an <literal>ext4</literal> file system created in
-   <filename>/dev/sda1</filename>:
-<screen>
-<prompt>$ </prompt>mkfs.ext4 /dev/sda1
-<prompt>$ </prompt>mount /dev/sda1 /mnt
-<prompt>$ </prompt>nixos-generate-config --root /mnt
-<prompt>$ </prompt># edit /mnt/etc/nixos/configuration.nix
-<prompt>$ </prompt>nixos-install
-<prompt>$ </prompt>reboot
-</screen>
-  </para>
- </refsection>
-</refentry>
diff --git a/nixos/doc/manual/man-nixos-option.xml b/nixos/doc/manual/man-nixos-option.xml
deleted file mode 100644
index b921386d0df01..0000000000000
--- a/nixos/doc/manual/man-nixos-option.xml
+++ /dev/null
@@ -1,134 +0,0 @@
-<refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude">
- <refmeta>
-  <refentrytitle><command>nixos-option</command>
-  </refentrytitle><manvolnum>8</manvolnum>
-  <refmiscinfo class="source">NixOS</refmiscinfo>
-<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
- </refmeta>
- <refnamediv>
-  <refname><command>nixos-option</command></refname>
-  <refpurpose>inspect a NixOS configuration</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
-  <cmdsynopsis>
-   <command>nixos-option</command>
-
-   <arg>
-    <group choice='req'>
-     <arg choice='plain'><option>-r</option></arg>
-     <arg choice='plain'><option>--recursive</option></arg>
-    </group>
-   </arg>
-
-   <arg>
-    <option>-I</option> <replaceable>path</replaceable>
-   </arg>
-
-   <arg>
-    <replaceable>option.name</replaceable>
-   </arg>
-  </cmdsynopsis>
- </refsynopsisdiv>
- <refsection>
-  <title>Description</title>
-  <para>
-   This command evaluates the configuration specified in
-   <filename>/etc/nixos/configuration.nix</filename> and returns the properties
-   of the option name given as argument.
-  </para>
-  <para>
-   When the option name is not an option, the command prints the list of
-   attributes contained in the attribute set.
-  </para>
- </refsection>
- <refsection>
-  <title>Options</title>
-  <para>
-   This command accepts the following options:
-  </para>
-  <variablelist>
-   <varlistentry>
-    <term><option>-r</option></term>
-    <term><option>--recursive</option></term>
-    <listitem>
-     <para>
-      Print all the values at or below the specified path recursively.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <option>-I</option> <replaceable>path</replaceable>
-    </term>
-    <listitem>
-     <para>
-      This option is passed to the underlying
-      <command>nix-instantiate</command> invocation.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
- </refsection>
- <refsection>
-  <title>Environment</title>
-  <variablelist>
-   <varlistentry>
-    <term>
-     <envar>NIXOS_CONFIG</envar>
-    </term>
-    <listitem>
-     <para>
-      Path to the main NixOS configuration module. Defaults to
-      <filename>/etc/nixos/configuration.nix</filename>.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
- </refsection>
- <refsection>
-  <title>Examples</title>
-  <para>
-   Investigate option values:
-<screen><prompt>$ </prompt>nixos-option boot.loader
-This attribute set contains:
-generationsDir
-grub
-initScript
-
-<prompt>$ </prompt>nixos-option boot.loader.grub.enable
-Value:
-true
-
-Default:
-true
-
-Description:
-Whether to enable the GNU GRUB boot loader.
-
-Declared by:
-  "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix"
-
-Defined by:
-  "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix"
-</screen>
-  </para>
- </refsection>
- <refsection>
-  <title>Bugs</title>
-  <para>
-   The author listed in the following section is wrong. If there is any other
-   bug, please report to Nicolas Pierron.
-  </para>
- </refsection>
- <refsection>
-  <title>See also</title>
-  <para>
-   <citerefentry>
-    <refentrytitle>configuration.nix</refentrytitle>
-    <manvolnum>5</manvolnum>
-   </citerefentry>
-  </para>
- </refsection>
-</refentry>
diff --git a/nixos/doc/manual/man-nixos-rebuild.xml b/nixos/doc/manual/man-nixos-rebuild.xml
deleted file mode 100644
index bf0f4aafa1429..0000000000000
--- a/nixos/doc/manual/man-nixos-rebuild.xml
+++ /dev/null
@@ -1,781 +0,0 @@
-<refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude">
- <refmeta>
-  <refentrytitle><command>nixos-rebuild</command>
-  </refentrytitle><manvolnum>8</manvolnum>
-  <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'>
-   <arg choice='plain'>
-    <option>switch</option>
-   </arg>
-
-   <arg choice='plain'>
-    <option>boot</option>
-   </arg>
-
-   <arg choice='plain'>
-    <option>test</option>
-   </arg>
-
-   <arg choice='plain'>
-    <option>build</option>
-   </arg>
-
-   <arg choice='plain'>
-    <option>dry-build</option>
-   </arg>
-
-   <arg choice='plain'>
-    <option>dry-activate</option>
-   </arg>
-
-   <arg choice='plain'>
-    <option>edit</option>
-   </arg>
-
-   <arg choice='plain'>
-    <option>build-vm</option>
-   </arg>
-
-   <arg choice='plain'>
-    <option>build-vm-with-bootloader</option>
-   </arg>
-    </group>
-    <sbr />
-
-    <arg>
-      <group choice='req'>
-        <arg choice='plain'>
-          <option>--upgrade</option>
-        </arg>
-        <arg choice='plain'>
-          <option>--upgrade-all</option>
-        </arg>
-      </group>
-    </arg>
-
-   <arg>
-    <option>--install-bootloader</option>
-   </arg>
-
-   <arg>
-    <option>--no-build-nix</option>
-   </arg>
-
-   <arg>
-    <option>--fast</option>
-   </arg>
-
-   <arg>
-    <option>--rollback</option>
-   </arg>
-
-   <arg>
-    <option>--builders</option> <replaceable>builder-spec</replaceable>
-   </arg>
-
-   <sbr/>
-
-   <arg>
-    <option>--flake</option> <replaceable>flake-uri</replaceable>
-   </arg>
-
-   <arg>
-    <option>--no-flake</option>
-   </arg>
-
-   <arg>
-    <option>--override-input</option> <replaceable>input-name</replaceable> <replaceable>flake-uri</replaceable>
-   </arg>
-
-   <sbr />
-
-   <arg>
-    <group choice='req'>
-    <arg choice='plain'>
-     <option>--profile-name</option>
-    </arg>
-
-    <arg choice='plain'>
-     <option>-p</option>
-    </arg>
-     </group> <replaceable>name</replaceable>
-   </arg>
-
-   <arg>
-    <group choice='req'>
-    <arg choice='plain'>
-     <option>--specialisation</option>
-    </arg>
-
-    <arg choice='plain'>
-     <option>-c</option>
-    </arg>
-     </group> <replaceable>name</replaceable>
-   </arg>
-
-   <sbr />
-
-   <arg>
-    <option>--build-host</option> <replaceable>host</replaceable>
-   </arg>
-
-   <arg>
-    <option>--target-host</option> <replaceable>host</replaceable>
-   </arg>
-
-   <arg>
-    <option>--use-remote-sudo</option>
-   </arg>
-
-   <sbr />
-
-   <arg>
-    <option>--show-trace</option>
-   </arg>
-   <arg>
-    <option>-I</option>
-    <replaceable>NIX_PATH</replaceable>
-   </arg>
-   <arg>
-    <group choice='req'>
-     <arg choice='plain'><option>--verbose</option></arg>
-     <arg choice='plain'><option>-v</option></arg>
-    </group>
-   </arg>
-   <arg>
-    <group choice='req'>
-     <arg choice='plain'><option>--impure</option></arg>
-    </group>
-   </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>
-    <group choice='req'>
-     <arg choice='plain'><option>--keep-failed</option></arg>
-     <arg choice='plain'><option>-K</option></arg>
-    </group>
-   </arg>
-   <arg>
-    <group choice='req'>
-     <arg choice='plain'><option>--keep-going</option></arg>
-     <arg choice='plain'><option>-k</option></arg>
-    </group>
-   </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> or
-   <filename>/etc/nixos/flake.nix</filename>. Thus, every time you
-   modify the configuration or any other NixOS module, you must run
-   <command>nixos-rebuild</command> to make the changes take
-   effect. It builds the new system in
-   <filename>/nix/store</filename>, runs its activation script, and
-   stop and (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>
-      <option>switch</option>
-     </term>
-     <listitem>
-      <para>
-       Build and activate the new configuration, and make it the boot default.
-       That is, the configuration is added to the GRUB boot menu as the default
-       menu entry, so that subsequent reboots will boot the system into the new
-       configuration. Previous configurations activated with
-       <command>nixos-rebuild switch</command> or <command>nixos-rebuild
-       boot</command> remain available in the GRUB menu.
-      </para>
-      <para>
-        Note that if you are using specializations, running just
-        <command>nixos-rebuild switch</command> will switch you back to the
-        unspecialized, base system - in that case, you might want to use this
-        instead:
-<screen>
-<prompt>$ </prompt>nixos-rebuild switch --specialisation your-specialisation-name
-</screen>
-        This command will build all specialisations and make them bootable just
-        like regular <command>nixos-rebuild switch</command> does - the only
-        thing different is that it will switch to given specialisation instead
-        of the base system; it can be also used to switch from the base system
-        into a specialised one, or to switch between specialisations.
-      </para>
-     </listitem>
-    </varlistentry>
-
-    <varlistentry>
-     <term>
-      <option>boot</option>
-     </term>
-     <listitem>
-      <para>
-       Build the new configuration and make it the boot default (as with
-       <command>nixos-rebuild switch</command>), but do not activate it. That
-       is, the system continues to run the previous configuration until the
-       next reboot.
-      </para>
-     </listitem>
-    </varlistentry>
-
-    <varlistentry>
-     <term>
-      <option>test</option>
-     </term>
-     <listitem>
-      <para>
-       Build and activate the new configuration, but do not add it to the GRUB
-       boot menu. Thus, if you reboot the system (or if it crashes), you will
-       automatically revert to the default configuration (i.e. the
-       configuration resulting from the last call to <command>nixos-rebuild
-       switch</command> or <command>nixos-rebuild boot</command>).
-      </para>
-      <para>
-        Note that if you are using specialisations, running just
-        <command>nixos-rebuild test</command> will activate the unspecialised,
-        base system - in that case, you might want to use this instead:
-<screen>
-<prompt>$ </prompt>nixos-rebuild test --specialisation your-specialisation-name
-</screen>
-        This command can be also used to switch from the base system into a
-        specialised one, or to switch between specialisations.
-      </para>
-     </listitem>
-    </varlistentry>
-
-    <varlistentry>
-     <term>
-      <option>build</option>
-     </term>
-     <listitem>
-      <para>
-       Build the new configuration, but neither activate it nor add it to the
-       GRUB boot menu. It leaves a symlink named <filename>result</filename> in
-       the current directory, which points to the output of the top-level
-       “system” derivation. This is essentially the same as doing
-<screen>
-<prompt>$ </prompt>nix-build /path/to/nixpkgs/nixos -A system
-</screen>
-       Note that you do not need to be <literal>root</literal> to run
-       <command>nixos-rebuild build</command>.
-      </para>
-     </listitem>
-    </varlistentry>
-
-    <varlistentry>
-     <term>
-      <option>dry-build</option>
-     </term>
-     <listitem>
-      <para>
-       Show what store paths would be built or downloaded by any of the
-       operations above, but otherwise do nothing.
-      </para>
-     </listitem>
-    </varlistentry>
-
-    <varlistentry>
-     <term>
-      <option>dry-activate</option>
-     </term>
-     <listitem>
-      <para>
-       Build the new configuration, but instead of activating it, show what
-       changes would be performed by the activation (i.e. by
-       <command>nixos-rebuild test</command>). For instance, this command will
-       print which systemd units would be restarted. The list of changes is not
-       guaranteed to be complete.
-      </para>
-     </listitem>
-    </varlistentry>
-
-    <varlistentry>
-     <term>
-      <option>edit</option>
-     </term>
-     <listitem>
-      <para>
-       Opens <filename>configuration.nix</filename> in the default editor.
-      </para>
-     </listitem>
-    </varlistentry>
-
-    <varlistentry>
-     <term>
-      <option>build-vm</option>
-     </term>
-     <listitem>
-      <para>
-       Build a script that starts a NixOS virtual machine with the desired
-       configuration. It leaves a symlink <filename>result</filename> in the
-       current directory that points (under
-       <filename>result/bin/run-<replaceable>hostname</replaceable>-vm</filename>)
-       at the script that starts the VM. Thus, to test a NixOS configuration in
-       a virtual machine, you should do the following:
-<screen>
-<prompt>$ </prompt>nixos-rebuild build-vm
-<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
-       will not work in the VM. This includes commands such as
-       <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
-       across reboots of the VM. It is stored in
-       <literal>./<replaceable>hostname</replaceable>.qcow2</literal>.
-<!-- The entire file system hierarchy of the host is available in
-      the VM under <filename>/hostfs</filename>.-->
-      </para>
-     </listitem>
-    </varlistentry>
-
-    <varlistentry>
-     <term>
-      <option>build-vm-with-bootloader</option>
-     </term>
-     <listitem>
-      <para>
-       Like <option>build-vm</option>, but boots using the regular boot loader
-       of your configuration (e.g., GRUB 1 or 2), rather than booting directly
-       into the kernel and initial ramdisk of the system. This allows you to
-       test whether the boot loader works correctly. However, it does not
-       guarantee that your NixOS configuration will boot successfully on the
-       host hardware (i.e., after running <command>nixos-rebuild
-       switch</command>), because the hardware and boot loader configuration in
-       the VM are different. The boot loader is installed on an automatically
-       generated virtual disk containing a <filename>/boot</filename>
-       partition.
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
- </refsection>
-
- <refsection>
-  <title>Options</title>
-  <para>
-   This command accepts the following options:
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <option>--upgrade</option>
-    </term>
-    <term>
-     <option>--upgrade-all</option>
-    </term>
-    <listitem>
-      <para>
-        Update the root user's channel named <literal>nixos</literal>
-        before rebuilding the system.
-      </para>
-      <para>
-        In addition to the <literal>nixos</literal> channel, the root
-        user's channels which have a file named
-        <literal>.update-on-nixos-rebuild</literal> in their base
-        directory will also be updated.
-      </para>
-      <para>
-        Passing <option>--upgrade-all</option> updates all of the root
-        user's channels.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <option>--install-bootloader</option>
-    </term>
-    <listitem>
-     <para>
-      Causes the boot loader to be (re)installed on the device specified by the
-      relevant configuration options.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <option>--no-build-nix</option>
-    </term>
-    <listitem>
-     <para>
-      Normally, <command>nixos-rebuild</command> first builds the
-      <varname>nixUnstable</varname> attribute in Nixpkgs, and uses the
-      resulting instance of the Nix package manager to build the new system
-      configuration. This is necessary if the NixOS modules use features not
-      provided by the currently installed version of Nix. This option disables
-      building a new Nix.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <option>--fast</option>
-    </term>
-    <listitem>
-     <para>
-      Equivalent to <option>--no-build-nix</option>. This option is
-      useful if you call <command>nixos-rebuild</command> frequently
-      (e.g. if you’re hacking on a NixOS module).
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <option>--rollback</option>
-    </term>
-    <listitem>
-     <para>
-      Instead of building a new configuration as specified by
-      <filename>/etc/nixos/configuration.nix</filename>, roll back to the
-      previous configuration. (The previous configuration is defined as the one
-      before the “current” generation of the Nix profile
-      <filename>/nix/var/nix/profiles/system</filename>.)
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <option>--builders</option> <replaceable>builder-spec</replaceable>
-    </term>
-    <listitem>
-     <para>
-      Allow ad-hoc remote builders for building the new system. This requires
-      the user executing <command>nixos-rebuild</command> (usually root) to be
-      configured as a trusted user in the Nix daemon. This can be achieved by
-      using the <literal>nix.settings.trusted-users</literal> NixOS option. Examples
-      values for that option are described in the <literal>Remote builds
-      chapter</literal> in the Nix manual, (i.e. <command>--builders
-      "ssh://bigbrother x86_64-linux"</command>). By specifying an empty string
-      existing builders specified in <filename>/etc/nix/machines</filename> can
-      be ignored: <command>--builders ""</command> for example when they are
-      not reachable due to network connectivity.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <option>--profile-name</option>
-    </term>
-    <term>
-     <option>-p</option>
-    </term>
-    <listitem>
-     <para>
-      Instead of using the Nix profile
-      <filename>/nix/var/nix/profiles/system</filename> to keep track of the
-      current and previous system configurations, use
-      <filename>/nix/var/nix/profiles/system-profiles/<replaceable>name</replaceable></filename>.
-      When you use GRUB 2, for every system profile created with this flag,
-      NixOS will create a submenu named “NixOS - Profile
-      '<replaceable>name</replaceable>'” in GRUB’s boot menu, containing
-      the current and previous configurations of this profile.
-     </para>
-     <para>
-      For instance, if you want to test a configuration file named
-      <filename>test.nix</filename> without affecting the default system
-      profile, you would do:
-<screen>
-<prompt>$ </prompt>nixos-rebuild switch -p test -I nixos-config=./test.nix
-</screen>
-      The new configuration will appear in the GRUB 2 submenu “NixOS -
-      Profile 'test'”.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <option>--specialisation</option>
-    </term>
-    <term>
-     <option>-c</option>
-    </term>
-    <listitem>
-     <para>
-      Activates given specialisation; when not specified, switching and testing
-      will activate the base, unspecialised system.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <option>--build-host</option>
-    </term>
-    <listitem>
-     <para>
-      Instead of building the new configuration locally, use the specified host
-      to perform the build. The host needs to be accessible with ssh, and must
-      be able to perform Nix builds. If the option
-      <option>--target-host</option> is not set, the build will be copied back
-      to the local machine when done.
-     </para>
-     <para>
-      Note that, if <option>--no-build-nix</option> is not specified, Nix will
-      be built both locally and remotely. This is because the configuration
-      will always be evaluated locally even though the building might be
-      performed remotely.
-     </para>
-     <para>
-      You can include a remote user name in the host name
-      (<replaceable>user@host</replaceable>). You can also set ssh options by
-      defining the <envar>NIX_SSHOPTS</envar> environment variable.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <option>--target-host</option>
-    </term>
-    <listitem>
-     <para>
-      Specifies the NixOS target host. By setting this to something other than
-      an empty string, the system activation will happen
-      on the remote host instead of the local machine. The remote host needs to
-      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 or empty,
-      building will take place locally.
-     </para>
-
-     <para>
-      You can include a remote user name in the host name
-      (<replaceable>user@host</replaceable>). You can also set ssh options by
-      defining the <envar>NIX_SSHOPTS</envar> environment variable.
-     </para>
-
-     <para>
-      Note that <command>nixos-rebuild</command> honors the
-      <literal>nixpkgs.crossSystem</literal> setting of the given configuration
-      but disregards the true architecture of the target host. Hence the
-      <literal>nixpkgs.crossSystem</literal> setting has to match the target
-      platform or else activation will fail.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <option>--use-substitutes</option>
-    </term>
-    <listitem>
-     <para>
-       When set, nixos-rebuild will add <option>--use-substitutes</option>
-       to each invocation of nix-copy-closure. This will only affect the
-       behavior of nixos-rebuild if <option>--target-host</option> or
-       <option>--build-host</option> is also set. This is useful when
-       the target-host connection to cache.nixos.org is faster than the
-       connection between hosts.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <option>--use-remote-sudo</option>
-    </term>
-    <listitem>
-     <para>
-      When set, nixos-rebuild prefixes remote commands that run on
-      the <option>--build-host</option> and <option>--target-host</option>
-      systems with <command>sudo</command>. Setting this option allows
-      deploying as a non-root user.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <option>--flake</option> <replaceable>flake-uri</replaceable><optional>#<replaceable>name</replaceable></optional>
-    </term>
-    <listitem>
-     <para>
-      Build the NixOS system from the specified flake. It defaults to
-      the directory containing the target of the symlink
-      <filename>/etc/nixos/flake.nix</filename>, if it exists. The
-      flake must contain an output named
-      <literal>nixosConfigurations.<replaceable>name</replaceable></literal>. If
-      <replaceable>name</replaceable> is omitted, it default to the
-      current host name.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <option>--no-flake</option>
-    </term>
-    <listitem>
-     <para>
-      Do not imply <option>--flake</option> if
-      <filename>/etc/nixos/flake.nix</filename> exists. With this
-      option, it is possible to build non-flake NixOS configurations
-      even if the current NixOS systems uses flakes.
-     </para>
-    </listitem>
-   </varlistentry>
-
-  </variablelist>
-
-  <para>
-   In addition, <command>nixos-rebuild</command> accepts various Nix-related
-   flags, including <option>--max-jobs</option> / <option>-j</option>, <option>-I</option>,
-   <option>--show-trace</option>, <option>--keep-failed</option>,
-   <option>--keep-going</option>, <option>--impure</option>, and <option>--verbose</option> /
-   <option>-v</option>. See the Nix manual for details.
-  </para>
- </refsection>
-
- <refsection>
-  <title>Environment</title>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <envar>NIXOS_CONFIG</envar>
-    </term>
-    <listitem>
-     <para>
-      Path to the main NixOS configuration module. Defaults to
-      <filename>/etc/nixos/configuration.nix</filename>.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <envar>NIX_PATH</envar>
-    </term>
-    <listitem>
-     <para>
-      A colon-separated list of directories used to look up Nix expressions enclosed in angle brackets (e.g &lt;nixpkgs&gt;). Example
-      <screen>
-          nixpkgs=./my-nixpkgs
-      </screen>
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <envar>NIX_SSHOPTS</envar>
-    </term>
-    <listitem>
-     <para>
-      Additional options to be passed to <command>ssh</command> on the command
-      line.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
- </refsection>
-
- <refsection>
-  <title>Files</title>
-
-  <variablelist>
-
-   <varlistentry>
-    <term>
-     <filename>/etc/nixos/flake.nix</filename>
-    </term>
-    <listitem>
-     <para>
-      If this file exists, then <command>nixos-rebuild</command> will
-      use it as if the <option>--flake</option> option was given. This
-      file may be a symlink to a <filename>flake.nix</filename> in an
-      actual flake; thus <filename>/etc/nixos</filename> need not be a
-      flake.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <filename>/run/current-system</filename>
-    </term>
-    <listitem>
-     <para>
-      A symlink to the currently active system configuration in the Nix store.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <filename>/nix/var/nix/profiles/system</filename>
-    </term>
-    <listitem>
-     <para>
-      The Nix profile that contains the current and previous system
-      configurations. Used to generate the GRUB boot menu.
-     </para>
-    </listitem>
-   </varlistentry>
-
-  </variablelist>
- </refsection>
-
- <refsection>
-  <title>Bugs</title>
-  <para>
-   This command should be renamed to something more descriptive.
-  </para>
- </refsection>
-</refentry>
diff --git a/nixos/doc/manual/man-nixos-version.xml b/nixos/doc/manual/man-nixos-version.xml
deleted file mode 100644
index 507c5035ed8d1..0000000000000
--- a/nixos/doc/manual/man-nixos-version.xml
+++ /dev/null
@@ -1,158 +0,0 @@
-<refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude">
- <refmeta>
-  <refentrytitle><command>nixos-version</command>
-  </refentrytitle><manvolnum>8</manvolnum>
-  <refmiscinfo class="source">NixOS</refmiscinfo>
- </refmeta>
- <refnamediv>
-  <refname><command>nixos-version</command></refname>
-  <refpurpose>show the NixOS version</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
-  <cmdsynopsis>
-   <command>nixos-version</command>
-   <arg>
-    <option>--hash</option>
-   </arg>
-
-   <arg>
-    <option>--revision</option>
-   </arg>
-
-   <arg>
-    <option>--configuration-revision</option>
-   </arg>
-
-   <arg>
-    <option>--json</option>
-   </arg>
-
-  </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsection>
-  <title>Description</title>
-  <para>
-   This command shows the version of the currently active NixOS configuration.
-   For example:
-<screen><prompt>$ </prompt>nixos-version
-16.03.1011.6317da4 (Emu)
-</screen>
-   The version consists of the following elements:
-   <variablelist>
-    <varlistentry>
-     <term>
-      <literal>16.03</literal>
-     </term>
-     <listitem>
-      <para>
-       The NixOS release, indicating the year and month in which it was
-       released (e.g. March 2016).
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>
-      <literal>1011</literal>
-     </term>
-     <listitem>
-      <para>
-       The number of commits in the Nixpkgs Git repository between the start of
-       the release branch and the commit from which this version was built.
-       This ensures that NixOS versions are monotonically increasing. It is
-       <literal>git</literal> when the current NixOS configuration was built
-       from a checkout of the Nixpkgs Git repository rather than from a NixOS
-       channel.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>
-      <literal>6317da4</literal>
-     </term>
-     <listitem>
-      <para>
-       The first 7 characters of the commit in the Nixpkgs Git repository from
-       which this version was built.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>
-      <literal>Emu</literal>
-     </term>
-     <listitem>
-      <para>
-       The code name of the NixOS release. The first letter of the code name
-       indicates that this is the N'th stable NixOS release; for example, Emu
-       is the fifth release.
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
- </refsection>
-
- <refsection>
-  <title>Options</title>
-
-  <para>
-   This command accepts the following options:
-  </para>
-
-  <variablelist>
-
-   <varlistentry>
-    <term>
-     <option>--hash</option>
-    </term>
-    <term>
-     <option>--revision</option>
-    </term>
-    <listitem>
-     <para>
-      Show the full SHA1 hash of the Git commit from which this configuration
-      was built, e.g.
-<screen><prompt>$ </prompt>nixos-version --hash
-6317da40006f6bc2480c6781999c52d88dde2acf
-</screen>
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <option>--configuration-revision</option>
-    </term>
-    <listitem>
-     <para>
-      Show the configuration revision if available. This could be the full SHA1
-      hash of the Git commit of the system flake, if you add
-      <screen>{ system.configurationRevision = self.rev or "dirty"; }</screen>
-      to the <screen>modules</screen> array of your flake.nix system configuration e.g.
-<screen><prompt>$ </prompt>nixos-version --configuration-revision
-aa314ebd1592f6cdd53cb5bba8bcae97d9323de8
-</screen>
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term>
-     <option>--json</option>
-    </term>
-    <listitem>
-     <para>
-      Print a JSON representation of the versions of NixOS and the
-      top-level configuration flake.
-     </para>
-    </listitem>
-   </varlistentry>
-
-  </variablelist>
-
- </refsection>
-
-</refentry>
diff --git a/nixos/doc/manual/man-pages.xml b/nixos/doc/manual/man-pages.xml
index 58f73521e94fd..0186221bddce9 100644
--- a/nixos/doc/manual/man-pages.xml
+++ b/nixos/doc/manual/man-pages.xml
@@ -15,11 +15,4 @@
   </copyright>
  </info>
  <xi:include href="man-configuration.xml" />
- <xi:include href="man-nixos-build-vms.xml" />
- <xi:include href="man-nixos-generate-config.xml" />
- <xi:include href="man-nixos-install.xml" />
- <xi:include href="man-nixos-enter.xml" />
- <xi:include href="man-nixos-option.xml" />
- <xi:include href="man-nixos-rebuild.xml" />
- <xi:include href="man-nixos-version.xml" />
 </reference>
diff --git a/nixos/doc/manual/manpages/README.md b/nixos/doc/manual/manpages/README.md
new file mode 100644
index 0000000000000..ed2682e5332d6
--- /dev/null
+++ b/nixos/doc/manual/manpages/README.md
@@ -0,0 +1,55 @@
+# NixOS manpages
+
+This is the collection of NixOS manpages, excluding `configuration.nix(5)`.
+
+Man pages are written in [`mdoc(7)` format](https://mandoc.bsd.lv/man/mdoc.7.html) and should be portable between mandoc and groff for rendering (though minor differences may occur, mandoc and groff seem to have slightly different spacing rules.)
+
+Being written in `mdoc` these manpages use semantic markup. This file provides a guideline on where to apply which of the semantic elements of `mdoc`.
+
+### Command lines and arguments
+
+In any manpage, commands, flags and arguments to the *current* executable should be marked according to their semantics. Commands, flags and arguments passed to *other* executables should not be marked like this and should instead be considered as code examples and marked with `Ql`.
+
+ - Use `Fl` to mark flag arguments, `Ar` for their arguments.
+ - Repeating arguments should be marked by adding ellipses (`...`).
+ - Use `Cm` to mark literal string arguments, e.g. the `boot` command argument passed to `nixos-rebuild`.
+ - Optional flags or arguments should be marked with `Op`. This includes optional repeating arguments.
+ - Required flags or arguments should not be marked.
+ - Mutually exclusive groups of arguments should be enclosed in curly brackets, preferrably created with `Bro`/`Brc` blocks.
+
+When an argument is used in an example it should be marked up with `Ar` again to differentiate it from a constant. For example, a command with a `--host name` flag that calls ssh to retrieve the host's local time would signify this thusly:
+```
+This will run
+.Ic ssh Ar name Ic time
+to retrieve the remote time.
+```
+
+### Paths, NixOS options, environment variables
+
+Constant paths should be marked with `Pa`, NixOS options with `Va`, and environment variables with `Ev`.
+
+Generated paths, e.g. `result/bin/run-hostname-vm` (where `hostname` is a variable or arguments) should be marked as `Ql` inline literals with their variable components marked appropriately.
+
+ - Taking `hostname` from an argument become `.Ql result/bin/run- Ns Ar hostname Ns -vm`
+ - Taking `hostname` from a variable otherwise defined becomes `.Ql result/bin/run- Ns Va hostname Ns -vm`
+
+### Code examples and other commands
+
+In free text names and complete invocations of other commands (e.g. `ssh` or `tar -xvf src.tar`) should be marked with `Ic`, fragments of command lines should be marked with `Ql`.
+
+Larger code blocks or those that cannot be shown inline should use indented literal display block markup for their contents, i.e.
+```
+.Bd -literal -offset indent
+...
+.Ed
+```
+Contents of code blocks may be marked up further, e.g. if they refer to arguments that will be subsituted into them:
+```
+.Bd -literal -offset indent
+{
+  options.hostname = "\c
+.Ar hostname Ns \c
+";
+}
+.Ed
+```
diff --git a/nixos/doc/manual/manpages/nixos-build-vms.8 b/nixos/doc/manual/manpages/nixos-build-vms.8
new file mode 100644
index 0000000000000..abf06b5dd5962
--- /dev/null
+++ b/nixos/doc/manual/manpages/nixos-build-vms.8
@@ -0,0 +1,109 @@
+.Dd January 1, 1980
+.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from
+.\" doc-default-operating-system. mandoc doesn't have this register set by default,
+.\" so we can use it as a groff/mandoc switch.
+.ie ddoc-default-operating-system .Dt nixos-build-vms \&8 "NixOS System Manager's Manual"
+.el .Dt nixos-build-vms 8
+.Os NixOS
+.Sh NAME
+.Nm nixos-build-vms
+.Nd build a network of virtual machines from a network of NixOS configurations
+.
+.
+.
+.Sh SYNOPSIS
+.Nm nixos-build-vms
+.Op Fl -show-trace
+.Op Fl -no-out-link
+.Op Fl -help
+.Op Fl -option Ar name value
+.Pa network.nix
+.
+.
+.
+.Sh DESCRIPTION
+.
+This command builds a network of QEMU\-KVM virtual machines of a Nix expression
+specifying a network of NixOS machines. The virtual network can be started by
+executing the
+.Pa bin/run-vms
+shell script that is generated by this command. By default, a
+.Pa result
+symlink is produced that points to the generated virtual network.
+.
+.Pp
+A network Nix expression has the following structure:
+.Bd -literal -offset indent
+{
+  test1 = {pkgs, config, ...}:
+    {
+      services.openssh.enable = true;
+      nixpkgs.localSystem.system = "i686-linux";
+      deployment.targetHost = "test1.example.net";
+
+      # Other NixOS options
+    };
+
+  test2 = {pkgs, config, ...}:
+    {
+      services.openssh.enable = true;
+      services.httpd.enable = true;
+      environment.systemPackages = [ pkgs.lynx ];
+      nixpkgs.localSystem.system = "x86_64-linux";
+      deployment.targetHost = "test2.example.net";
+
+      # Other NixOS options
+    };
+}
+.Ed
+.
+.Pp
+Each attribute in the expression represents a machine in the network
+.Ns (e.g.
+.Va test1
+and
+.Va test2 Ns
+) referring to a function defining a NixOS configuration. In each NixOS
+configuration, two attributes have a special meaning. The
+.Va deployment.targetHost
+specifies the address (domain name or IP address) of the system which is used by
+.Ic ssh
+to perform remote deployment operations. The
+.Va nixpkgs.localSystem.system
+attribute can be used to specify an architecture for the target machine, such as
+.Ql i686-linux
+which builds a 32-bit NixOS configuration. Omitting this property will build the
+configuration for the same architecture as the host system.
+.
+.
+.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl -show-trace
+Shows a trace of the output.
+.
+.It Fl -no-out-link
+Do not create a
+.Pa result
+symlink.
+.
+.It Fl h , -help
+Shows the usage of this command to the user.
+.
+.It Fl -option Ar name Va value
+Set the Nix configuration option
+.Va name
+to
+.Va value Ns
+\&. This overrides settings in the Nix configuration file (see
+.Xr nix.conf 5 Ns
+).
+.El
+.
+.
+.
+.Sh AUTHORS
+.An -nosplit
+.An Eelco Dolstra
+and
+.An the Nixpkgs/NixOS contributors
diff --git a/nixos/doc/manual/manpages/nixos-enter.8 b/nixos/doc/manual/manpages/nixos-enter.8
new file mode 100644
index 0000000000000..bc8df31e5f2d8
--- /dev/null
+++ b/nixos/doc/manual/manpages/nixos-enter.8
@@ -0,0 +1,76 @@
+.Dd January 1, 1980
+.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from
+.\" doc-default-operating-system. mandoc doesn't have this register set by default,
+.\" so we can use it as a groff/mandoc switch.
+.ie ddoc-default-operating-system .Dt nixos-enter \&8 "NixOS System Manager's Manual"
+.el .Dt nixos-enter 8
+.Os NixOS
+.Sh NAME
+.Nm nixos-enter
+.Nd run a command in a NixOS chroot environment
+.
+.
+.
+.Sh SYNOPSIS
+.Nm nixos-enter
+.Op Fl -root Ar root
+.Op Fl -system Ar system
+.Op Fl -command | c Ar shell-command
+.Op Fl -silent
+.Op Fl -help
+.Op Fl - Ar arguments ...
+.
+.
+.
+.Sh DESCRIPTION
+This command runs a command in a NixOS chroot environment, that is, in a filesystem hierarchy previously prepared using
+.Xr nixos-install 8 .
+.
+.
+.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl -root Ar root
+The path to the NixOS system you want to enter. It defaults to
+.Pa /mnt Ns
+\&.
+.It Fl -system Ar system
+The NixOS system configuration to use. It defaults to
+.Pa /nix/var/nix/profiles/system Ns
+\&. You can enter a previous NixOS configuration by specifying a path such as
+.Pa /nix/var/nix/profiles/system-106-link Ns
+\&.
+.
+.It Fl -command Ar shell-command , Fl c Ar shell-command
+The bash command to execute.
+.
+.It Fl -silent
+Suppresses all output from the activation script of the target system.
+.
+.It Fl -
+Interpret the remaining arguments as the program name and arguments to be invoked.
+The program is not executed in a shell.
+.El
+.
+.
+.
+.Sh EXAMPLES
+.Bl -tag -width indent
+.It Ic nixos-enter --root /mnt
+Start an interactive shell in the NixOS installation in
+.Pa /mnt Ns .
+.
+.It Ic nixos-enter -c 'ls -l /; cat /proc/mounts'
+Run a shell command.
+.
+.It Ic nixos-enter -- cat /proc/mounts
+Run a non-shell command.
+.El
+.
+.
+.
+.Sh AUTHORS
+.An -nosplit
+.An Eelco Dolstra
+and
+.An the Nixpkgs/NixOS contributors
diff --git a/nixos/doc/manual/manpages/nixos-generate-config.8 b/nixos/doc/manual/manpages/nixos-generate-config.8
new file mode 100644
index 0000000000000..8b9bb4d42483b
--- /dev/null
+++ b/nixos/doc/manual/manpages/nixos-generate-config.8
@@ -0,0 +1,169 @@
+.Dd January 1, 1980
+.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from
+.\" doc-default-operating-system. mandoc doesn't have this register set by default,
+.\" so we can use it as a groff/mandoc switch.
+.ie ddoc-default-operating-system .Dt nixos-generate-config \&8 "NixOS System Manager's Manual"
+.el .Dt nixos-generate-config 8
+.Os NixOS
+.Sh NAME
+.Nm nixos-generate-config
+.Nd generate NixOS configuration modules
+.
+.
+.
+.Sh SYNOPSIS
+.Nm nixos-generate-config
+.Op Fl -force
+.Op Fl -root Ar root
+.Op Fl -dir Ar dir
+.
+.
+.
+.Sh DESCRIPTION
+This command writes two NixOS configuration modules:
+.Bl -tag -width indent
+.It Pa /etc/nixos/hardware-configuration.nix
+This module sets NixOS configuration options based on your current hardware
+configuration. In particular, it sets the
+.Va fileSystem
+option to reflect all currently mounted file systems, the
+.Va swapDevices
+option to reflect active swap devices, and the
+.Va boot.initrd.*
+options to ensure that the initial ramdisk contains any kernel modules necessary
+for mounting the root file system.
+.Pp
+If this file already exists, it is overwritten. Thus, you should not modify it
+manually. Rather, you should include it from your
+.Pa /etc/nixos/configuration.nix Ns
+, and re-run
+.Nm
+to update it whenever your hardware configuration changes.
+.
+.It Pa /etc/nixos/configuration.nix
+This is the main NixOS system configuration module. If it already exists, it’s
+left unchanged. Otherwise,
+.Nm
+will write a template for you to customise.
+.El
+.
+.
+.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl -root Ar root
+If this option is given, treat the directory
+.Ar root
+as the root of the file system. This means that configuration files will be written to
+.Ql Ar root Ns /etc/nixos Ns
+, and that any file systems outside of
+.Ar root
+are ignored for the purpose of generating the
+.Va fileSystems
+option.
+.
+.It Fl -dir Ar dir
+If this option is given, write the configuration files to the directory
+.Ar dir
+instead of
+.Pa /etc/nixos Ns
+\&.
+.
+.It Fl -force
+Overwrite
+.Pa /etc/nixos/configuration.nix
+if it already exists.
+.
+.It Fl -no-filesystems
+Omit everything concerning file systems and swap devices from the hardware configuration.
+.
+.It Fl -show-hardware-config
+Don't generate
+.Pa configuration.nix
+or
+.Pa hardware-configuration.nix
+and print the hardware configuration to stdout only.
+.El
+.
+.
+.
+.Sh EXAMPLES
+This command is typically used during NixOS installation to write initial
+configuration modules. For example, if you created and mounted the target file
+systems on
+.Pa /mnt
+and
+.Pa /mnt/boot Ns
+, you would run:
+.Bd -literal -offset indent
+$ nixos-generate-config --root /mnt
+.Ed
+.
+.Pp
+The resulting file
+.Pa /mnt/etc/nixos/hardware-configuration.nix
+might look like this:
+.Bd -literal -offset indent
+# Do not modify this file!  It was generated by 'nixos-generate-config'
+# and may be overwritten by future invocations.  Please make changes
+# to /etc/nixos/configuration.nix instead.
+{ config, pkgs, ... }:
+
+{
+  imports =
+    [ <nixos/modules/installer/scan/not-detected.nix>
+    ];
+
+  boot.initrd.availableKernelModules = [ "ehci_hcd" "ahci" ];
+  boot.kernelModules = [ "kvm-intel" ];
+  boot.extraModulePackages = [ ];
+
+  fileSystems."/" =
+    { device = "/dev/disk/by-label/nixos";
+      fsType = "ext3";
+      options = [ "rw" "data=ordered" "relatime" ];
+    };
+
+  fileSystems."/boot" =
+    { device = "/dev/sda1";
+      fsType = "ext3";
+      options = [ "rw" "errors=continue" "user_xattr" "acl" "barrier=1" "data=writeback" "relatime" ];
+    };
+
+  swapDevices =
+    [ { device = "/dev/sda2"; }
+    ];
+
+  nix.maxJobs = 8;
+}
+.Ed
+.
+.Pp
+It will also create a basic
+.Pa /mnt/etc/nixos/configuration.nix Ns
+, which you should edit to customise the logical configuration of your system. \
+This file includes the result of the hardware scan as follows:
+.Bd -literal -offset indent
+imports = [ ./hardware-configuration.nix ];
+.Ed
+.
+.Pp
+After installation, if your hardware configuration changes, you can run:
+.Bd -literal -offset indent
+$ nixos-generate-config
+.Ed
+.
+.Pp
+to update
+.Pa /etc/nixos/hardware-configuration.nix Ns
+\&. Your
+.Pa /etc/nixos/configuration.nix
+will
+.Em not
+be overwritten.
+.
+.Sh AUTHORS
+.An -nosplit
+.An Eelco Dolstra
+and
+.An the Nixpkgs/NixOS contributors
diff --git a/nixos/doc/manual/manpages/nixos-install.8 b/nixos/doc/manual/manpages/nixos-install.8
new file mode 100644
index 0000000000000..dc0a5da275d88
--- /dev/null
+++ b/nixos/doc/manual/manpages/nixos-install.8
@@ -0,0 +1,195 @@
+.Dd January 1, 1980
+.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from
+.\" doc-default-operating-system. mandoc doesn't have this register set by default,
+.\" so we can use it as a groff/mandoc switch.
+.ie ddoc-default-operating-system .Dt nixos-install \&8 "NixOS System Manager's Manual"
+.el .Dt nixos-install 8
+.Os NixOS
+.Sh NAME
+.Nm nixos-install
+.Nd install bootloader and NixOS
+.
+.
+.
+.Sh SYNOPSIS
+.Nm nixos-install
+.Op Fl -verbose | v
+.Op Fl I Ar path
+.Op Fl -root Ar root
+.Op Fl -system Ar path
+.Op Fl -flake Ar flake-uri
+.Op Fl -impure
+.Op Fl -channel Ar channel
+.Op Fl -no-channel-copy
+.Op Fl -no-root-password | -no-root-passwd
+.Op Fl -no-bootloader
+.Op Fl -max-jobs | j Ar number
+.Op Fl -cores Ar number
+.Op Fl -option Ar name value
+.Op Fl -show-trace
+.Op Fl -keep-going
+.Op Fl -help
+.
+.
+.
+.Sh DESCRIPTION
+This command installs NixOS in the file system mounted on
+.Pa /mnt Ns
+, based on the NixOS configuration specified in
+.Pa /mnt/etc/nixos/configuration.nix Ns
+\&. It performs the following steps:
+.
+.Bl -enum
+.It
+It copies Nix and its dependencies to
+.Pa /mnt/nix/store Ns
+\&.
+.
+.It
+It runs Nix in
+.Pa /mnt
+to build the NixOS configuration specified in
+.Pa /mnt/etc/nixos/configuration.nix Ns
+\&.
+.
+.It
+It installs the current channel
+.Dq nixos
+in the target channel profile (unless
+.Fl -no-channel-copy
+is specified).
+.
+.It
+It installs the GRUB boot loader on the device specified in the option
+.Va boot.loader.grub.device
+(unless
+.Fl -no-bootloader
+is specified), and generates a GRUB configuration file that boots into the NixOS
+configuration just installed.
+.
+.It
+It prompts you for a password for the root account (unless
+.Fl -no-root-password
+is specified).
+.El
+.
+.Pp
+This command is idempotent: if it is interrupted or fails due to a temporary
+problem (e.g. a network issue), you can safely re-run it.
+.
+.
+.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl -verbose , v
+Increases the level of verbosity of diagnostic messages printed on standard
+error. For each Nix operation, the information printed on standard output is
+well-defined; any diagnostic information is printed on standard error, never on
+standard output.
+.Pp
+Please note that this option may be specified repeatedly.
+.
+.It Fl -root Ar root
+Defaults to
+.Pa /mnt Ns
+\&. If this option is given, treat the directory
+.Ar root
+as the root of the NixOS installation.
+.
+.It Fl -system Ar path
+If this option is provided,
+.Nm
+will install the specified closure rather than attempt to build one from
+.Pa /mnt/etc/nixos/configuration.nix Ns
+\&.
+.Pp
+The closure must be an appropriately configured NixOS system, with boot loader
+and partition configuration that fits the target host. Such a closure is
+typically obtained with a command such as
+.Ic nix-build -I nixos-config=./configuration.nix '<nixpkgs/nixos>' -A system --no-out-link Ns
+\&.
+.
+.It Fl -flake Ar flake-uri Ns # Ns Ar name
+Build the NixOS system from the specified flake. The flake must contain an
+output named
+.Ql nixosConfigurations. Ns Ar name Ns
+\&.
+.
+.It Fl -channel Ar channel
+If this option is provided, do not copy the current
+.Dq nixos
+channel to the target host. Instead, use the specified derivation.
+.
+.It Fl I Ar Path
+Add a path to the Nix expression search path. This option may be given multiple
+times. See the
+.Ev NIX_PATH
+environment variable for information on the semantics of the Nix search path. Paths added through
+.Fl I
+take precedence over
+.Ev NIX_PATH Ns
+\&.
+.
+.It Fl -max-jobs , j Ar number
+Sets the maximum number of build jobs that Nix will perform in parallel to the
+specified number. The default is 1. A higher value is useful on SMP systems or
+to exploit I/O latency.
+.
+.It Fl -cores Ar N
+Sets the value of the
+.Ev NIX_BUILD_CORES
+environment variable in the invocation of builders. Builders can use this
+variable at their discretion to control the maximum amount of parallelism. For
+instance, in Nixpkgs, if the derivation attribute
+.Va enableParallelBuilding
+is set to true, the builder passes the
+.Fl j Ns Va N
+flag to GNU Make. The value 0 means that the builder should use all available CPU cores in the system.
+.
+.It Fl -option Ar name value
+Set the Nix configuration option
+.Ar name
+to
+.Ar value Ns
+\&.
+.
+.It Fl -show-trace
+Causes Nix to print out a stack trace in case of Nix expression evaluation errors.
+.
+.It Fl -keep-going
+Causes Nix to continue building derivations as far as possible in the face of failed builds.
+.
+.It Fl -help
+Synonym for
+.Ic man nixos-install Ns
+\&.
+.El
+.
+.
+.
+.Sh EXAMPLES
+A typical NixOS installation is done by creating and mounting a file system on
+.Pa /mnt Ns
+, generating a NixOS configuration in
+.Pa /mnt/etc/nixos/configuration.nix Ns
+, and running
+.Nm Ns
+\&. For instance, if we want to install NixOS on an ext4 file system created in
+.Pa /dev/sda1 Ns
+:
+.Bd -literal -offset indent
+$ mkfs.ext4 /dev/sda1
+$ mount /dev/sda1 /mnt
+$ nixos-generate-config --root /mnt
+$ # edit /mnt/etc/nixos/configuration.nix
+$ nixos-install
+$ reboot
+.Ed
+.
+.
+.
+.Sh AUTHORS
+.An -nosplit
+.An Eelco Dolstra
+and
+.An the Nixpkgs/NixOS contributors
diff --git a/nixos/doc/manual/manpages/nixos-option.8 b/nixos/doc/manual/manpages/nixos-option.8
new file mode 100644
index 0000000000000..79cc113cfaf2d
--- /dev/null
+++ b/nixos/doc/manual/manpages/nixos-option.8
@@ -0,0 +1,93 @@
+.Dd January 1, 1980
+.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from
+.\" doc-default-operating-system. mandoc doesn't have this register set by default,
+.\" so we can use it as a groff/mandoc switch.
+.ie ddoc-default-operating-system .Dt nixos-option \&8 "NixOS System Manager's Manual"
+.el .Dt nixos-option 8
+.Os NixOS
+.Sh NAME
+.Nm nixos-option
+.Nd inspect a NixOS configuration
+.
+.
+.
+.Sh SYNOPSIS
+.Nm
+.Op Fl r | -recursive
+.Op Fl I Ar path
+.Ar option.name
+.
+.
+.
+.Sh DESCRIPTION
+This command evaluates the configuration specified in
+.Pa /etc/nixos/configuration.nix
+and returns the properties of the option name given as argument.
+.
+.Pp
+When the option name is not an option, the command prints the list of attributes
+contained in the attribute set.
+.
+.
+.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl r , -recursive
+Print all the values at or below the specified path recursively.
+.
+.It Fl I Ar path
+This option is passed to the underlying
+.Xr nix-instantiate 1
+invocation.
+.El
+.
+.
+.
+.Sh ENVIRONMENT
+.Bl -tag -width indent
+.It Ev NIXOS_CONFIG
+Path to the main NixOS configuration module. Defaults to
+.Pa /etc/nixos/configuration.nix Ns
+\&.
+.El
+.
+.
+.
+.Sh EXAMPLES
+Investigate option values:
+.Bd -literal -offset indent
+$ nixos-option boot.loader
+This attribute set contains:
+generationsDir
+grub
+initScript
+
+$ nixos-option boot.loader.grub.enable
+Value:
+true
+
+Default:
+true
+
+Description:
+Whether to enable the GNU GRUB boot loader.
+
+Declared by:
+  "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix"
+
+Defined by:
+  "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix"
+.Ed
+.
+.
+.
+.Sh SEE ALSO
+.Xr configuration.nix 5
+.
+.
+.
+.Sh AUTHORS
+.An -nosplit
+.An Nicolas Pierron
+and
+.An the Nixpkgs/NixOS contributors
diff --git a/nixos/doc/manual/manpages/nixos-rebuild.8 b/nixos/doc/manual/manpages/nixos-rebuild.8
new file mode 100644
index 0000000000000..8ff59d6da9cfb
--- /dev/null
+++ b/nixos/doc/manual/manpages/nixos-rebuild.8
@@ -0,0 +1,456 @@
+.Dd January 1, 1980
+.\" nixpkgs groff will use Nixpkgs the OS in the title by default, taking it from
+.\" doc-default-operating-system. mandoc doesn't have this register set by default,
+.\" so we can use it as a groff/mandoc switch.
+.ie ddoc-default-operating-system .Dt nixos-rebuild \&8 "NixOS System Manager's Manual"
+.el .Dt nixos-rebuild 8
+.Os NixOS
+.Sh NAME
+.Nm nixos-rebuild
+.Nd reconfigure a NixOS machine
+.
+.
+.
+.Sh SYNOPSIS
+.Nm
+.Bro
+.Cm switch | boot | test | build | dry-build | dry-activate | edit | build-vm | build-vm-with-bootloader
+.Brc
+.br
+.Op Fl -upgrade | -upgrade-all
+.Op Fl -install-bootloader
+.Op Fl -no-build-nix
+.Op Fl -fast
+.Op Fl -rollback
+.Op Fl -builders Ar builder-spec
+.br
+.Op Fl -flake Ar flake-uri
+.Op Fl -no-flake
+.Op Fl -override-input Ar input-name flake-uri
+.br
+.Op Fl -profile-name | p Ar name
+.Op Fl -specialisation | c Ar name
+.br
+.Op Fl -build-host Va host
+.Op Fl -target-host Va host
+.Op Fl -use-remote-sudo
+.br
+.Op Fl -show-trace
+.Op Fl I Va NIX_PATH
+.Op Fl -verbose | v
+.Op Fl -impure
+.Op Fl -max-jobs | j Va number
+.Op Fl -keep-failed | K
+.Op Fl -keep-going | k
+.
+.
+.
+.Sh DESCRIPTION
+This command updates the system so that it corresponds to the
+configuration specified in
+.Pa /etc/nixos/configuration.nix
+or
+.Pa /etc/nixos/flake.nix Ns
+\&. Thus, every time you modify the configuration or any other NixOS module, you
+must run
+.Nm
+to make the changes take effect. It builds the new system in
+.Pa /nix/store Ns
+, runs its activation script, and stop and (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.
+.
+.Pp
+This command has one required argument, which specifies the desired
+operation. It must be one of the following:
+.Bl -tag -width indent
+.It Cm switch
+Build and activate the new configuration, and make it the boot default. That
+is, the configuration is added to the GRUB boot menu as the default
+menu entry, so that subsequent reboots will boot the system into the new
+configuration. Previous configurations activated with
+.Ic nixos-rebuild switch
+or
+.Ic nixos-rebuild boot
+remain available in the GRUB menu.
+.Pp
+Note that if you are using specializations, running just
+.Ic nixos-rebuild switch
+will switch you back to the unspecialized, base system \(em in that case, you
+might want to use this instead:
+.Bd -literal -offset indent
+$ nixos-rebuild switch --specialisation your-specialisation-name
+.Ed
+.Pp
+This command will build all specialisations and make them bootable just
+like regular
+.Ic nixos-rebuild switch
+does \(em the only thing different is that it will switch to given
+specialisation instead of the base system; it can be also used to switch from
+the base system into a specialised one, or to switch between specialisations.
+.
+.It Cm boot
+Build the new configuration and make it the boot default (as with
+.Ic nixos-rebuild switch Ns
+), but do not activate it. That is, the system continues to run the previous
+configuration until the next reboot.
+.
+.It Cm test
+Build and activate the new configuration, but do not add it to the GRUB
+boot menu. Thus, if you reboot the system (or if it crashes), you will
+automatically revert to the default configuration (i.e. the
+configuration resulting from the last call to
+.Ic nixos-rebuild switch
+or
+.Ic nixos-rebuild boot Ns
+).
+.Pp
+Note that if you are using specialisations, running just
+.Ic nixos-rebuild test
+will activate the unspecialised, base system \(em in that case, you might want
+to use this instead:
+.Bd -literal -offset indent
+$ nixos-rebuild test --specialisation your-specialisation-name
+.Ed
+.Pp
+This command can be also used to switch from the base system into a
+specialised one, or to switch between specialisations.
+.
+.It Cm build
+Build the new configuration, but neither activate it nor add it to the
+GRUB boot menu. It leaves a symlink named
+.Pa result
+in the current directory, which points to the output of the top-level
+.Dq system
+derivation. This is essentially the same as doing
+.Bd -literal -offset indent
+$ nix-build /path/to/nixpkgs/nixos -A system
+.Ed
+.Pp
+Note that you do not need to be root to run
+.Ic nixos-rebuild build Ns
+\&.
+.
+.It Cm dry-build
+Show what store paths would be built or downloaded by any of the
+operations above, but otherwise do nothing.
+.
+.It Cm dry-activate
+Build the new configuration, but instead of activating it, show what
+changes would be performed by the activation (i.e. by
+.Ic nixos-rebuild test Ns
+). For instance, this command will print which systemd units would be restarted.
+The list of changes is not guaranteed to be complete.
+.
+.It Cm edit
+Opens
+.Pa configuration.nix
+in the default editor.
+.
+.It Cm build-vm
+Build a script that starts a NixOS virtual machine with the desired
+configuration. It leaves a symlink
+.Pa result
+in the current directory that points (under
+.Ql result/bin/run\- Ns Va hostname Ns \-vm Ns
+)
+at the script that starts the VM. Thus, to test a NixOS configuration in
+a virtual machine, you should do the following:
+.Bd -literal -offset indent
+$ nixos-rebuild build-vm
+$ ./result/bin/run-*-vm
+.Ed
+.Pp
+The VM is implemented using the
+.Ql qemu
+package. For best performance, you should load the
+.Ql kvm-intel
+or
+.Ql kvm-amd
+kernel modules to get hardware virtualisation.
+.Pp
+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
+will not work in the VM. This includes commands such as
+.Nm Ns
+; to change the VM’s configuration, you must halt the VM and re-run the commands
+above.
+.Pp
+The VM has its own ext3 root file system, which is automatically created when
+the VM is first started, and is persistent across reboots of the VM. It is
+stored in
+.Ql ./ Ns Va hostname Ns .qcow2 Ns
+\&.
+.\" The entire file system hierarchy of the host is available in
+.\" the VM under
+.\" .Pa /hostfs Ns
+.\" .
+.
+.It Cm build-vm-with-bootloader
+Like
+.Cm build-vm Ns
+, but boots using the regular boot loader of your configuration (e.g. GRUB 1 or
+2), rather than booting directly into the kernel and initial ramdisk of the
+system. This allows you to test whether the boot loader works correctly. \
+However, it does not guarantee that your NixOS configuration will boot
+successfully on the host hardware (i.e., after running
+.Ic nixos-rebuild switch Ns
+), because the hardware and boot loader configuration in the VM are different.
+The boot loader is installed on an automatically generated virtual disk
+containing a
+.Pa /boot
+partition.
+.El
+.
+.
+.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl -upgrade , -upgrade-all
+Update the root user's channel named
+.Ql nixos
+before rebuilding the system.
+.Pp
+In addition to the
+.Ql nixos
+channel, the root user's channels which have a file named
+.Ql .update-on-nixos-rebuild
+in their base directory will also be updated.
+.Pp
+Passing
+.Fl -upgrade-all
+updates all of the root user's channels.
+.
+.It Fl -install-bootloader
+Causes the boot loader to be (re)installed on the device specified by the
+relevant configuration options.
+.
+.It Fl -no-build-nix
+Normally,
+.Nm
+first builds the
+.Ql nixUnstable
+attribute in Nixpkgs, and uses the resulting instance of the Nix package manager
+to build the new system configuration. This is necessary if the NixOS modules
+use features not provided by the currently installed version of Nix. This option
+disables building a new Nix.
+.
+.It Fl -fast
+Equivalent to
+.Fl -no-build-nix Ns
+\&. This option is useful if you call
+.Nm
+frequently (e.g. if you’re hacking on a NixOS module).
+.
+.It Fl -rollback
+Instead of building a new configuration as specified by
+.Pa /etc/nixos/configuration.nix Ns
+, roll back to the previous configuration. (The previous configuration is
+defined as the one before the “current” generation of the Nix profile
+.Pa /nix/var/nix/profiles/system Ns
+\&.)
+.
+.It Fl -builders Ar builder-spec
+Allow ad-hoc remote builders for building the new system. This requires
+the user executing
+.Nm
+(usually root) to be configured as a trusted user in the Nix daemon. This can be
+achieved by using the
+.Va nix.settings.trusted-users
+NixOS option. Examples values for that option are described in the
+.Dq Remote builds
+chapter in the Nix manual, (i.e.
+.Ql --builders \(dqssh://bigbrother x86_64-linux\(dq Ns
+). By specifying an empty string existing builders specified in
+.Pa /etc/nix/machines
+can be ignored:
+.Ql --builders \(dq\(dq
+for example when they are not reachable due to network connectivity.
+.
+.It Fl -profile-name Ar name , Fl p Ar name
+Instead of using the Nix profile
+.Pa /nix/var/nix/profiles/system
+to keep track of the current and previous system configurations, use
+.Pa /nix/var/nix/profiles/system-profiles/ Ns Va name Ns
+\&. When you use GRUB 2, for every system profile created with this flag, NixOS
+will create a submenu named
+.Dq NixOS - Profile Va name
+in GRUB’s boot menu, containing the current and previous configurations of this profile.
+.Pp
+For instance, if you want to test a configuration file named
+.Pa test.nix
+without affecting the default system profile, you would do:
+.Bd -literal -offset indent
+$ nixos-rebuild switch -p test -I nixos-config=./test.nix
+.Ed
+.Pp
+The new configuration will appear in the GRUB 2 submenu
+.Dq NixOS - Profile 'test' Ns
+\&.
+.
+.It Fl -specialisation Ar name , Fl c Ar name
+Activates given specialisation; when not specified, switching and testing
+will activate the base, unspecialised system.
+.
+.It Fl -build-host Ar host
+Instead of building the new configuration locally, use the specified host
+to perform the build. The host needs to be accessible with
+.Ic ssh Ns ,
+and must be able to perform Nix builds. If the option
+.Fl -target-host
+is not set, the build will be copied back to the local machine when done.
+.Pp
+Note that, if
+.Fl -no-build-nix
+is not specified, Nix will be built both locally and remotely. This is because
+the configuration will always be evaluated locally even though the building
+might be performed remotely.
+.Pp
+You can include a remote user name in the host name
+.Ns ( Va user@host Ns
+). You can also set ssh options by defining the
+.Ev NIX_SSHOPTS
+environment variable.
+.
+.It Fl -target-host Ar host
+Specifies the NixOS target host. By setting this to something other than an
+empty string, the system activation will happen on the remote host instead of
+the local machine. The remote host needs to be accessible over
+.Ic ssh Ns ,
+and for the commands
+.Cm switch Ns
+,
+.Cm boot
+and
+.Cm test
+you need root access.
+.Pp
+If
+.Fl -build-host
+is not explicitly specified or empty, building will take place locally.
+.Pp
+You can include a remote user name in the host name
+.Ns ( Va user@host Ns
+). You can also set ssh options by defining the
+.Ev NIX_SSHOPTS
+environment variable.
+.Pp
+Note that
+.Nm
+honors the
+.Va nixpkgs.crossSystem
+setting of the given configuration but disregards the true architecture of the
+target host. Hence the
+.Va nixpkgs.crossSystem
+setting has to match the target platform or else activation will fail.
+.
+.It Fl -use-substitutes
+When set, nixos-rebuild will add
+.Fl -use-substitutes
+to each invocation of nix-copy-closure. This will only affect the behavior of
+nixos-rebuild if
+.Fl -target-host
+or
+.Fl -build-host
+is also set. This is useful when the target-host connection to cache.nixos.org
+is faster than the connection between hosts.
+.
+.It Fl -use-remote-sudo
+When set, nixos-rebuild prefixes remote commands that run on the
+.Fl -build-host
+and
+.Fl -target-host
+systems with
+.Ic sudo Ns
+\&. Setting this option allows deploying as a non-root user.
+.
+.It Fl -flake Va flake-uri Ns Op Va #name
+Build the NixOS system from the specified flake. It defaults to the directory
+containing the target of the symlink
+.Pa /etc/nixos/flake.nix Ns
+, if it exists. The flake must contain an output named
+.Ql nixosConfigurations. Ns Va name Ns
+\&. If
+.Va name
+is omitted, it default to the current host name.
+.
+.It Fl -no-flake
+Do not imply
+.Fl -flake
+if
+.Pa /etc/nixos/flake.nix
+exists. With this option, it is possible to build non-flake NixOS configurations
+even if the current NixOS systems uses flakes.
+.El
+.Pp
+In addition,
+.Nm
+accepts various Nix-related flags, including
+.Fl -max-jobs Ns ,
+.Fl j Ns ,
+.Fl I Ns ,
+.Fl -show-trace Ns ,
+.Fl -keep-failed Ns ,
+.Fl -keep-going Ns ,
+.Fl -impure Ns ,
+.Fl -verbose Ns , and
+.Fl v Ns
+\&. See the Nix manual for details.
+.
+.
+.
+.Sh ENVIRONMENT
+.Bl -tag -width indent
+.It Ev NIXOS_CONFIG
+Path to the main NixOS configuration module. Defaults to
+.Pa /etc/nixos/configuration.nix Ns
+\&.
+.
+.It Ev NIX_PATH
+A colon-separated list of directories used to look up Nix expressions enclosed
+in angle brackets (e.g. <nixpkgs>). Example:
+.Bd -literal -offset indent
+nixpkgs=./my-nixpkgs
+.Ed
+.
+.It Ev NIX_SSHOPTS
+Additional options to be passed to
+.Ic ssh
+on the command line.
+.El
+.
+.
+.
+.Sh FILES
+.Bl -tag -width indent
+.It Pa /etc/nixos/flake.nix
+If this file exists, then
+.Nm
+will use it as if the
+.Fl -flake
+option was given. This file may be a symlink to a
+.Pa flake.nix
+in an actual flake; thus
+.Pa /etc/nixos
+need not be a flake.
+.
+.It Pa /run/current-system
+A symlink to the currently active system configuration in the Nix store.
+.
+.It Pa /nix/var/nix/profiles/system
+The Nix profile that contains the current and previous system
+configurations. Used to generate the GRUB boot menu.
+.El
+.
+.
+.
+.Sh BUGS
+This command should be renamed to something more descriptive.
+.
+.
+.
+.Sh AUTHORS
+.An -nosplit
+.An Eelco Dolstra
+and
+.An the Nixpkgs/NixOS contributors
diff --git a/nixos/doc/manual/manpages/nixos-version.8 b/nixos/doc/manual/manpages/nixos-version.8
new file mode 100644
index 0000000000000..980ee8b1f49e9
--- /dev/null
+++ b/nixos/doc/manual/manpages/nixos-version.8
@@ -0,0 +1,90 @@
+.Dd January 1, 1980
+.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from
+.\" doc-default-operating-system. mandoc doesn't have this register set by default,
+.\" so we can use it as a groff/mandoc switch.
+.ie ddoc-default-operating-system .Dt nixos-version \&8 "NixOS System Manager's Manual"
+.el .Dt nixos-version 8
+.Os NixOS
+.Sh NAME
+.Nm nixos-version
+.Nd show the NixOS version
+.
+.
+.
+.Sh SYNOPSIS
+.Nm nixos-version
+.Op Fl -hash
+.Op Fl -revision
+.Op Fl -configuration-revision
+.Op Fl -json
+.
+.
+.
+.Sh DESCRIPTION
+This command shows the version of the currently active NixOS configuration. For example:
+.Bd -literal -offset indent
+$ nixos-version
+16.03.1011.6317da4 (Emu)
+.Ed
+.
+.Pp
+The version consists of the following elements:
+.Bl -tag -width indent
+.It Ql 16.03
+The NixOS release, indicating the year and month in which it was released
+(e.g. March 2016).
+.It Ql 1011
+The number of commits in the Nixpkgs Git repository between the start of the
+release branch and the commit from which this version was built. This ensures
+that NixOS versions are monotonically increasing. It is
+.Ql git
+when the current NixOS configuration was built from a checkout of the Nixpkgs
+Git repository rather than from a NixOS channel.
+.It Ql 6317da4
+The first 7 characters of the commit in the Nixpkgs Git repository from which
+this version was built.
+.It Ql Emu
+The code name of the NixOS release. The first letter of the code name indicates
+that this is the N'th stable NixOS release; for example, Emu is the fifth
+release.
+.El
+.
+.
+.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl -hash , -revision
+Show the full SHA1 hash of the Git commit from which this configuration was
+built, e.g.
+.Bd -literal -offset indent
+$ nixos-version --hash
+6317da40006f6bc2480c6781999c52d88dde2acf
+.Ed
+.
+.It Fl -configuration-revision
+Show the configuration revision if available. This could be the full SHA1 hash
+of the Git commit of the system flake, if you add
+.Bd -literal -offset indent
+{ system.configurationRevision = self.rev or "dirty"; }
+.Ed
+.Pp
+to the
+.Ql modules
+array of your flake.nix system configuration e.g.
+.Bd -literal -offset indent
+$ nixos-version --configuration-revision
+aa314ebd1592f6cdd53cb5bba8bcae97d9323de8
+.Ed
+.
+.It Fl -json
+Print a JSON representation of the versions of NixOS and the top-level
+configuration flake.
+.El
+.
+.
+.
+.Sh AUTHORS
+.An -nosplit
+.An Eelco Dolstra
+and
+.An the Nixpkgs/NixOS contributors