Merge pull request #128934 from bobby285271/pr6

nixos/doc: convert "6.2. Ad-Hoc Package Management" to CommonMark

4 files changed, 111 insertions, 62 deletions

diff --git a/nixos/doc/manual/configuration/ad-hoc-packages.section.md b/nixos/doc/manual/configuration/ad-hoc-packages.section.md
new file mode 100644
index 00000000000..e9d574903a1
--- /dev/null
+++ b/nixos/doc/manual/configuration/ad-hoc-packages.section.md
@@ -0,0 +1,51 @@
+# Ad-Hoc Package Management {#sec-ad-hoc-packages}
+
+With the command `nix-env`, you can install and uninstall packages from
+the command line. For instance, to install Mozilla Thunderbird:
+
+```ShellSession
+$ nix-env -iA nixos.thunderbird
+```
+
+If you invoke this as root, the package is installed in the Nix profile
+`/nix/var/nix/profiles/default` and visible to all users of the system;
+otherwise, the package ends up in
+`/nix/var/nix/profiles/per-user/username/profile` and is not visible to
+other users. The `-A` flag specifies the package by its attribute name;
+without it, the package is installed by matching against its package
+name (e.g. `thunderbird`). The latter is slower because it requires
+matching against all available Nix packages, and is ambiguous if there
+are multiple matching packages.
+
+Packages come from the NixOS channel. You typically upgrade a package by
+updating to the latest version of the NixOS channel:
+
+```ShellSession
+$ nix-channel --update nixos
+```
+
+and then running `nix-env -i` again. Other packages in the profile are
+*not* affected; this is the crucial difference with the declarative
+style of package management, where running `nixos-rebuild switch` causes
+all packages to be updated to their current versions in the NixOS
+channel. You can however upgrade all packages for which there is a newer
+version by doing:
+
+```ShellSession
+$ nix-env -u '*'
+```
+
+A package can be uninstalled using the `-e` flag:
+
+```ShellSession
+$ nix-env -e thunderbird
+```
+
+Finally, you can roll back an undesirable `nix-env` action:
+
+```ShellSession
+$ nix-env --rollback
+```
+
+`nix-env` has many more flags. For details, see the nix-env(1) manpage or
+the Nix manual.
diff --git a/nixos/doc/manual/configuration/ad-hoc-packages.xml b/nixos/doc/manual/configuration/ad-hoc-packages.xml
deleted file mode 100644
index c7e882d846f..00000000000
--- a/nixos/doc/manual/configuration/ad-hoc-packages.xml
+++ /dev/null
@@ -1,61 +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-ad-hoc-packages">
- <title>Ad-Hoc Package Management</title>
-
- <para>
-  With the command <command>nix-env</command>, you can install and uninstall
-  packages from the command line. For instance, to install Mozilla Thunderbird:
-<screen>
-<prompt>$ </prompt>nix-env -iA nixos.thunderbird</screen>
-  If you invoke this as root, the package is installed in the Nix profile
-  <filename>/nix/var/nix/profiles/default</filename> and visible to all users
-  of the system; otherwise, the package ends up in
-  <filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/profile</filename>
-  and is not visible to other users. The <option>-A</option> flag specifies the
-  package by its attribute name; without it, the package is installed by
-  matching against its package name (e.g. <literal>thunderbird</literal>). The
-  latter is slower because it requires matching against all available Nix
-  packages, and is ambiguous if there are multiple matching packages.
- </para>
-
- <para>
-  Packages come from the NixOS channel. You typically upgrade a package by
-  updating to the latest version of the NixOS channel:
-<screen>
-<prompt>$ </prompt>nix-channel --update nixos
-</screen>
-  and then running <literal>nix-env -i</literal> again. Other packages in the
-  profile are <emphasis>not</emphasis> affected; this is the crucial difference
-  with the declarative style of package management, where running
-  <command>nixos-rebuild switch</command> causes all packages to be updated to
-  their current versions in the NixOS channel. You can however upgrade all
-  packages for which there is a newer version by doing:
-<screen>
-<prompt>$ </prompt>nix-env -u '*'
-</screen>
- </para>
-
- <para>
-  A package can be uninstalled using the <option>-e</option> flag:
-<screen>
-<prompt>$ </prompt>nix-env -e thunderbird
-</screen>
- </para>
-
- <para>
-  Finally, you can roll back an undesirable <command>nix-env</command> action:
-<screen>
-<prompt>$ </prompt>nix-env --rollback
-</screen>
- </para>
-
- <para>
-  <command>nix-env</command> has many more flags. For details, see the
-  <citerefentry>
-  <refentrytitle>nix-env</refentrytitle>
-  <manvolnum>1</manvolnum></citerefentry> manpage or the Nix manual.
- </para>
-</section>
diff --git a/nixos/doc/manual/configuration/package-mgmt.xml b/nixos/doc/manual/configuration/package-mgmt.xml
index e8ac5d0681a..2f9395d26fa 100644
--- a/nixos/doc/manual/configuration/package-mgmt.xml
+++ b/nixos/doc/manual/configuration/package-mgmt.xml
@@ -27,5 +27,5 @@
   </itemizedlist>
  </para>
  <xi:include href="declarative-packages.xml" />
