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

4 files changed, 156 insertions, 74 deletions

diff --git a/nixos/doc/manual/configuration/adding-custom-packages.section.md b/nixos/doc/manual/configuration/adding-custom-packages.section.md
new file mode 100644
index 00000000000..14370c89126
--- /dev/null
+++ b/nixos/doc/manual/configuration/adding-custom-packages.section.md
@@ -0,0 +1,74 @@
+# Adding Custom Packages {#sec-custom-packages}
+
+It's possible that a package you need is not available in NixOS. In that
+case, you can do two things. First, you can clone the Nixpkgs
+repository, add the package to your clone, and (optionally) submit a
+patch or pull request to have it accepted into the main Nixpkgs repository.
+This is described in detail in the [Nixpkgs manual](https://nixos.org/nixpkgs/manual).
+In short, you clone Nixpkgs:
+
+```ShellSession
+$ git clone https://github.com/NixOS/nixpkgs
+$ cd nixpkgs
+```
+
+Then you write and test the package as described in the Nixpkgs manual.
+Finally, you add it to [`environment.systemPackages`](options.html#opt-environment.systemPackages), e.g.
+
+```nix
+environment.systemPackages = [ pkgs.my-package ];
+```
+
+and you run `nixos-rebuild`, specifying your own Nixpkgs tree:
+
+```ShellSession
+# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs
+```
+
+The second possibility is to add the package outside of the Nixpkgs
+tree. For instance, here is how you specify a build of the
+[GNU Hello](https://www.gnu.org/software/hello/) package directly in
+`configuration.nix`:
+
+```nix
+environment.systemPackages =
+  let
+    my-hello = with pkgs; stdenv.mkDerivation rec {
+      name = "hello-2.8";
+      src = fetchurl {
+        url = "mirror://gnu/hello/${name}.tar.gz";
+        sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
+      };
+    };
+  in
+  [ my-hello ];
+```
+
+Of course, you can also move the definition of `my-hello` into a
+separate Nix expression, e.g.
+
+```nix
+environment.systemPackages = [ (import ./my-hello.nix) ];
+```
+
+where `my-hello.nix` contains:
+
+```nix
+with import <nixpkgs> {}; # bring all of Nixpkgs into scope
+
+stdenv.mkDerivation rec {
+  name = "hello-2.8";
+  src = fetchurl {
+    url = "mirror://gnu/hello/${name}.tar.gz";
+    sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
+  };
+}
+```
+
+This allows testing the package easily:
+
+```ShellSession
+$ nix-build my-hello.nix
+$ ./result/bin/hello
+Hello, world!
+```
diff --git a/nixos/doc/manual/configuration/adding-custom-packages.xml b/nixos/doc/manual/configuration/adding-custom-packages.xml
deleted file mode 100644
index 19eb2429d0a..00000000000
--- a/nixos/doc/manual/configuration/adding-custom-packages.xml
+++ /dev/null
@@ -1,73 +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-custom-packages">
- <title>Adding Custom Packages</title>
-
- <para>
-  It’s possible that a package you need is not available in NixOS. In that
-  case, you can do two things. First, you can clone the Nixpkgs repository, add
-  the package to your clone, and (optionally) submit a patch or pull request to
-  have it accepted into the main Nixpkgs repository. This is described in
-  detail in the <link
-xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs
-  manual</link>. In short, you clone Nixpkgs:
-<screen>
-<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs
-<prompt>$ </prompt>cd nixpkgs
-</screen>
-  Then you write and test the package as described in the Nixpkgs manual.
-  Finally, you add it to <literal>environment.systemPackages</literal>, e.g.
-<programlisting>
-<xref linkend="opt-environment.systemPackages"/> = [ pkgs.my-package ];
-</programlisting>
-  and you run <command>nixos-rebuild</command>, specifying your own Nixpkgs
-  tree:
-<screen>
-<prompt># </prompt>nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>
- </para>
-
- <para>
-  The second possibility is to add the package outside of the Nixpkgs tree. For
-  instance, here is how you specify a build of the
-  <link xlink:href="https://www.gnu.org/software/hello/">GNU Hello</link>
-  package directly in <filename>configuration.nix</filename>:
-<programlisting>
-<xref linkend="opt-environment.systemPackages"/> =
-  let
-    my-hello = with pkgs; stdenv.mkDerivation rec {
-      name = "hello-2.8";
-      src = fetchurl {
-        url = "mirror://gnu/hello/${name}.tar.gz";
-        sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
-      };
-    };
-  in
-  [ my-hello ];
-</programlisting>
-  Of course, you can also move the definition of <literal>my-hello</literal>
-  into a separate Nix expression, e.g.
-<programlisting>
-<xref linkend="opt-environment.systemPackages"/> = [ (import ./my-hello.nix) ];
-</programlisting>
-  where <filename>my-hello.nix</filename> contains:
-<programlisting>
-with import &lt;nixpkgs> {}; # bring all of Nixpkgs into scope
-
-stdenv.mkDerivation rec {
-  name = "hello-2.8";
-  src = fetchurl {
-    url = "mirror://gnu/hello/${name}.tar.gz";
-    sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
-  };
-}
-</programlisting>
-  This allows testing the package easily:
-<screen>
-<prompt>$ </prompt>nix-build my-hello.nix
-<prompt>$ </prompt>./result/bin/hello
-Hello, world!
-</screen>
- </para>
-</section>
diff --git a/nixos/doc/manual/configuration/declarative-packages.xml b/nixos/doc/manual/configuration/declarative-packages.xml
index cd84d1951d2..648bb76cf3b 100644
--- a/nixos/doc/manual/configuration/declarative-packages.xml
+++ b/nixos/doc/manual/configuration/declarative-packages.xml
@@ -50,5 +50,5 @@ nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
 
  <xi:include href="customizing-packages.xml" />
 
- <xi:include href="adding-custom-packages.xml" />
+ <xi:include href="../from_md/configuration/adding-custom-packages.section.xml" />
 </section>
diff --git a/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml b/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml
new file mode 100644
index 00000000000..80e3aa69212
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml
@@ -0,0 +1,81 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-custom-packages">
+  <title>Adding Custom Packages</title>
+  <para>
+    It’s possible that a package you need is not available in NixOS. In
+    that case, you can do two things. First, you can clone the Nixpkgs
+    repository, add the package to your clone, and (optionally) submit a
+    patch or pull request to have it accepted into the main Nixpkgs
+    repository. This is described in detail in the
+    <link xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs
+    manual</link>. In short, you clone Nixpkgs:
+  </para>
+  <programlisting>
+$ git clone https://github.com/NixOS/nixpkgs
+$ cd nixpkgs
+</programlisting>
+  <para>
+    Then you write and test the package as described in the Nixpkgs
+    manual. Finally, you add it to
+    <link xlink:href="options.html#opt-environment.systemPackages"><literal>environment.systemPackages</literal></link>,
+    e.g.
+  </para>
+  <programlisting language="bash">
+environment.systemPackages = [ pkgs.my-package ];
+</programlisting>
+  <para>
+    and you run <literal>nixos-rebuild</literal>, specifying your own
+    Nixpkgs tree:
+  </para>
+  <programlisting>
+# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs
+</programlisting>
+  <para>
+    The second possibility is to add the package outside of the Nixpkgs
+    tree. For instance, here is how you specify a build of the
+    <link xlink:href="https://www.gnu.org/software/hello/">GNU
+    Hello</link> package directly in
+    <literal>configuration.nix</literal>:
+  </para>
+  <programlisting language="bash">
+environment.systemPackages =
+  let
+    my-hello = with pkgs; stdenv.mkDerivation rec {
+      name = &quot;hello-2.8&quot;;
+      src = fetchurl {
+        url = &quot;mirror://gnu/hello/${name}.tar.gz&quot;;
+        sha256 = &quot;0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6&quot;;
+      };
+    };
+  in
+  [ my-hello ];
+</programlisting>
+  <para>
+    Of course, you can also move the definition of
+    <literal>my-hello</literal> into a separate Nix expression, e.g.
+  </para>
+  <programlisting language="bash">
+environment.systemPackages = [ (import ./my-hello.nix) ];
+</programlisting>
+  <para>
+    where <literal>my-hello.nix</literal> contains:
+  </para>
+  <programlisting language="bash">
+with import &lt;nixpkgs&gt; {}; # bring all of Nixpkgs into scope
+
+stdenv.mkDerivation rec {
+  name = &quot;hello-2.8&quot;;
+  src = fetchurl {
+    url = &quot;mirror://gnu/hello/${name}.tar.gz&quot;;
+    sha256 = &quot;0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6&quot;;
+  };
+}
+</programlisting>
+  <para>
+    This allows testing the package easily:
+  </para>
+  <programlisting>
+$ nix-build my-hello.nix
+$ ./result/bin/hello
+Hello, world!
+</programlisting>
+</section>