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

4 files changed, 165 insertions, 87 deletions

diff --git a/nixos/doc/manual/configuration/customizing-packages.section.md b/nixos/doc/manual/configuration/customizing-packages.section.md
new file mode 100644
index 00000000000..480aed61211
--- /dev/null
+++ b/nixos/doc/manual/configuration/customizing-packages.section.md
@@ -0,0 +1,74 @@
+# Customising Packages {#sec-customising-packages}
+
+Some packages in Nixpkgs have options to enable or disable optional
+functionality or change other aspects of the package. For instance, the
+Firefox wrapper package (which provides Firefox with a set of plugins
+such as the Adobe Flash player) has an option to enable the Google Talk
+plugin. It can be set in `configuration.nix` as follows:
+`nixpkgs.config.firefox.enableGoogleTalkPlugin = true;`
+
+::: {.warning}
+Unfortunately, Nixpkgs currently lacks a way to query available
+configuration options.
+:::
+
+Apart from high-level options, it's possible to tweak a package in
+almost arbitrary ways, such as changing or disabling dependencies of a
+package. For instance, the Emacs package in Nixpkgs by default has a
+dependency on GTK 2. If you want to build it against GTK 3, you can
+specify that as follows:
+
+```nix
+environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
+```
+
+The function `override` performs the call to the Nix function that
+produces Emacs, with the original arguments amended by the set of
+arguments specified by you. So here the function argument `gtk` gets the
+value `pkgs.gtk3`, causing Emacs to depend on GTK 3. (The parentheses
+are necessary because in Nix, function application binds more weakly
+than list construction, so without them,
+[`environment.systemPackages`](options.html#opt-environment.systemPackages)
+would be a list with two elements.)
+
+Even greater customisation is possible using the function
+`overrideAttrs`. While the `override` mechanism above overrides the
+arguments of a package function, `overrideAttrs` allows changing the
+*attributes* passed to `mkDerivation`. This permits changing any aspect
+of the package, such as the source code. For instance, if you want to
+override the source code of Emacs, you can say:
+
+```nix
+environment.systemPackages = [
+  (pkgs.emacs.overrideAttrs (oldAttrs: {
+    name = "emacs-25.0-pre";
+    src = /path/to/my/emacs/tree;
+  }))
+];
+```
+
+Here, `overrideAttrs` takes the Nix derivation specified by `pkgs.emacs`
+and produces a new derivation in which the original's `name` and `src`
+attribute have been replaced by the given values by re-calling
+`stdenv.mkDerivation`. The original attributes are accessible via the
+function argument, which is conventionally named `oldAttrs`.
+
+The overrides shown above are not global. They do not affect the
+original package; other packages in Nixpkgs continue to depend on the
+original rather than the customised package. This means that if another
+package in your system depends on the original package, you end up with
+two instances of the package. If you want to have everything depend on
+your customised instance, you can apply a *global* override as follows:
+
+```nix
+nixpkgs.config.packageOverrides = pkgs:
+  { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
+  };
+```
+
+The effect of this definition is essentially equivalent to modifying the
+`emacs` attribute in the Nixpkgs source tree. Any package in Nixpkgs
+that depends on `emacs` will be passed your customised instance.
+(However, the value `pkgs.emacs` in `nixpkgs.config.packageOverrides`
+refers to the original rather than overridden instance, to prevent an
+infinite recursion.)
diff --git a/nixos/doc/manual/configuration/customizing-packages.xml b/nixos/doc/manual/configuration/customizing-packages.xml
deleted file mode 100644
index 34e6ab4b24d..00000000000
--- a/nixos/doc/manual/configuration/customizing-packages.xml
+++ /dev/null
@@ -1,86 +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-customising-packages">
- <title>Customising Packages</title>
-
- <para>
-  Some packages in Nixpkgs have options to enable or disable optional
-  functionality or change other aspects of the package. For instance, the
-  Firefox wrapper package (which provides Firefox with a set of plugins such as
-  the Adobe Flash player) has an option to enable the Google Talk plugin. It
-  can be set in <filename>configuration.nix</filename> as follows: <filename>
-  nixpkgs.config.firefox.enableGoogleTalkPlugin = true; </filename>
- </para>
-
- <warning>
-  <para>
-   Unfortunately, Nixpkgs currently lacks a way to query available
-   configuration options.
-  </para>
- </warning>
-
- <para>
-  Apart from high-level options, it’s possible to tweak a package in almost
-  arbitrary ways, such as changing or disabling dependencies of a package. For
-  instance, the Emacs package in Nixpkgs by default has a dependency on GTK 2.
-  If you want to build it against GTK 3, you can specify that as follows:
-<programlisting>
-<xref linkend="opt-environment.systemPackages"/> = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
-</programlisting>
-  The function <varname>override</varname> performs the call to the Nix
-  function that produces Emacs, with the original arguments amended by the set
-  of arguments specified by you. So here the function argument
-  <varname>gtk</varname> gets the value <literal>pkgs.gtk3</literal>, causing
-  Emacs to depend on GTK 3. (The parentheses are necessary because in Nix,
-  function application binds more weakly than list construction, so without
-  them, <xref linkend="opt-environment.systemPackages"/> would be a list with
-  two elements.)
- </para>
-
- <para>
-  Even greater customisation is possible using the function
-  <varname>overrideAttrs</varname>. While the <varname>override</varname>
-  mechanism above overrides the arguments of a package function,
-  <varname>overrideAttrs</varname> allows changing the
-  <emphasis>attributes</emphasis> passed to <literal>mkDerivation</literal>.
-  This permits changing any aspect of the package, such as the source code. For
-  instance, if you want to override the source code of Emacs, you can say:
-<programlisting>
-<xref linkend="opt-environment.systemPackages"/> = [
-  (pkgs.emacs.overrideAttrs (oldAttrs: {
-    name = "emacs-25.0-pre";
-    src = /path/to/my/emacs/tree;
-  }))
-];
-</programlisting>
-  Here, <varname>overrideAttrs</varname> takes the Nix derivation specified by
-  <varname>pkgs.emacs</varname> and produces a new derivation in which the
-  original’s <literal>name</literal> and <literal>src</literal> attribute
-  have been replaced by the given values by re-calling
-  <literal>stdenv.mkDerivation</literal>. The original attributes are
-  accessible via the function argument, which is conventionally named
-  <varname>oldAttrs</varname>.
- </para>
-
- <para>
-  The overrides shown above are not global. They do not affect the original
-  package; other packages in Nixpkgs continue to depend on the original rather
-  than the customised package. This means that if another package in your
-  system depends on the original package, you end up with two instances of the
-  package. If you want to have everything depend on your customised instance,
-  you can apply a <emphasis>global</emphasis> override as follows:
-<screen>
-nixpkgs.config.packageOverrides = pkgs:
-  { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
-  };
-</screen>
-  The effect of this definition is essentially equivalent to modifying the
-  <literal>emacs</literal> attribute in the Nixpkgs source tree. Any package in
-  Nixpkgs that depends on <literal>emacs</literal> will be passed your
-  customised instance. (However, the value <literal>pkgs.emacs</literal> in
-  <varname>nixpkgs.config.packageOverrides</varname> refers to the original
-  rather than overridden instance, to prevent an infinite recursion.)
- </para>
-</section>
diff --git a/nixos/doc/manual/configuration/declarative-packages.xml b/nixos/doc/manual/configuration/declarative-packages.xml
index 648bb76cf3b..8d321929f3f 100644
--- a/nixos/doc/manual/configuration/declarative-packages.xml
+++ b/nixos/doc/manual/configuration/declarative-packages.xml
@@ -48,7 +48,7 @@ nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
   <command>nixos-rebuild switch</command>.
  </para>
 
- <xi:include href="customizing-packages.xml" />
+ <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/from_md/configuration/customizing-packages.section.xml b/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml
new file mode 100644
index 00000000000..661fb8475b3
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml
@@ -0,0 +1,90 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-customising-packages">
+  <title>Customising Packages</title>
+  <para>
+    Some packages in Nixpkgs have options to enable or disable optional
+    functionality or change other aspects of the package. For instance,
+    the Firefox wrapper package (which provides Firefox with a set of
+    plugins such as the Adobe Flash player) has an option to enable the
+    Google Talk plugin. It can be set in
+    <literal>configuration.nix</literal> as follows:
+    <literal>nixpkgs.config.firefox.enableGoogleTalkPlugin = true;</literal>
+  </para>
+  <warning>
+    <para>
+      Unfortunately, Nixpkgs currently lacks a way to query available
+      configuration options.
+    </para>
+  </warning>
+  <para>
+    Apart from high-level options, it’s possible to tweak a package in
+    almost arbitrary ways, such as changing or disabling dependencies of
+    a package. For instance, the Emacs package in Nixpkgs by default has
+    a dependency on GTK 2. If you want to build it against GTK 3, you
+    can specify that as follows:
+  </para>
+  <programlisting language="bash">
+environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
+</programlisting>
+  <para>
+    The function <literal>override</literal> performs the call to the
+    Nix function that produces Emacs, with the original arguments
+    amended by the set of arguments specified by you. So here the
+    function argument <literal>gtk</literal> gets the value
+    <literal>pkgs.gtk3</literal>, causing Emacs to depend on GTK 3. (The
+    parentheses are necessary because in Nix, function application binds
+    more weakly than list construction, so without them,
+    <link xlink:href="options.html#opt-environment.systemPackages"><literal>environment.systemPackages</literal></link>
+    would be a list with two elements.)
+  </para>
+  <para>
+    Even greater customisation is possible using the function
+    <literal>overrideAttrs</literal>. While the
+    <literal>override</literal> mechanism above overrides the arguments
+    of a package function, <literal>overrideAttrs</literal> allows
+    changing the <emphasis>attributes</emphasis> passed to
+    <literal>mkDerivation</literal>. This permits changing any aspect of
+    the package, such as the source code. For instance, if you want to
+    override the source code of Emacs, you can say:
+  </para>
+  <programlisting language="bash">
+environment.systemPackages = [
+  (pkgs.emacs.overrideAttrs (oldAttrs: {
+    name = &quot;emacs-25.0-pre&quot;;
+    src = /path/to/my/emacs/tree;
+  }))
+];
+</programlisting>
+  <para>
+    Here, <literal>overrideAttrs</literal> takes the Nix derivation
+    specified by <literal>pkgs.emacs</literal> and produces a new
+    derivation in which the original’s <literal>name</literal> and
+    <literal>src</literal> attribute have been replaced by the given
+    values by re-calling <literal>stdenv.mkDerivation</literal>. The
+    original attributes are accessible via the function argument, which
+    is conventionally named <literal>oldAttrs</literal>.
+  </para>
+  <para>
+    The overrides shown above are not global. They do not affect the
+    original package; other packages in Nixpkgs continue to depend on
+    the original rather than the customised package. This means that if
+    another package in your system depends on the original package, you
+    end up with two instances of the package. If you want to have
+    everything depend on your customised instance, you can apply a
+    <emphasis>global</emphasis> override as follows:
+  </para>
+  <programlisting language="bash">
+nixpkgs.config.packageOverrides = pkgs:
+  { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
+  };
+</programlisting>
+  <para>
+    The effect of this definition is essentially equivalent to modifying
+    the <literal>emacs</literal> attribute in the Nixpkgs source tree.
+    Any package in Nixpkgs that depends on <literal>emacs</literal> will
+    be passed your customised instance. (However, the value
+    <literal>pkgs.emacs</literal> in
+    <literal>nixpkgs.config.packageOverrides</literal> refers to the
+    original rather than overridden instance, to prevent an infinite
+    recursion.)
+  </para>
+</section>