Merge pull request #128935 from bobby285271/pr7

nixos/doc: convert "Chapter 56. Troubleshooting" to CommonMark

13 files changed, 217 insertions, 124 deletions

diff --git a/nixos/doc/manual/administration/maintenance-mode.section.md b/nixos/doc/manual/administration/maintenance-mode.section.md
new file mode 100644
index 000000000000..0aec013c0a9b
--- /dev/null
+++ b/nixos/doc/manual/administration/maintenance-mode.section.md
@@ -0,0 +1,11 @@
+# Maintenance Mode {#sec-maintenance-mode}
+
+You can enter rescue mode by running:
+
+```ShellSession
+# systemctl rescue
+```
+
+This will eventually give you a single-user root shell. Systemd will
+stop (almost) all system services. To get out of maintenance mode, just
+exit from the rescue shell.
diff --git a/nixos/doc/manual/administration/maintenance-mode.xml b/nixos/doc/manual/administration/maintenance-mode.xml
deleted file mode 100644
index 74abfdd7c663..000000000000
--- a/nixos/doc/manual/administration/maintenance-mode.xml
+++ /dev/null
@@ -1,16 +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-maintenance-mode">
- <title>Maintenance Mode</title>
-
- <para>
-  You can enter rescue mode by running:
-<screen>
-<prompt># </prompt>systemctl rescue</screen>
-  This will eventually give you a single-user root shell. Systemd will stop
-  (almost) all system services. To get out of maintenance mode, just exit from
-  the rescue shell.
- </para>
-</section>
diff --git a/nixos/doc/manual/administration/network-problems.section.md b/nixos/doc/manual/administration/network-problems.section.md
new file mode 100644
index 000000000000..d360120d72d0
--- /dev/null
+++ b/nixos/doc/manual/administration/network-problems.section.md
@@ -0,0 +1,21 @@
+# Network Problems {#sec-nix-network-issues}
+
+Nix uses a so-called *binary cache* to optimise building a package from
+source into downloading it as a pre-built binary. That is, whenever a
+command like `nixos-rebuild` needs a path in the Nix store, Nix will try
+to download that path from the Internet rather than build it from
+source. The default binary cache is `https://cache.nixos.org/`. If this
+cache is unreachable, Nix operations may take a long time due to HTTP
+connection timeouts. You can disable the use of the binary cache by
+adding `--option use-binary-caches false`, e.g.
+
+```ShellSession
+# nixos-rebuild switch --option use-binary-caches false
+```
+
+If you have an alternative binary cache at your disposal, you can use it
+instead:
+
+```ShellSession
+# nixos-rebuild switch --option binary-caches http://my-cache.example.org/
+```
diff --git a/nixos/doc/manual/administration/network-problems.xml b/nixos/doc/manual/administration/network-problems.xml
deleted file mode 100644
index 1035e4e056a9..000000000000
--- a/nixos/doc/manual/administration/network-problems.xml
+++ /dev/null
@@ -1,27 +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-nix-network-issues">
- <title>Network Problems</title>
-
- <para>
-  Nix uses a so-called <emphasis>binary cache</emphasis> to optimise building a
-  package from source into downloading it as a pre-built binary. That is,
-  whenever a command like <command>nixos-rebuild</command> needs a path in the
-  Nix store, Nix will try to download that path from the Internet rather than
-  build it from source. The default binary cache is
-  <uri>https://cache.nixos.org/</uri>. If this cache is unreachable, Nix
-  operations may take a long time due to HTTP connection timeouts. You can
-  disable the use of the binary cache by adding <option>--option
-  use-binary-caches false</option>, e.g.
-<screen>
-<prompt># </prompt>nixos-rebuild switch --option use-binary-caches false
-</screen>
-  If you have an alternative binary cache at your disposal, you can use it
-  instead:
-<screen>
-<prompt># </prompt>nixos-rebuild switch --option binary-caches <replaceable>http://my-cache.example.org/</replaceable>
-</screen>
- </para>
-</section>
diff --git a/nixos/doc/manual/administration/rollback.section.md b/nixos/doc/manual/administration/rollback.section.md
new file mode 100644
index 000000000000..290d685a2a18
--- /dev/null
+++ b/nixos/doc/manual/administration/rollback.section.md
@@ -0,0 +1,38 @@
+# Rolling Back Configuration Changes {#sec-rollback}
+
+After running `nixos-rebuild` to switch to a new configuration, you may
+find that the new configuration doesn't work very well. In that case,
+there are several ways to return to a previous configuration.
+
+First, the GRUB boot manager allows you to boot into any previous
+configuration that hasn't been garbage-collected. These configurations
+can be found under the GRUB submenu "NixOS - All configurations". This
+is especially useful if the new configuration fails to boot. After the
+system has booted, you can make the selected configuration the default
+for subsequent boots:
+
+```ShellSession
+# /run/current-system/bin/switch-to-configuration boot
+```
+
+Second, you can switch to the previous configuration in a running
+system:
+
+```ShellSession
+# nixos-rebuild switch --rollback
+```
+
+This is equivalent to running:
+
+```ShellSession
+# /nix/var/nix/profiles/system-N-link/bin/switch-to-configuration switch
+```
+
+where `N` is the number of the NixOS system configuration. To get a
+list of the available configurations, do:
+
+```ShellSession
+$ ls -l /nix/var/nix/profiles/system-*-link
+...
+lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055
+```
diff --git a/nixos/doc/manual/administration/rollback.xml b/nixos/doc/manual/administration/rollback.xml
deleted file mode 100644
index 80d79e1a53f1..000000000000
--- a/nixos/doc/manual/administration/rollback.xml
+++ /dev/null
@@ -1,41 +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-rollback">
- <title>Rolling Back Configuration Changes</title>
-
- <para>
-  After running <command>nixos-rebuild</command> to switch to a new
-  configuration, you may find that the new configuration doesn’t work very
-  well. In that case, there are several ways to return to a previous
-  configuration.
- </para>
-
- <para>
-  First, the GRUB boot manager allows you to boot into any previous
-  configuration that hasn’t been garbage-collected. These configurations can
-  be found under the GRUB submenu “NixOS - All configurations”. This is
-  especially useful if the new configuration fails to boot. After the system
-  has booted, you can make the selected configuration the default for
-  subsequent boots:
-<screen>
-<prompt># </prompt>/run/current-system/bin/switch-to-configuration boot</screen>
- </para>
-
- <para>
-  Second, you can switch to the previous configuration in a running system:
-<screen>
-<prompt># </prompt>nixos-rebuild switch --rollback</screen>
-  This is equivalent to running:
-<screen>
-<prompt># </prompt>/nix/var/nix/profiles/system-<replaceable>N</replaceable>-link/bin/switch-to-configuration switch</screen>
-  where <replaceable>N</replaceable> is the number of the NixOS system
-  configuration. To get a list of the available configurations, do:
-<screen>
-<prompt>$ </prompt>ls -l /nix/var/nix/profiles/system-*-link
-<replaceable>...</replaceable>
-lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055
-</screen>
- </para>
-</section>
diff --git a/nixos/doc/manual/administration/store-corruption.section.md b/nixos/doc/manual/administration/store-corruption.section.md
new file mode 100644
index 000000000000..bd8a5772b37c
--- /dev/null
+++ b/nixos/doc/manual/administration/store-corruption.section.md
@@ -0,0 +1,28 @@
+# Nix Store Corruption {#sec-nix-store-corruption}
+
+After a system crash, it's possible for files in the Nix store to become
+corrupted. (For instance, the Ext4 file system has the tendency to
+replace un-synced files with zero bytes.) NixOS tries hard to prevent
+this from happening: it performs a `sync` before switching to a new
+configuration, and Nix's database is fully transactional. If corruption
+still occurs, you may be able to fix it automatically.
+
+If the corruption is in a path in the closure of the NixOS system
+configuration, you can fix it by doing
+
+```ShellSession
+# nixos-rebuild switch --repair
+```
+
+This will cause Nix to check every path in the closure, and if its
+cryptographic hash differs from the hash recorded in Nix's database, the
+path is rebuilt or redownloaded.
+
+You can also scan the entire Nix store for corrupt paths:
+
+```ShellSession
+# nix-store --verify --check-contents --repair
+```
+
+Any corrupt paths will be redownloaded if they're available in a binary
+cache; otherwise, they cannot be repaired.
diff --git a/nixos/doc/manual/administration/store-corruption.xml b/nixos/doc/manual/administration/store-corruption.xml
deleted file mode 100644
index b9d11152d5e1..000000000000
--- a/nixos/doc/manual/administration/store-corruption.xml
+++ /dev/null
@@ -1,36 +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-nix-store-corruption">
- <title>Nix Store Corruption</title>
-
- <para>
-  After a system crash, it’s possible for files in the Nix store to become
-  corrupted. (For instance, the Ext4 file system has the tendency to replace
-  un-synced files with zero bytes.) NixOS tries hard to prevent this from
-  happening: it performs a <command>sync</command> before switching to a new
-  configuration, and Nix’s database is fully transactional. If corruption
-  still occurs, you may be able to fix it automatically.
- </para>
-
- <para>
-  If the corruption is in a path in the closure of the NixOS system
-  configuration, you can fix it by doing
-<screen>
-<prompt># </prompt>nixos-rebuild switch --repair
-</screen>
-  This will cause Nix to check every path in the closure, and if its
-  cryptographic hash differs from the hash recorded in Nix’s database, the
-  path is rebuilt or redownloaded.
- </para>
-
- <para>
-  You can also scan the entire Nix store for corrupt paths:
-<screen>
-<prompt># </prompt>nix-store --verify --check-contents --repair
-</screen>
-  Any corrupt paths will be redownloaded if they’re available in a binary
-  cache; otherwise, they cannot be repaired.
- </para>
-</section>
diff --git a/nixos/doc/manual/administration/troubleshooting.xml b/nixos/doc/manual/administration/troubleshooting.xml
index b055acadacf3..d447b537335b 100644
--- a/nixos/doc/manual/administration/troubleshooting.xml
+++ b/nixos/doc/manual/administration/troubleshooting.xml
@@ -9,8 +9,8 @@
   you manage your NixOS system.
  </para>
  <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" />
