Merge pull request #105752 from ryantm/docbook2commonmark-packages-linux

docs: convert packages/linux docbook -> commonmark

3 files changed, 42 insertions, 86 deletions

diff --git a/doc/builders/packages/index.xml b/doc/builders/packages/index.xml
index 44e89169629d..baf9b8db01be 100644
--- a/doc/builders/packages/index.xml
+++ b/doc/builders/packages/index.xml
@@ -12,7 +12,7 @@
  <xi:include href="emacs.section.xml" />
  <xi:include href="ibus.xml" />
  <xi:include href="kakoune.section.xml" />
- <xi:include href="linux.xml" />
+ <xi:include href="linux.section.xml" />
  <xi:include href="locales.xml" />
  <xi:include href="nginx.section.xml" />
  <xi:include href="opengl.section.xml" />
diff --git a/doc/builders/packages/linux.section.md b/doc/builders/packages/linux.section.md
new file mode 100644
index 000000000000..1b8d6eda749d
--- /dev/null
+++ b/doc/builders/packages/linux.section.md
@@ -0,0 +1,41 @@
+# Linux kernel {#sec-linux-kernel}
+
+The Nix expressions to build the Linux kernel are in [`pkgs/os-specific/linux/kernel`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/os-specific/linux/kernel).
+
+The function that builds the kernel has an argument `kernelPatches` which should be a list of `{name, patch, extraConfig}` attribute sets, where `name` is the name of the patch (which is included in the kernel’s `meta.description` attribute), `patch` is the patch itself (possibly compressed), and `extraConfig` (optional) is a string specifying extra options to be concatenated to the kernel configuration file (`.config`).
+
+The kernel derivation exports an attribute `features` specifying whether optional functionality is or isn’t enabled. This is used in NixOS to implement kernel-specific behaviour. For instance, if the kernel has the `iwlwifi` feature (i.e. has built-in support for Intel wireless chipsets), then NixOS doesn’t have to build the external `iwlwifi` package:
+
+```nix
+modulesTree = [kernel]
+  ++ pkgs.lib.optional (!kernel.features ? iwlwifi) kernelPackages.iwlwifi
+  ++ ...;
+```
+
+How to add a new (major) version of the Linux kernel to Nixpkgs:
+
+1.  Copy the old Nix expression (e.g. `linux-2.6.21.nix`) to the new one (e.g. `linux-2.6.22.nix`) and update it.
+
+2.  Add the new kernel to `all-packages.nix` (e.g., create an attribute `kernel_2_6_22`).
+
+3.  Now we’re going to update the kernel configuration. First unpack the kernel. Then for each supported platform (`i686`, `x86_64`, `uml`) do the following:
+
+    1.  Make an copy from the old config (e.g. `config-2.6.21-i686-smp`) to the new one (e.g. `config-2.6.22-i686-smp`).
+
+    2.  Copy the config file for this platform (e.g. `config-2.6.22-i686-smp`) to `.config` in the kernel source tree.
+
+    3.  Run `make oldconfig ARCH={i386,x86_64,um}` and answer all questions. (For the uml configuration, also add `SHELL=bash`.) Make sure to keep the configuration consistent between platforms (i.e. don’t enable some feature on `i686` and disable it on `x86_64`).
+
+    4.  If needed you can also run `make menuconfig`:
+
+        ```ShellSession
+        $ nix-env -i ncurses
+        $ export NIX_CFLAGS_LINK=-lncurses
+        $ make menuconfig ARCH=arch
+        ```
+
+    5.  Copy `.config` over the new config file (e.g. `config-2.6.22-i686-smp`).
+
+4.  Test building the kernel: `nix-build -A kernel_2_6_22`. If it compiles, ship it! For extra credit, try booting NixOS with it.
+
+5.  It may be that the new kernel requires updating the external kernel modules and kernel-dependent packages listed in the `linuxPackagesFor` function in `all-packages.nix` (such as the NVIDIA drivers, AUFS, etc.). If the updated packages aren’t backwards compatible with older kernels, you may need to keep the older versions around.
diff --git a/doc/builders/packages/linux.xml b/doc/builders/packages/linux.xml
deleted file mode 100644
index 72d0e21493b3..000000000000
--- a/doc/builders/packages/linux.xml
+++ /dev/null
@@ -1,85 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="sec-linux-kernel">
- <title>Linux kernel</title>
-
- <para>
-  The Nix expressions to build the Linux kernel are in <link
-xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/os-specific/linux/kernel"><filename>pkgs/os-specific/linux/kernel</filename></link>.
- </para>
-
- <para>
-  The function that builds the kernel has an argument <varname>kernelPatches</varname> which should be a list of <literal>{name, patch, extraConfig}</literal> attribute sets, where <varname>name</varname> is the name of the patch (which is included in the kernel’s <varname>meta.description</varname> attribute), <varname>patch</varname> is the patch itself (possibly compressed), and <varname>extraConfig</varname> (optional) is a string specifying extra options to be concatenated to the kernel configuration file (<filename>.config</filename>).
- </para>
-
- <para>
-  The kernel derivation exports an attribute <varname>features</varname> specifying whether optional functionality is or isn’t enabled. This is used in NixOS to implement kernel-specific behaviour. For instance, if the kernel has the <varname>iwlwifi</varname> feature (i.e. has built-in support for Intel wireless chipsets), then NixOS doesn’t have to build the external <varname>iwlwifi</varname> package:
-<programlisting>
-modulesTree = [kernel]
-  ++ pkgs.lib.optional (!kernel.features ? iwlwifi) kernelPackages.iwlwifi
-  ++ ...;
-</programlisting>
- </para>
-
- <para>
-  How to add a new (major) version of the Linux kernel to Nixpkgs:
-  <orderedlist>
-   <listitem>
-    <para>
-     Copy the old Nix expression (e.g. <filename>linux-2.6.21.nix</filename>) to the new one (e.g. <filename>linux-2.6.22.nix</filename>) and update it.
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     Add the new kernel to <filename>all-packages.nix</filename> (e.g., create an attribute <varname>kernel_2_6_22</varname>).
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     Now we’re going to update the kernel configuration. First unpack the kernel. Then for each supported platform (<literal>i686</literal>, <literal>x86_64</literal>, <literal>uml</literal>) do the following:
-     <orderedlist>
-      <listitem>
-       <para>
-        Make an copy from the old config (e.g. <filename>config-2.6.21-i686-smp</filename>) to the new one (e.g. <filename>config-2.6.22-i686-smp</filename>).
-       </para>
-      </listitem>
-      <listitem>
-       <para>
-        Copy the config file for this platform (e.g. <filename>config-2.6.22-i686-smp</filename>) to <filename>.config</filename> in the kernel source tree.
-       </para>
-      </listitem>
-      <listitem>
-       <para>
-        Run <literal>make oldconfig ARCH=<replaceable>{i386,x86_64,um}</replaceable></literal> and answer all questions. (For the uml configuration, also add <literal>SHELL=bash</literal>.) Make sure to keep the configuration consistent between platforms (i.e. don’t enable some feature on <literal>i686</literal> and disable it on <literal>x86_64</literal>).
-       </para>
-      </listitem>
-      <listitem>
-       <para>
-        If needed you can also run <literal>make menuconfig</literal>:
-<screen>
-<prompt>$ </prompt>nix-env -i ncurses
-<prompt>$ </prompt>export NIX_CFLAGS_LINK=-lncurses
-<prompt>$ </prompt>make menuconfig ARCH=<replaceable>arch</replaceable></screen>
-       </para>
-      </listitem>
-      <listitem>
-       <para>
-        Copy <filename>.config</filename> over the new config file (e.g. <filename>config-2.6.22-i686-smp</filename>).
-       </para>
-      </listitem>
-     </orderedlist>
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     Test building the kernel: <literal>nix-build -A kernel_2_6_22</literal>. If it compiles, ship it! For extra credit, try booting NixOS with it.
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     It may be that the new kernel requires updating the external kernel modules and kernel-dependent packages listed in the <varname>linuxPackagesFor</varname> function in <filename>all-packages.nix</filename> (such as the NVIDIA drivers, AUFS, etc.). If the updated packages aren’t backwards compatible with older kernels, you may need to keep the older versions around.
-    </para>
-   </listitem>
-  </orderedlist>
- </para>
-</section>