doc/builders/images/*.xml: Convert to markdown

7 files changed, 121 insertions, 203 deletions

diff --git a/doc/builders/images.xml b/doc/builders/images.xml
index d7d25029189..cd10d69a96d 100644
--- a/doc/builders/images.xml
+++ b/doc/builders/images.xml
@@ -5,8 +5,8 @@
  <para>
   This chapter describes tools for creating various types of images.
  </para>
- <xi:include href="images/appimagetools.xml" />
+ <xi:include href="images/appimagetools.section.xml" />
  <xi:include href="images/dockertools.section.xml" />
  <xi:include href="images/ocitools.section.xml" />
- <xi:include href="images/snaptools.xml" />
+ <xi:include href="images/snaptools.section.xml" />
 </chapter>
diff --git a/doc/builders/images/appimagetools.section.md b/doc/builders/images/appimagetools.section.md
new file mode 100644
index 00000000000..7ab4e4e9d85
--- /dev/null
+++ b/doc/builders/images/appimagetools.section.md
@@ -0,0 +1,48 @@
+# pkgs.appimageTools {#sec-pkgs-appimageTools}
+
+`pkgs.appimageTools` is a set of functions for extracting and wrapping [AppImage](https://appimage.org/) files. They are meant to be used if traditional packaging from source is infeasible, or it would take too long. To quickly run an AppImage file, `pkgs.appimage-run` can be used as well.
+
+::: warning
+The `appimageTools` API is unstable and may be subject to backwards-incompatible changes in the future.
+:::
+
+## AppImage formats {#ssec-pkgs-appimageTools-formats}
+
+There are different formats for AppImages, see [the specification](https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format) for details.
+
+- Type 1 images are ISO 9660 files that are also ELF executables.
+- Type 2 images are ELF executables with an appended filesystem.
+
+They can be told apart with `file -k`:
+
+```ShellSession
+$ file -k type1.AppImage
+type1.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) ISO 9660 CD-ROM filesystem data 'AppImage' (Lepton 3.x), scale 0-0,
+spot sensor temperature 0.000000, unit celsius, color scheme 0, calibration: offset 0.000000, slope 0.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=d629f6099d2344ad82818172add1d38c5e11bc6d, stripped\012- data
+
+$ file -k type2.AppImage
+type2.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) (Lepton 3.x), scale 232-60668, spot sensor temperature -4.187500, color scheme 15, show scale bar, calibration: offset -0.000000, slope 0.000000 (Lepton 2.x), scale 4111-45000, spot sensor temperature 412442.250000, color scheme 3, minimum point enabled, calibration: offset -75402534979642766821519867692934234112.000000, slope 5815371847733706829839455140374904832.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=79dcc4e55a61c293c5e19edbd8d65b202842579f, stripped\012- data
+```
+
+Note how the type 1 AppImage is described as an `ISO 9660 CD-ROM filesystem`, and the type 2 AppImage is not.
+
+## Wrapping {#ssec-pkgs-appimageTools-wrapping}
+
+Depending on the type of AppImage you're wrapping, you'll have to use `wrapType1` or `wrapType2`.
+
+```nix
+appimageTools.wrapType2 { # or wrapType1
+  name = "patchwork";
+  src = fetchurl {
+    url = "https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage";
+    sha256 = "1blsprpkvm0ws9b96gb36f0rbf8f5jgmw4x6dsb1kswr4ysf591s";
+  };
+  extraPkgs = pkgs: with pkgs; [ ];
+}
+```
+
+- `name` specifies the name of the resulting image.
+- `src` specifies the AppImage file to extract.
+- `extraPkgs` allows you to pass a function to include additional packages inside the FHS environment your AppImage is going to run in. There are a few ways to learn which dependencies an application needs:
+  - Looking through the extracted AppImage files, reading its scripts and running `patchelf` and `ldd` on its executables. This can also be done in `appimage-run`, by setting `APPIMAGE_DEBUG_EXEC=bash`.
+  - Running `strace -vfefile` on the wrapped executable, looking for libraries that can't be found.
diff --git a/doc/builders/images/appimagetools.xml b/doc/builders/images/appimagetools.xml
deleted file mode 100644
index 45c5619abd9..00000000000
--- a/doc/builders/images/appimagetools.xml
+++ /dev/null
@@ -1,102 +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"
-         xml:id="sec-pkgs-appimageTools">
- <title>pkgs.appimageTools</title>
-
- <para>
-  <varname>pkgs.appimageTools</varname> is a set of functions for extracting and wrapping <link xlink:href="https://appimage.org/">AppImage</link> files. They are meant to be used if traditional packaging from source is infeasible, or it would take too long. To quickly run an AppImage file, <literal>pkgs.appimage-run</literal> can be used as well.
- </para>
-
- <warning>
-  <para>
-   The <varname>appimageTools</varname> API is unstable and may be subject to backwards-incompatible changes in the future.
-  </para>
- </warning>
-
- <section xml:id="ssec-pkgs-appimageTools-formats">
-  <title>AppImage formats</title>
-
-  <para>
-   There are different formats for AppImages, see <link xlink:href="https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format">the specification</link> for details.
-  </para>
-
-  <itemizedlist>
-   <listitem>
-    <para>
-     Type 1 images are ISO 9660 files that are also ELF executables.
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     Type 2 images are ELF executables with an appended filesystem.
-    </para>
-   </listitem>
-  </itemizedlist>
-
-  <para>
-   They can be told apart with <command>file -k</command>:
-  </para>
-
-<screen>
-<prompt>$ </prompt>file -k type1.AppImage
-type1.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) ISO 9660 CD-ROM filesystem data 'AppImage' (Lepton 3.x), scale 0-0,
-spot sensor temperature 0.000000, unit celsius, color scheme 0, calibration: offset 0.000000, slope 0.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=d629f6099d2344ad82818172add1d38c5e11bc6d, stripped\012- data
-
-<prompt>$ </prompt>file -k type2.AppImage
-type2.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) (Lepton 3.x), scale 232-60668, spot sensor temperature -4.187500, color scheme 15, show scale bar, calibration: offset -0.000000, slope 0.000000 (Lepton 2.x), scale 4111-45000, spot sensor temperature 412442.250000, color scheme 3, minimum point enabled, calibration: offset -75402534979642766821519867692934234112.000000, slope 5815371847733706829839455140374904832.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=79dcc4e55a61c293c5e19edbd8d65b202842579f, stripped\012- data
-</screen>
-
-  <para>
-   Note how the type 1 AppImage is described as an <literal>ISO 9660 CD-ROM filesystem</literal>, and the type 2 AppImage is not.
-  </para>
- </section>
-
- <section xml:id="ssec-pkgs-appimageTools-wrapping">
-  <title>Wrapping</title>
-
-  <para>
-   Depending on the type of AppImage you're wrapping, you'll have to use <varname>wrapType1</varname> or <varname>wrapType2</varname>.
-  </para>
-
-<programlisting>
-appimageTools.wrapType2 { # or wrapType1
-  name = "patchwork"; <co xml:id='ex-appimageTools-wrapping-1' />
-  src = fetchurl { <co xml:id='ex-appimageTools-wrapping-2' />
-    url = "https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage";
-    sha256 =  "1blsprpkvm0ws9b96gb36f0rbf8f5jgmw4x6dsb1kswr4ysf591s";
-  };
-  extraPkgs = pkgs: with pkgs; [ ]; <co xml:id='ex-appimageTools-wrapping-3' />
-}</programlisting>
-
-  <calloutlist>
-   <callout arearefs='ex-appimageTools-wrapping-1'>
-    <para>
-     <varname>name</varname> specifies the name of the resulting image.
-    </para>
-   </callout>
-   <callout arearefs='ex-appimageTools-wrapping-2'>
-    <para>
-     <varname>src</varname> specifies the AppImage file to extract.
-    </para>
-   </callout>
-   <callout arearefs='ex-appimageTools-wrapping-3'>
-    <para>
-     <varname>extraPkgs</varname> allows you to pass a function to include additional packages inside the FHS environment your AppImage is going to run in. There are a few ways to learn which dependencies an application needs:
-     <itemizedlist>
-      <listitem>
-       <para>
-        Looking through the extracted AppImage files, reading its scripts and running <command>patchelf</command> and <command>ldd</command> on its executables. This can also be done in <command>appimage-run</command>, by setting <command>APPIMAGE_DEBUG_EXEC=bash</command>.
-       </para>
-      </listitem>
-      <listitem>
-       <para>
-        Running <command>strace -vfefile</command> on the wrapped executable, looking for libraries that can't be found.
-       </para>
-      </listitem>
-     </itemizedlist>
-    </para>
-   </callout>
-  </calloutlist>
- </section>
-</section>
diff --git a/doc/builders/images/snap/example-firefox.nix b/doc/builders/images/snap/example-firefox.nix
deleted file mode 100644
index d58c98a65a2..00000000000
--- a/doc/builders/images/snap/example-firefox.nix
+++ /dev/null
@@ -1,28 +0,0 @@
-let
-  inherit (import <nixpkgs> { }) snapTools firefox;
-in snapTools.makeSnap {
-  meta = {
-    name = "nix-example-firefox";
-    summary = firefox.meta.description;
-    architectures = [ "amd64" ];
-    apps.nix-example-firefox = {
-      command = "${firefox}/bin/firefox";
-      plugs = [
-        "pulseaudio"
-        "camera"
-        "browser-support"
-        "avahi-observe"
-        "cups-control"
-        "desktop"
-        "desktop-legacy"
-        "gsettings"
-        "home"
-        "network"
-        "mount-observe"
-        "removable-media"
-        "x11"
-      ];
-    };
-    confinement = "strict";
-  };
-}
diff --git a/doc/builders/images/snap/example-hello.nix b/doc/builders/images/snap/example-hello.nix
deleted file mode 100644
index 123da80c547..00000000000
--- a/doc/builders/images/snap/example-hello.nix
+++ /dev/null
@@ -1,12 +0,0 @@
-let
-  inherit (import <nixpkgs> { }) snapTools hello;
-in snapTools.makeSnap {
-  meta = {
-    name = "hello";
-    summary = hello.meta.description;
-    description = hello.meta.longDescription;
-    architectures = [ "amd64" ];
-    confinement = "strict";
-    apps.hello.command = "${hello}/bin/hello";
-  };
-}
diff --git a/doc/builders/images/snaptools.section.md b/doc/builders/images/snaptools.section.md
new file mode 100644
index 00000000000..9e1403b8828
--- /dev/null
+++ b/doc/builders/images/snaptools.section.md
@@ -0,0 +1,71 @@
+# pkgs.snapTools {#sec-pkgs-snapTools}
+
+`pkgs.snapTools` is a set of functions for creating Snapcraft images. Snap and Snapcraft is not used to perform these operations.
+
+## The makeSnap Function {#ssec-pkgs-snapTools-makeSnap-signature}
+
+`makeSnap` takes a single named argument, `meta`. This argument mirrors [the upstream `snap.yaml` format](https://docs.snapcraft.io/snap-format) exactly.
+
+The `base` should not be specified, as `makeSnap` will force set it.
+
+Currently, `makeSnap` does not support creating GUI stubs.
+
+## Build a Hello World Snap {#ssec-pkgs-snapTools-build-a-snap-hello}
+
+The following expression packages GNU Hello as a Snapcraft snap.
+
+```{#ex-snapTools-buildSnap-hello .nix}
+let
+  inherit (import <nixpkgs> { }) snapTools hello;
+in snapTools.makeSnap {
+  meta = {
+    name = "hello";
+    summary = hello.meta.description;
+    description = hello.meta.longDescription;
+    architectures = [ "amd64" ];
+    confinement = "strict";
+    apps.hello.command = "${hello}/bin/hello";
+  };
+}
+```
+
+`nix-build` this expression and install it with `snap install ./result --dangerous`. `hello` will now be the Snapcraft version of the package.
+
+## Build a Graphical Snap {#ssec-pkgs-snapTools-build-a-snap-firefox}
+
+Graphical programs require many more integrations with the host. This example uses Firefox as an example, because it is one of the most complicated programs we could package.
+
+```{#ex-snapTools-buildSnap-firefox .nix}
+let
+  inherit (import <nixpkgs> { }) snapTools firefox;
+in snapTools.makeSnap {
+  meta = {
+    name = "nix-example-firefox";
+    summary = firefox.meta.description;
+    architectures = [ "amd64" ];
+    apps.nix-example-firefox = {
+      command = "${firefox}/bin/firefox";
+      plugs = [
+        "pulseaudio"
+        "camera"
+        "browser-support"
+        "avahi-observe"
+        "cups-control"
+        "desktop"
+        "desktop-legacy"
+        "gsettings"
+        "home"
+        "network"
+        "mount-observe"
+        "removable-media"
+        "x11"
+      ];
+    };
+    confinement = "strict";
+  };
+}
+```
+
+`nix-build` this expression and install it with `snap install ./result --dangerous`. `nix-example-firefox` will now be the Snapcraft version of the Firefox package.
+
+The specific meaning behind plugs can be looked up in the [Snapcraft interface documentation](https://docs.snapcraft.io/supported-interfaces).
diff --git a/doc/builders/images/snaptools.xml b/doc/builders/images/snaptools.xml
deleted file mode 100644
index bbe2e3f5e14..00000000000
--- a/doc/builders/images/snaptools.xml
+++ /dev/null
@@ -1,59 +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"
-         xml:id="sec-pkgs-snapTools">
- <title>pkgs.snapTools</title>
-
- <para>
-  <varname>pkgs.snapTools</varname> is a set of functions for creating Snapcraft images. Snap and Snapcraft is not used to perform these operations.
- </para>
-
- <section xml:id="ssec-pkgs-snapTools-makeSnap-signature">
-  <title>The makeSnap Function</title>
-
-  <para>
-   <function>makeSnap</function> takes a single named argument, <parameter>meta</parameter>. This argument mirrors <link xlink:href="https://docs.snapcraft.io/snap-format">the upstream <filename>snap.yaml</filename> format</link> exactly.
-  </para>
-
-  <para>
-   The <parameter>base</parameter> should not be specified, as <function>makeSnap</function> will force set it.
-  </para>
-
-  <para>
-   Currently, <function>makeSnap</function> does not support creating GUI stubs.
-  </para>
- </section>
-
- <section xml:id="ssec-pkgs-snapTools-build-a-snap-hello">
-  <title>Build a Hello World Snap</title>
-
-  <example xml:id="ex-snapTools-buildSnap-hello">
-   <title>Making a Hello World Snap</title>
-   <para>
-    The following expression packages GNU Hello as a Snapcraft snap.
-   </para>
-<programlisting><xi:include href="./snap/example-hello.nix" parse="text" /></programlisting>
-   <para>
-    <command>nix-build</command> this expression and install it with <command>snap install ./result --dangerous</command>. <command>hello</command> will now be the Snapcraft version of the package.
-   </para>
-  </example>
- </section>
-
- <section xml:id="ssec-pkgs-snapTools-build-a-snap-firefox">
-  <title>Build a Hello World Snap</title>
-
-  <example xml:id="ex-snapTools-buildSnap-firefox">
-   <title>Making a Graphical Snap</title>
-   <para>
-    Graphical programs require many more integrations with the host. This example uses Firefox as an example, because it is one of the most complicated programs we could package.
-   </para>
-<programlisting><xi:include href="./snap/example-firefox.nix" parse="text" /></programlisting>
-   <para>
-    <command>nix-build</command> this expression and install it with <command>snap install ./result --dangerous</command>. <command>nix-example-firefox</command> will now be the Snapcraft version of the Firefox package.
-   </para>
-   <para>
-    The specific meaning behind plugs can be looked up in the <link xlink:href="https://docs.snapcraft.io/supported-interfaces">Snapcraft interface documentation</link>.
-   </para>
-  </example>
- </section>
-</section>