- <xi:include href="network-problems.xml" />
+ <xi:include href="../from_md/administration/maintenance-mode.section.xml" />
+ <xi:include href="../from_md/administration/rollback.section.xml" />
+ <xi:include href="../from_md/administration/store-corruption.section.xml" />
+ <xi:include href="../from_md/administration/network-problems.section.xml" />
 </chapter>
diff --git a/nixos/doc/manual/from_md/administration/maintenance-mode.section.xml b/nixos/doc/manual/from_md/administration/maintenance-mode.section.xml
new file mode 100644
index 000000000000..c86b1911c117
--- /dev/null
+++ b/nixos/doc/manual/from_md/administration/maintenance-mode.section.xml
@@ -0,0 +1,14 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-maintenance-mode">
+  <title>Maintenance Mode</title>
+  <para>
+    You can enter rescue mode by running:
+  </para>
+  <programlisting>
+# systemctl rescue
+</programlisting>
+  <para>
+    This will eventually give you a single-user root shell. Systemd will
+    stop (almost) all system services. To get out of maintenance mode,
+    just exit from the rescue shell.
+  </para>
+</section>
diff --git a/nixos/doc/manual/from_md/administration/network-problems.section.xml b/nixos/doc/manual/from_md/administration/network-problems.section.xml
new file mode 100644
index 000000000000..4c0598ca94e8
--- /dev/null
+++ b/nixos/doc/manual/from_md/administration/network-problems.section.xml
@@ -0,0 +1,25 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-nix-network-issues">
+  <title>Network Problems</title>
+  <para>
+    Nix uses a so-called <emphasis>binary cache</emphasis> to optimise
+    building a package from source into downloading it as a pre-built
+    binary. That is, whenever a command like
+    <literal>nixos-rebuild</literal> needs a path in the Nix store, Nix
+    will try to download that path from the Internet rather than build
+    it from source. The default binary cache is
+    <literal>https://cache.nixos.org/</literal>. If this cache is
+    unreachable, Nix operations may take a long time due to HTTP
+    connection timeouts. You can disable the use of the binary cache by
+    adding <literal>--option use-binary-caches false</literal>, e.g.
+  </para>
+  <programlisting>
+# nixos-rebuild switch --option use-binary-caches false
+</programlisting>
+  <para>
+    If you have an alternative binary cache at your disposal, you can
+    use it instead:
+  </para>
+  <programlisting>
+# nixos-rebuild switch --option binary-caches http://my-cache.example.org/
+</programlisting>
+</section>
diff --git a/nixos/doc/manual/from_md/administration/rollback.section.xml b/nixos/doc/manual/from_md/administration/rollback.section.xml
new file mode 100644
index 000000000000..a8df053011c5
--- /dev/null
+++ b/nixos/doc/manual/from_md/administration/rollback.section.xml
@@ -0,0 +1,42 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-rollback">
+  <title>Rolling Back Configuration Changes</title>
+  <para>
+    After running <literal>nixos-rebuild</literal> to switch to a new
+    configuration, you may find that the new configuration doesn’t work
+    very well. In that case, there are several ways to return to a
+    previous configuration.
+  </para>
+  <para>
+    First, the GRUB boot manager allows you to boot into any previous
+    configuration that hasn’t been garbage-collected. These
+    configurations can be found under the GRUB submenu <quote>NixOS -
+    All configurations</quote>. This is especially useful if the new
+    configuration fails to boot. After the system has booted, you can
+    make the selected configuration the default for subsequent boots:
+  </para>
+  <programlisting>
+# /run/current-system/bin/switch-to-configuration boot
+</programlisting>
+  <para>
+    Second, you can switch to the previous configuration in a running
+    system:
+  </para>
+  <programlisting>
+# nixos-rebuild switch --rollback
+</programlisting>
+  <para>
+    This is equivalent to running:
+  </para>
+  <programlisting>
+# /nix/var/nix/profiles/system-N-link/bin/switch-to-configuration switch
+</programlisting>
+  <para>
+    where <literal>N</literal> is the number of the NixOS system
+    configuration. To get a list of the available configurations, do:
+  </para>
+  <programlisting>
+$ ls -l /nix/var/nix/profiles/system-*-link
+...
+lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -&gt; /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055
+</programlisting>
+</section>
diff --git a/nixos/doc/manual/from_md/administration/store-corruption.section.xml b/nixos/doc/manual/from_md/administration/store-corruption.section.xml
new file mode 100644
index 000000000000..9ed572d484dc
--- /dev/null
+++ b/nixos/doc/manual/from_md/administration/store-corruption.section.xml
@@ -0,0 +1,34 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-nix-store-corruption">
+  <title>Nix Store Corruption</title>
+  <para>
+    After a system crash, it’s possible for files in the Nix store to
+    become corrupted. (For instance, the Ext4 file system has the
+    tendency to replace un-synced files with zero bytes.) NixOS tries
+    hard to prevent this from happening: it performs a
+    <literal>sync</literal> before switching to a new configuration, and
+    Nix’s database is fully transactional. If corruption still occurs,
+    you may be able to fix it automatically.
+  </para>
+  <para>
+    If the corruption is in a path in the closure of the NixOS system
+    configuration, you can fix it by doing
+  </para>
+  <programlisting>
+# nixos-rebuild switch --repair
+</programlisting>
+  <para>
+    This will cause Nix to check every path in the closure, and if its
+    cryptographic hash differs from the hash recorded in Nix’s database,
+    the path is rebuilt or redownloaded.
+  </para>
+  <para>
+    You can also scan the entire Nix store for corrupt paths:
+  </para>
+  <programlisting>
+# nix-store --verify --check-contents --repair
+</programlisting>
+  <para>
+    Any corrupt paths will be redownloaded if they’re available in a
+    binary cache; otherwise, they cannot be repaired.
+  </para>
+</section>