nixos: nixos/doc/manual/configuration/declarative-packages.xml to CommonMark

4 files changed, 100 insertions, 55 deletions

diff --git a/nixos/doc/manual/configuration/declarative-packages.section.md b/nixos/doc/manual/configuration/declarative-packages.section.md
new file mode 100644
index 00000000000..337cdf8472e
--- /dev/null
+++ b/nixos/doc/manual/configuration/declarative-packages.section.md
@@ -0,0 +1,46 @@
+# Declarative Package Management {#sec-declarative-package-mgmt}
+
+With declarative package management, you specify which packages you want
+on your system by setting the option
+[](#opt-environment.systemPackages). For instance, adding the
+following line to `configuration.nix` enables the Mozilla Thunderbird
+email application:
+
+```nix
+environment.systemPackages = [ pkgs.thunderbird ];
+```
+
+The effect of this specification is that the Thunderbird package from
+Nixpkgs will be built or downloaded as part of the system when you run
+`nixos-rebuild switch`.
+
+::: {.note}
+Some packages require additional global configuration such as D-Bus or
+systemd service registration so adding them to
+[](#opt-environment.systemPackages) might not be sufficient. You are
+advised to check the [list of options](#ch-options) whether a NixOS
+module for the package does not exist.
+:::
+
+You can get a list of the available packages as follows:
+
+```ShellSession
+$ nix-env -qaP '*' --description
+nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
+...
+```
+
+The first column in the output is the *attribute name*, such as
+`nixos.thunderbird`.
+
+Note: the `nixos` prefix tells us that we want to get the package from
+the `nixos` channel and works only in CLI tools. In declarative
+configuration use `pkgs` prefix (variable).
+
+To "uninstall" a package, simply remove it from
+[](#opt-environment.systemPackages) and run `nixos-rebuild switch`.
+
+```{=docbook}
+<xi:include href="customizing-packages.section.xml" />
+<xi:include href="adding-custom-packages.section.xml" />
+```
diff --git a/nixos/doc/manual/configuration/declarative-packages.xml b/nixos/doc/manual/configuration/declarative-packages.xml
deleted file mode 100644
index 8d321929f3f..00000000000
--- a/nixos/doc/manual/configuration/declarative-packages.xml
+++ /dev/null
@@ -1,54 +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-declarative-package-mgmt">
- <title>Declarative Package Management</title>
-
- <para>
-  With declarative package management, you specify which packages you want on
-  your system by setting the option
-  <xref linkend="opt-environment.systemPackages"/>. For instance, adding the
-  following line to <filename>configuration.nix</filename> enables the Mozilla
-  Thunderbird email application:
-<programlisting>
-<xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird ];
-</programlisting>
-  The effect of this specification is that the Thunderbird package from Nixpkgs
-  will be built or downloaded as part of the system when you run
-  <command>nixos-rebuild switch</command>.
- </para>
-
- <note>
-  <para>
-   Some packages require additional global configuration such as D-Bus or systemd service registration so adding them to <xref linkend="opt-environment.systemPackages"/> might not be sufficient. You are advised to check the <link xlink:href="#ch-options">list of options</link> whether a NixOS module for the package does not exist.
-  </para>
- </note>
-
- <para>
-  You can get a list of the available packages as follows:
-<screen>
-<prompt>$ </prompt>nix-env -qaP '*' --description
-nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
-<replaceable>...</replaceable>
-</screen>
-  The first column in the output is the <emphasis>attribute name</emphasis>,
-  such as <literal>nixos.thunderbird</literal>.
- </para>
- <para>
-  Note: the <literal>nixos</literal> prefix tells us that we want to get the
-  package from the <literal>nixos</literal> channel and works only in CLI tools.
-
-  In declarative configuration use <literal>pkgs</literal> prefix (variable).
- </para>
-
- <para>
-  To “uninstall” a package, simply remove it from
-  <xref linkend="opt-environment.systemPackages"/> and run
-  <command>nixos-rebuild switch</command>.
- </para>
-
- <xi:include href="../from_md/configuration/customizing-packages.section.xml" />
-
- <xi:include href="../from_md/configuration/adding-custom-packages.section.xml" />
-</section>
diff --git a/nixos/doc/manual/configuration/package-mgmt.xml b/nixos/doc/manual/configuration/package-mgmt.xml
index 2f9395d26fa..499926ea50b 100644
--- a/nixos/doc/manual/configuration/package-mgmt.xml
+++ b/nixos/doc/manual/configuration/package-mgmt.xml
@@ -26,6 +26,6 @@
    </listitem>
   </itemizedlist>
  </para>
- <xi:include href="declarative-packages.xml" />
+ <xi:include href="../from_md/configuration/declarative-packages.section.xml" />
  <xi:include href="../from_md/configuration/ad-hoc-packages.section.xml" />
 </chapter>
diff --git a/nixos/doc/manual/from_md/configuration/declarative-packages.section.xml b/nixos/doc/manual/from_md/configuration/declarative-packages.section.xml
new file mode 100644
index 00000000000..da31f18d923
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/declarative-packages.section.xml
@@ -0,0 +1,53 @@
+<section xmlns="http://docbook.org/ns/docbook"  xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-declarative-package-mgmt">
+  <title>Declarative Package Management</title>
+  <para>
+    With declarative package management, you specify which packages you
+    want on your system by setting the option
+    <xref linkend="opt-environment.systemPackages" />. For instance,
+    adding the following line to <literal>configuration.nix</literal>
+    enables the Mozilla Thunderbird email application:
+  </para>
+  <programlisting language="bash">
+environment.systemPackages = [ pkgs.thunderbird ];
+</programlisting>
+  <para>
+    The effect of this specification is that the Thunderbird package
+    from Nixpkgs will be built or downloaded as part of the system when
+    you run <literal>nixos-rebuild switch</literal>.
+  </para>
+  <note>
+    <para>
+      Some packages require additional global configuration such as
+      D-Bus or systemd service registration so adding them to
+      <xref linkend="opt-environment.systemPackages" /> might not be
+      sufficient. You are advised to check the
+      <link linkend="ch-options">list of options</link> whether a NixOS
+      module for the package does not exist.
+    </para>
+  </note>
+  <para>
+    You can get a list of the available packages as follows:
+  </para>
+  <programlisting>
+$ nix-env -qaP '*' --description
+nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
+...
+</programlisting>
+  <para>
+    The first column in the output is the <emphasis>attribute
+    name</emphasis>, such as <literal>nixos.thunderbird</literal>.
+  </para>
+  <para>
+    Note: the <literal>nixos</literal> prefix tells us that we want to
+    get the package from the <literal>nixos</literal> channel and works
+    only in CLI tools. In declarative configuration use
+    <literal>pkgs</literal> prefix (variable).
+  </para>
+  <para>
+    To <quote>uninstall</quote> a package, simply remove it from
+    <xref linkend="opt-environment.systemPackages" /> and run
+    <literal>nixos-rebuild switch</literal>.
+  </para>
+  <xi:include href="customizing-packages.section.xml" />
+  <xi:include href="adding-custom-packages.section.xml" />
+</section>