- <xi:include href="ad-hoc-packages.xml" />
+ <xi:include href="../from_md/configuration/ad-hoc-packages.section.xml" />
 </chapter>
diff --git a/nixos/doc/manual/from_md/configuration/ad-hoc-packages.section.xml b/nixos/doc/manual/from_md/configuration/ad-hoc-packages.section.xml
new file mode 100644
index 00000000000..c9a8d4f3f10
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/ad-hoc-packages.section.xml
@@ -0,0 +1,59 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-ad-hoc-packages">
+  <title>Ad-Hoc Package Management</title>
+  <para>
+    With the command <literal>nix-env</literal>, you can install and
+    uninstall packages from the command line. For instance, to install
+    Mozilla Thunderbird:
+  </para>
+  <programlisting>
+$ nix-env -iA nixos.thunderbird
+</programlisting>
+  <para>
+    If you invoke this as root, the package is installed in the Nix
+    profile <literal>/nix/var/nix/profiles/default</literal> and visible
+    to all users of the system; otherwise, the package ends up in
+    <literal>/nix/var/nix/profiles/per-user/username/profile</literal>
+    and is not visible to other users. The <literal>-A</literal> flag
+    specifies the package by its attribute name; without it, the package
+    is installed by matching against its package name (e.g.
+    <literal>thunderbird</literal>). The latter is slower because it
+    requires matching against all available Nix packages, and is
+    ambiguous if there are multiple matching packages.
+  </para>
+  <para>
+    Packages come from the NixOS channel. You typically upgrade a
+    package by updating to the latest version of the NixOS channel:
+  </para>
+  <programlisting>
+$ nix-channel --update nixos
+</programlisting>
+  <para>
+    and then running <literal>nix-env -i</literal> again. Other packages
+    in the profile are <emphasis>not</emphasis> affected; this is the
+    crucial difference with the declarative style of package management,
+    where running <literal>nixos-rebuild switch</literal> causes all
+    packages to be updated to their current versions in the NixOS
+    channel. You can however upgrade all packages for which there is a
+    newer version by doing:
+  </para>
+  <programlisting>
+$ nix-env -u '*'
+</programlisting>
+  <para>
+    A package can be uninstalled using the <literal>-e</literal> flag:
+  </para>
+  <programlisting>
+$ nix-env -e thunderbird
+</programlisting>
+  <para>
+    Finally, you can roll back an undesirable <literal>nix-env</literal>
+    action:
+  </para>
+  <programlisting>
+$ nix-env --rollback
+</programlisting>
+  <para>
+    <literal>nix-env</literal> has many more flags. For details, see the
+    nix-env(1) manpage or the Nix manual.
+  </para>
+</section>