nixos/doc: convert boot problems section to CommonMark

4 files changed, 163 insertions, 127 deletions

diff --git a/nixos/doc/manual/administration/boot-problems.section.md b/nixos/doc/manual/administration/boot-problems.section.md
new file mode 100644
index 00000000000..eb9209602a3
--- /dev/null
+++ b/nixos/doc/manual/administration/boot-problems.section.md
@@ -0,0 +1,35 @@
+# Boot Problems {#sec-boot-problems}
+
+If NixOS fails to boot, there are a number of kernel command line parameters that may help you to identify or fix the issue. You can add these parameters in the GRUB boot menu by pressing “e” to modify the selected boot entry and editing the line starting with `linux`. The following are some useful kernel command line parameters that are recognised by the NixOS boot scripts or by systemd:
+
+`boot.shell_on_fail`
+
+: Allows the user to start a root shell if something goes wrong in stage 1 of the boot process (the initial ramdisk). This is disabled by default because there is no authentication for the root shell.
+
+`boot.debug1`
+
+: Start an interactive shell in stage 1 before anything useful has been done. That is, no modules have been loaded and no file systems have been mounted, except for `/proc` and `/sys`.
+
+`boot.debug1devices`
+
+: Like `boot.debug1`, but runs stage1 until kernel modules are loaded and device nodes are created. This may help with e.g. making the keyboard work.
+
+`boot.debug1mounts`
+
+: Like `boot.debug1` or `boot.debug1devices`, but runs stage1 until all filesystems that are mounted during initrd are mounted (see [neededForBoot](#opt-fileSystems._name_.neededForBoot)). As a motivating example, this could be useful if you've forgotten to set [neededForBoot](options.html#opt-fileSystems._name_.neededForBoot) on a file system.
+
+`boot.trace`
+
+: Print every shell command executed by the stage 1 and 2 boot scripts.
+
+`single`
+
+: Boot into rescue mode (a.k.a. single user mode). This will cause systemd to start nothing but the unit `rescue.target`, which runs `sulogin` to prompt for the root password and start a root login shell. Exiting the shell causes the system to continue with the normal boot process.
+
+`systemd.log_level=debug` `systemd.log_target=console`
+
+: Make systemd very verbose and send log messages to the console instead of the journal. For more parameters recognised by systemd, see systemd(1).
+
+Notice that for `boot.shell_on_fail`, `boot.debug1`, `boot.debug1devices`, and `boot.debug1mounts`, if you did **not** select "start the new shell as pid 1", and you `exit` from the new shell, boot will proceed normally from the point where it failed, as if you'd chosen "ignore the error and continue".
+
+If no login prompts or X11 login screens appear (e.g. due to hanging dependencies), you can press Alt+ArrowUp. If you’re lucky, this will start rescue mode (described above). (Also note that since most units have a 90-second timeout before systemd gives up on them, the `agetty` login prompts should appear eventually unless something is very wrong.)
diff --git a/nixos/doc/manual/administration/boot-problems.xml b/nixos/doc/manual/administration/boot-problems.xml
deleted file mode 100644
index e0f66284010..00000000000
--- a/nixos/doc/manual/administration/boot-problems.xml
+++ /dev/null
@@ -1,126 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-        xmlns:xlink="http://www.w3.org/1999/xlink"
-        xmlns:xi="http://www.w3.org/2001/XInclude"
-        version="5.0"
-        xml:id="sec-boot-problems">
- <title>Boot Problems</title>
-
- <para>
-  If NixOS fails to boot, there are a number of kernel command line parameters
-  that may help you to identify or fix the issue. You can add these parameters
-  in the GRUB boot menu by pressing “e” to modify the selected boot entry
-  and editing the line starting with <literal>linux</literal>. The following
-  are some useful kernel command line parameters that are recognised by the
-  NixOS boot scripts or by systemd:
-  <variablelist>
-   <varlistentry>
-    <term>
-     <literal>boot.shell_on_fail</literal>
-    </term>
-    <listitem>
-     <para>
-      Allows the user to start a root shell if something goes wrong in stage 1
-      of the boot process (the initial ramdisk). This is disabled by default
-      because there is no authentication for the root shell.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <literal>boot.debug1</literal>
-    </term>
-    <listitem>
-     <para>
-      Start an interactive shell in stage 1 before anything useful has been
-      done. That is, no modules have been loaded and no file systems have been
-      mounted, except for <filename>/proc</filename> and
-      <filename>/sys</filename>.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <literal>boot.debug1devices</literal>
-    </term>
-    <listitem>
-     <para>
-      Like <literal>boot.debug1</literal>, but runs stage1 until kernel modules are loaded and device nodes are created.
-      This may help with e.g. making the keyboard work.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <literal>boot.debug1mounts</literal>
-    </term>
-    <listitem>
-     <para>
-      Like <literal>boot.debug1</literal> or
-      <literal>boot.debug1devices</literal>, but runs stage1 until all
-      filesystems that are mounted during initrd are mounted (see
-      <option><link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link></option>
-      ). As a motivating example, this could be useful if you've forgotten to set
-      <option><link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link></option>
-      on a file system.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <literal>boot.trace</literal>
-    </term>
-    <listitem>
-     <para>
-      Print every shell command executed by the stage 1 and 2 boot scripts.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <literal>single</literal>
-    </term>
-    <listitem>
-     <para>
-      Boot into rescue mode (a.k.a. single user mode). This will cause systemd
-      to start nothing but the unit <literal>rescue.target</literal>, which
-      runs <command>sulogin</command> to prompt for the root password and start
-      a root login shell. Exiting the shell causes the system to continue with
-      the normal boot process.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <literal>systemd.log_level=debug systemd.log_target=console</literal>
-    </term>
-    <listitem>
-     <para>
-      Make systemd very verbose and send log messages to the console instead of
-      the journal.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-  For more parameters recognised by systemd, see <citerefentry>
-  <refentrytitle>systemd</refentrytitle>
-  <manvolnum>1</manvolnum></citerefentry>.
- </para>
-
- <para>
-  Notice that for <literal>boot.shell_on_fail</literal>,
-  <literal>boot.debug1</literal>, <literal>boot.debug1devices</literal>, and
-  <literal>boot.debug1mounts</literal>, if you did <emphasis>not</emphasis>
-  select "start the new shell as pid 1", and you <literal>exit</literal> from
-  the new shell, boot will proceed normally from the point where it failed, as
-  if you'd chosen "ignore the error and continue".
- </para>
-
- <para>
-  If no login prompts or X11 login screens appear (e.g. due to hanging
-  dependencies), you can press Alt+ArrowUp. If you’re lucky, this will start
-  rescue mode (described above). (Also note that since most units have a
-  90-second timeout before systemd gives up on them, the
-  <command>agetty</command> login prompts should appear eventually unless
-  something is very wrong.)
- </para>
-</section>
diff --git a/nixos/doc/manual/administration/troubleshooting.xml b/nixos/doc/manual/administration/troubleshooting.xml
index 6496e7bde38..b055acadacf 100644
--- a/nixos/doc/manual/administration/troubleshooting.xml
+++ b/nixos/doc/manual/administration/troubleshooting.xml
@@ -8,7 +8,7 @@
   This chapter describes solutions to common problems you might encounter when
   you manage your NixOS system.
  </para>
- <xi:include href="boot-problems.xml" />
+ <xi:include href="../from_md/administration/boot-problems.section.xml" />
  <xi:include href="maintenance-mode.xml" />
  <xi:include href="rollback.xml" />
  <xi:include href="store-corruption.xml" />
diff --git a/nixos/doc/manual/from_md/administration/boot-problems.section.xml b/nixos/doc/manual/from_md/administration/boot-problems.section.xml
new file mode 100644
index 00000000000..89871e7aeb6
--- /dev/null
+++ b/nixos/doc/manual/from_md/administration/boot-problems.section.xml
@@ -0,0 +1,127 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-boot-problems">
+  <title>Boot Problems</title>
+  <para>
+    If NixOS fails to boot, there are a number of kernel command line
+    parameters that may help you to identify or fix the issue. You can
+    add these parameters in the GRUB boot menu by pressing
+    <quote>e</quote> to modify the selected boot entry and editing the
+    line starting with <literal>linux</literal>. The following are some
+    useful kernel command line parameters that are recognised by the
+    NixOS boot scripts or by systemd:
+  </para>
+  <variablelist>
+    <varlistentry>
+      <term>
+        <literal>boot.shell_on_fail</literal>
+      </term>
+      <listitem>
+        <para>
+          Allows the user to start a root shell if something goes wrong
+          in stage 1 of the boot process (the initial ramdisk). This is
+          disabled by default because there is no authentication for the
+          root shell.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>boot.debug1</literal>
+      </term>
+      <listitem>
+        <para>
+          Start an interactive shell in stage 1 before anything useful
+          has been done. That is, no modules have been loaded and no
+          file systems have been mounted, except for
+          <literal>/proc</literal> and <literal>/sys</literal>.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>boot.debug1devices</literal>
+      </term>
+      <listitem>
+        <para>
+          Like <literal>boot.debug1</literal>, but runs stage1 until
+          kernel modules are loaded and device nodes are created. This
+          may help with e.g. making the keyboard work.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>boot.debug1mounts</literal>
+      </term>
+      <listitem>
+        <para>
+          Like <literal>boot.debug1</literal> or
+          <literal>boot.debug1devices</literal>, but runs stage1 until
+          all filesystems that are mounted during initrd are mounted
+          (see
+          <link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link>).
+          As a motivating example, this could be useful if you’ve
+          forgotten to set
+          <link xlink:href="options.html#opt-fileSystems._name_.neededForBoot">neededForBoot</link>
+          on a file system.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>boot.trace</literal>
+      </term>
+      <listitem>
+        <para>
+          Print every shell command executed by the stage 1 and 2 boot
+          scripts.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>single</literal>
+      </term>
+      <listitem>
+        <para>
+          Boot into rescue mode (a.k.a. single user mode). This will
+          cause systemd to start nothing but the unit
+          <literal>rescue.target</literal>, which runs
+          <literal>sulogin</literal> to prompt for the root password and
+          start a root login shell. Exiting the shell causes the system
+          to continue with the normal boot process.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>systemd.log_level=debug</literal>
+        <literal>systemd.log_target=console</literal>
+      </term>
+      <listitem>
+        <para>
+          Make systemd very verbose and send log messages to the console
+          instead of the journal. For more parameters recognised by
+          systemd, see systemd(1).
+        </para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+  <para>
+    Notice that for <literal>boot.shell_on_fail</literal>,
+    <literal>boot.debug1</literal>,
+    <literal>boot.debug1devices</literal>, and
+    <literal>boot.debug1mounts</literal>, if you did
+    <emphasis role="strong">not</emphasis> select <quote>start the new
+    shell as pid 1</quote>, and you <literal>exit</literal> from the new
+    shell, boot will proceed normally from the point where it failed, as
+    if you’d chosen <quote>ignore the error and continue</quote>.
+  </para>
+  <para>
+    If no login prompts or X11 login screens appear (e.g. due to hanging
+    dependencies), you can press Alt+ArrowUp. If you’re lucky, this will
+    start rescue mode (described above). (Also note that since most
+    units have a 90-second timeout before systemd gives up on them, the
+    <literal>agetty</literal> login prompts should appear eventually
+    unless something is very wrong.)
+  </para>
+</section>