nixos: nixos/doc/manual/administration/cleaning-store.xml to CommonMark

4 files changed, 134 insertions, 64 deletions

diff --git a/nixos/doc/manual/administration/cleaning-store.chapter.md b/nixos/doc/manual/administration/cleaning-store.chapter.md
new file mode 100644
index 0000000000000..fb2090b31d84a
--- /dev/null
+++ b/nixos/doc/manual/administration/cleaning-store.chapter.md
@@ -0,0 +1,62 @@
+# Cleaning the Nix Store {#sec-nix-gc}
+
+Nix has a purely functional model, meaning that packages are never
+upgraded in place. Instead new versions of packages end up in a
+different location in the Nix store (`/nix/store`). You should
+periodically run Nix's *garbage collector* to remove old, unreferenced
+packages. This is easy:
+
+```ShellSession
+$ nix-collect-garbage
+```
+
+Alternatively, you can use a systemd unit that does the same in the
+background:
+
+```ShellSession
+# systemctl start nix-gc.service
+```
+
+You can tell NixOS in `configuration.nix` to run this unit automatically
+at certain points in time, for instance, every night at 03:15:
+
+```nix
+nix.gc.automatic = true;
+nix.gc.dates = "03:15";
+```
+
+The commands above do not remove garbage collector roots, such as old
+system configurations. Thus they do not remove the ability to roll back
+to previous configurations. The following command deletes old roots,
+removing the ability to roll back to them:
+
+```ShellSession
+$ nix-collect-garbage -d
+```
+
+You can also do this for specific profiles, e.g.
+
+```ShellSession
+$ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old
+```
+
+Note that NixOS system configurations are stored in the profile
+`/nix/var/nix/profiles/system`.
+
+Another way to reclaim disk space (often as much as 40% of the size of
+the Nix store) is to run Nix's store optimiser, which seeks out
+identical files in the store and replaces them with hard links to a
+single copy.
+
+```ShellSession
+$ nix-store --optimise
+```
+
+Since this command needs to read the entire Nix store, it can take quite
+a while to finish.
+
+## NixOS Boot Entries {#sect-nixos-gc-boot-entries}
+
+If your `/boot` partition runs out of space, after clearing old profiles
+you must rebuild your system with `nixos-rebuild` to update the `/boot`
+partition and clear space.
diff --git a/nixos/doc/manual/administration/cleaning-store.xml b/nixos/doc/manual/administration/cleaning-store.xml
deleted file mode 100644
index 526803e429baf..0000000000000
--- a/nixos/doc/manual/administration/cleaning-store.xml
+++ /dev/null
@@ -1,63 +0,0 @@
-<chapter 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-gc">
- <title>Cleaning the Nix Store</title>
- <para>
-  Nix has a purely functional model, meaning that packages are never upgraded
-  in place. Instead new versions of packages end up in a different location in
-  the Nix store (<filename>/nix/store</filename>). You should periodically run
-  Nix’s <emphasis>garbage collector</emphasis> to remove old, unreferenced
-  packages. This is easy:
-<screen>
-<prompt>$ </prompt>nix-collect-garbage
-</screen>
-  Alternatively, you can use a systemd unit that does the same in the
-  background:
-<screen>
-<prompt># </prompt>systemctl start nix-gc.service
-</screen>
-  You can tell NixOS in <filename>configuration.nix</filename> to run this unit
-  automatically at certain points in time, for instance, every night at 03:15:
-<programlisting>
-<xref linkend="opt-nix.gc.automatic"/> = true;
-<xref linkend="opt-nix.gc.dates"/> = "03:15";
-</programlisting>
- </para>
- <para>
-  The commands above do not remove garbage collector roots, such as old system
-  configurations. Thus they do not remove the ability to roll back to previous
-  configurations. The following command deletes old roots, removing the ability
-  to roll back to them:
-<screen>
-<prompt>$ </prompt>nix-collect-garbage -d
-</screen>
-  You can also do this for specific profiles, e.g.
-<screen>
-<prompt>$ </prompt>nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old
-</screen>
-  Note that NixOS system configurations are stored in the profile
-  <filename>/nix/var/nix/profiles/system</filename>.
- </para>
- <para>
-  Another way to reclaim disk space (often as much as 40% of the size of the
-  Nix store) is to run Nix’s store optimiser, which seeks out identical files
-  in the store and replaces them with hard links to a single copy.
-<screen>
-<prompt>$ </prompt>nix-store --optimise
-</screen>
-  Since this command needs to read the entire Nix store, it can take quite a
-  while to finish.
- </para>
- <section xml:id="sect-nixos-gc-boot-entries">
-  <title>NixOS Boot Entries</title>
-
-  <para>
-   If your <filename>/boot</filename> partition runs out of space, after
-   clearing old profiles you must rebuild your system with
-   <literal>nixos-rebuild</literal> to update the <filename>/boot</filename>
-   partition and clear space.
-  </para>
- </section>
-</chapter>
diff --git a/nixos/doc/manual/administration/running.xml b/nixos/doc/manual/administration/running.xml
index aeccc843792b4..24fd864956ffa 100644
--- a/nixos/doc/manual/administration/running.xml
+++ b/nixos/doc/manual/administration/running.xml
@@ -15,7 +15,7 @@
  <xi:include href="../from_md/administration/user-sessions.chapter.xml" />
  <xi:include href="../from_md/administration/control-groups.chapter.xml" />
  <xi:include href="../from_md/administration/logging.chapter.xml" />
- <xi:include href="cleaning-store.xml" />
+ <xi:include href="../from_md/administration/cleaning-store.chapter.xml" />
  <xi:include href="containers.xml" />
  <xi:include href="troubleshooting.xml" />
 </part>
diff --git a/nixos/doc/manual/from_md/administration/cleaning-store.chapter.xml b/nixos/doc/manual/from_md/administration/cleaning-store.chapter.xml
new file mode 100644
index 0000000000000..0ca98dd6e5101
--- /dev/null
+++ b/nixos/doc/manual/from_md/administration/cleaning-store.chapter.xml
@@ -0,0 +1,71 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-nix-gc">
+  <title>Cleaning the Nix Store</title>
+  <para>
+    Nix has a purely functional model, meaning that packages are never
+    upgraded in place. Instead new versions of packages end up in a
+    different location in the Nix store (<literal>/nix/store</literal>).
+    You should periodically run Nix’s <emphasis>garbage
+    collector</emphasis> to remove old, unreferenced packages. This is
+    easy:
+  </para>
+  <programlisting>
+$ nix-collect-garbage
+</programlisting>
+  <para>
+    Alternatively, you can use a systemd unit that does the same in the
+    background:
+  </para>
+  <programlisting>
+# systemctl start nix-gc.service
+</programlisting>
+  <para>
+    You can tell NixOS in <literal>configuration.nix</literal> to run
+    this unit automatically at certain points in time, for instance,
+    every night at 03:15:
+  </para>
+  <programlisting language="bash">
+nix.gc.automatic = true;
+nix.gc.dates = &quot;03:15&quot;;
+</programlisting>
+  <para>
+    The commands above do not remove garbage collector roots, such as
+    old system configurations. Thus they do not remove the ability to
+    roll back to previous configurations. The following command deletes
+    old roots, removing the ability to roll back to them:
+  </para>
+  <programlisting>
+$ nix-collect-garbage -d
+</programlisting>
+  <para>
+    You can also do this for specific profiles, e.g.
+  </para>
+  <programlisting>
+$ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old
+</programlisting>
+  <para>
+    Note that NixOS system configurations are stored in the profile
+    <literal>/nix/var/nix/profiles/system</literal>.
+  </para>
+  <para>
+    Another way to reclaim disk space (often as much as 40% of the size
+    of the Nix store) is to run Nix’s store optimiser, which seeks out
+    identical files in the store and replaces them with hard links to a
+    single copy.
+  </para>
+  <programlisting>
+$ nix-store --optimise
+</programlisting>
+  <para>
+    Since this command needs to read the entire Nix store, it can take
+    quite a while to finish.
+  </para>
+  <section xml:id="sect-nixos-gc-boot-entries">
+    <title>NixOS Boot Entries</title>
+    <para>
+      If your <literal>/boot</literal> partition runs out of space,
+      after clearing old profiles you must rebuild your system with
+      <literal>nixos-rebuild</literal> to update the
+      <literal>/boot</literal> partition and clear space.
+    </para>
+  </section>
+</chapter>