doc: format the documentation (#57102)

17 files changed, 764 insertions, 764 deletions

diff --git a/doc/.gitignore b/doc/.gitignore
index cb07135e6858..b5c58be03d15 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1,7 +1,8 @@
 *.chapter.xml
 *.section.xml
 .version
-out
-manual-full.xml
-highlightjs
+functions/library/generated
 functions/library/locations.xml
+highlightjs
+manual-full.xml
+out
diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml
index d2c7a1baae9c..58ce9c7e627c 100644
--- a/doc/coding-conventions.xml
+++ b/doc/coding-conventions.xml
@@ -197,20 +197,14 @@ args.stdenv.mkDerivation (args // {
   <title>Package naming</title>
 
   <para>
-    The key words
-    <emphasis>must</emphasis>,
-    <emphasis>must not</emphasis>,
-    <emphasis>required</emphasis>,
-    <emphasis>shall</emphasis>,
-    <emphasis>shall not</emphasis>,
-    <emphasis>should</emphasis>,
-    <emphasis>should not</emphasis>,
-    <emphasis>recommended</emphasis>,
-    <emphasis>may</emphasis>,
-    and <emphasis>optional</emphasis> in this section
-    are to be interpreted as described in
-    <link xlink:href="https://tools.ietf.org/html/rfc2119">RFC 2119</link>.
-    Only <emphasis>emphasized</emphasis> words are to be interpreted in this way.
+   The key words <emphasis>must</emphasis>, <emphasis>must not</emphasis>,
+   <emphasis>required</emphasis>, <emphasis>shall</emphasis>, <emphasis>shall
+   not</emphasis>, <emphasis>should</emphasis>, <emphasis>should
+   not</emphasis>, <emphasis>recommended</emphasis>, <emphasis>may</emphasis>,
+   and <emphasis>optional</emphasis> in this section are to be interpreted as
+   described in <link xlink:href="https://tools.ietf.org/html/rfc2119">RFC
+   2119</link>. Only <emphasis>emphasized</emphasis> words are to be
+   interpreted in this way.
   </para>
 
   <para>
@@ -253,15 +247,15 @@ args.stdenv.mkDerivation (args // {
    <itemizedlist>
     <listitem>
      <para>
-       The <literal>name</literal> attribute <emphasis>should</emphasis>
-       be identical to the upstream package name.
+      The <literal>name</literal> attribute <emphasis>should</emphasis> be
+      identical to the upstream package name.
      </para>
     </listitem>
     <listitem>
      <para>
-       The <literal>name</literal> attribute <emphasis>must not</emphasis>
-       contain uppercase letters — e.g., <literal>"mplayer-1.0rc2"</literal>
-       instead of <literal>"MPlayer-1.0rc2"</literal>.
+      The <literal>name</literal> attribute <emphasis>must not</emphasis>
+      contain uppercase letters — e.g., <literal>"mplayer-1.0rc2"</literal>
+      instead of <literal>"MPlayer-1.0rc2"</literal>.
      </para>
     </listitem>
     <listitem>
@@ -275,28 +269,29 @@ args.stdenv.mkDerivation (args // {
      <para>
       If a package is not a release but a commit from a repository, then the
       version part of the name <emphasis>must</emphasis> be the date of that
-      (fetched) commit. The date <emphasis>must</emphasis> be in <literal>"YYYY-MM-DD"</literal>
-      format. Also append <literal>"unstable"</literal> to the name - e.g.,
+      (fetched) commit. The date <emphasis>must</emphasis> be in
+      <literal>"YYYY-MM-DD"</literal> format. Also append
+      <literal>"unstable"</literal> to the name - e.g.,
       <literal>"pkgname-unstable-2014-09-23"</literal>.
      </para>
     </listitem>
     <listitem>
      <para>
-      Dashes in the package name <emphasis>should</emphasis> be preserved in new variable names,
-      rather than converted to underscores or camel cased — e.g.,
-      <varname>http-parser</varname> instead of <varname>http_parser</varname>
-      or <varname>httpParser</varname>. The hyphenated style is preferred in
-      all three package names.
+      Dashes in the package name <emphasis>should</emphasis> be preserved in
+      new variable names, rather than converted to underscores or camel cased
+      — e.g., <varname>http-parser</varname> instead of
+      <varname>http_parser</varname> or <varname>httpParser</varname>. The
+      hyphenated style is preferred in all three package names.
      </para>
     </listitem>
     <listitem>
      <para>
-      If there are multiple versions of a package, this <emphasis>should</emphasis> be reflected in
-      the variable names in <filename>all-packages.nix</filename>, e.g.
-      <varname>json-c-0-9</varname> and <varname>json-c-0-11</varname>. If
-      there is an obvious “default” version, make an attribute like
-      <literal>json-c = json-c-0-9;</literal>. See also
-      <xref linkend="sec-versioning" />
+      If there are multiple versions of a package, this
+      <emphasis>should</emphasis> be reflected in the variable names in
+      <filename>all-packages.nix</filename>, e.g. <varname>json-c-0-9</varname>
+      and <varname>json-c-0-11</varname>. If there is an obvious “default”
+      version, make an attribute like <literal>json-c = json-c-0-9;</literal>.
+      See also <xref linkend="sec-versioning" />
      </para>
     </listitem>
    </itemizedlist>
@@ -814,8 +809,8 @@ args.stdenv.mkDerivation (args // {
 
   <para>
    There are multiple ways to fetch a package source in nixpkgs. The general
-   guideline is that you should package reproducible sources with a high degree of
-   availability. Right now there is only one fetcher which has mirroring
+   guideline is that you should package reproducible sources with a high degree
+   of availability. Right now there is only one fetcher which has mirroring
    support and that is <literal>fetchurl</literal>. Note that you should also
    prefer protocols which have a corresponding proxy environment variable.
   </para>
@@ -869,8 +864,10 @@ src = fetchFromGitHub {
 }
 </programlisting>
       Find the value to put as <literal>sha256</literal> by running
-      <literal>nix run -f '&lt;nixpkgs&gt;' nix-prefetch-github -c nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS nix</literal>
-      or <literal>nix-prefetch-url --unpack https://github.com/NixOS/nix/archive/1f795f9f44607cc5bec70d1300150bfefcef2aae.tar.gz</literal>.
+      <literal>nix run -f '&lt;nixpkgs&gt;' nix-prefetch-github -c
+      nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS
+      nix</literal> or <literal>nix-prefetch-url --unpack
+      https://github.com/NixOS/nix/archive/1f795f9f44607cc5bec70d1300150bfefcef2aae.tar.gz</literal>.
      </para>
     </listitem>
    </itemizedlist>
@@ -953,17 +950,23 @@ $ nix-hash --type sha256 --to-base32 <replaceable>HASH</replaceable>
      would be replace hash with a fake one and rebuild. Nix build will fail and
      error message will contain desired hash.
     </para>
-    <warning><para>This method has security problems. Check below for details.</para></warning>
+    <warning>
+     <para>
+      This method has security problems. Check below for details.
+     </para>
+    </warning>
    </listitem>
   </orderedlist>
 
   <section xml:id="sec-source-hashes-security">
    <title>Obtaining hashes securely</title>
+
    <para>
-    Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead of fetching
-    source you can fetch malware, and instead of source hash you get hash of malware. Here are
-    security considerations for this scenario:
+    Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead
+    of fetching source you can fetch malware, and instead of source hash you
+    get hash of malware. Here are security considerations for this scenario:
    </para>
+
    <itemizedlist>
     <listitem>
      <para>
@@ -972,7 +975,8 @@ $ nix-hash --type sha256 --to-base32 <replaceable>HASH</replaceable>
     </listitem>
     <listitem>
      <para>
-      hashes from upstream (in method 3) should be obtained via secure protocol;
+      hashes from upstream (in method 3) should be obtained via secure
+      protocol;
      </para>
     </listitem>
     <listitem>
@@ -982,12 +986,12 @@ $ nix-hash --type sha256 --to-base32 <replaceable>HASH</replaceable>
     </listitem>
     <listitem>
      <para>
-      <literal>https://</literal> URLs are not secure in method 5. When obtaining hashes
-      with fake hash method, TLS checks are disabled. So
-      refetch source hash from several different networks to exclude MITM scenario.
-      Alternatively, use fake hash method to make Nix error, but instead of extracting
-      hash from error, extract <literal>https://</literal> URL and prefetch it
-      with method 1.
+      <literal>https://</literal> URLs are not secure in method 5. When
+      obtaining hashes with fake hash method, TLS checks are disabled. So
+      refetch source hash from several different networks to exclude MITM
+      scenario. Alternatively, use fake hash method to make Nix error, but
+      instead of extracting hash from error, extract
+      <literal>https://</literal> URL and prefetch it with method 1.
      </para>
     </listitem>
    </itemizedlist>
diff --git a/doc/configuration.xml b/doc/configuration.xml
index 8a5ff8dcb8e0..b497fa4e2722 100644
--- a/doc/configuration.xml
+++ b/doc/configuration.xml
@@ -132,13 +132,13 @@
   </itemizedlist>
 
   <para>
-   The difference between a package being unsupported on some system and
-   being broken is admittedly a bit fuzzy. If a program
-   <emphasis>ought</emphasis> to work on a certain platform, but doesn't, the
-   platform should be included in <literal>meta.platforms</literal>, but marked
-   as broken with e.g. <literal>meta.broken =
-   !hostPlatform.isWindows</literal>. Of course, this begs the question of what
-   "ought" means exactly. That is left to the package maintainer.
+   The difference between a package being unsupported on some system and being
+   broken is admittedly a bit fuzzy. If a program <emphasis>ought</emphasis> to
+   work on a certain platform, but doesn't, the platform should be included in
+   <literal>meta.platforms</literal>, but marked as broken with e.g.
+   <literal>meta.broken = !hostPlatform.isWindows</literal>. Of course, this
+   begs the question of what "ought" means exactly. That is left to the package
+   maintainer.
   </para>
  </section>
  <section xml:id="sec-allow-unfree">
@@ -175,9 +175,8 @@
 </programlisting>
     </para>
     <para>
-     For a more useful example, try the following. This configuration
-     only allows unfree packages named flash player and visual studio
-     code:
+     For a more useful example, try the following. This configuration only
+     allows unfree packages named flash player and visual studio code:
 <programlisting>
 {
   allowUnfreePredicate = (pkg: builtins.elem
diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml
index 324fe5bdd02a..dbaf6f104ec0 100644
--- a/doc/cross-compilation.xml
+++ b/doc/cross-compilation.xml
@@ -6,17 +6,17 @@
   <title>Introduction</title>
 
   <para>
-   "Cross-compilation" means compiling a program on one machine for another type
-   of machine. For example, a typical use of cross-compilation is to compile
-   programs for embedded devices. These devices often don't have the computing
-   power and memory to compile their own programs. One might think that
-   cross-compilation is a fairly niche concern. However, there are significant
-   advantages to rigorously distinguishing between build-time and run-time
-   environments! This applies even when one is developing and deploying on the
-   same machine. Nixpkgs is increasingly adopting the opinion that packages
-   should be written with cross-compilation in mind, and nixpkgs should evaluate
-   in a similar way (by minimizing cross-compilation-specific special cases)
-   whether or not one is cross-compiling.
+   "Cross-compilation" means compiling a program on one machine for another
+   type of machine. For example, a typical use of cross-compilation is to
+   compile programs for embedded devices. These devices often don't have the
+   computing power and memory to compile their own programs. One might think
+   that cross-compilation is a fairly niche concern. However, there are
+   significant advantages to rigorously distinguishing between build-time and
+   run-time environments! This applies even when one is developing and
+   deploying on the same machine. Nixpkgs is increasingly adopting the opinion
+   that packages should be written with cross-compilation in mind, and nixpkgs
+   should evaluate in a similar way (by minimizing cross-compilation-specific
+   special cases) whether or not one is cross-compiling.
   </para>
 
   <para>
@@ -34,15 +34,16 @@
    <title>Platform parameters</title>
 
    <para>
-     Nixpkgs follows the <link
+    Nixpkgs follows the
+    <link
      xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html">conventions
-     of GNU autoconf</link>. We distinguish between 3 types of platforms when
-     building a derivation: <wordasword>build</wordasword>,
-     <wordasword>host</wordasword>, and <wordasword>target</wordasword>. In
-     summary, <wordasword>build</wordasword> is the platform on which a package
-     is being built, <wordasword>host</wordasword> is the platform on which it
-     will run. The third attribute, <wordasword>target</wordasword>, is relevant
-     only for certain specific compilers and build tools.
+    of GNU autoconf</link>. We distinguish between 3 types of platforms when
+    building a derivation: <wordasword>build</wordasword>,
+    <wordasword>host</wordasword>, and <wordasword>target</wordasword>. In
+    summary, <wordasword>build</wordasword> is the platform on which a package
+    is being built, <wordasword>host</wordasword> is the platform on which it
+    will run. The third attribute, <wordasword>target</wordasword>, is relevant
+    only for certain specific compilers and build tools.
    </para>
 
    <para>
@@ -95,10 +96,10 @@
        The build process of certain compilers is written in such a way that the
        compiler resulting from a single build can itself only produce binaries
        for a single platform. The task of specifying this single "target
-       platform" is thus pushed to build time of the compiler. The root cause of
-       this is that the compiler (which will be run on the host) and the standard
-       library/runtime (which will be run on the target) are built by a single
-       build process.
+       platform" is thus pushed to build time of the compiler. The root cause
+       of this is that the compiler (which will be run on the host) and the
+       standard library/runtime (which will be run on the target) are built by
+       a single build process.
       </para>
       <para>
        There is no fundamental need to think about a single target ahead of
@@ -136,9 +137,9 @@
        This is a two-component shorthand for the platform. Examples of this
        would be "x86_64-darwin" and "i686-linux"; see
        <literal>lib.systems.doubles</literal> for more. The first component
-       corresponds to the CPU architecture of the platform and the second to the
-       operating system of the platform (<literal>[cpu]-[os]</literal>). This
-       format has built-in support in Nix, such as the
+       corresponds to the CPU architecture of the platform and the second to
+       the operating system of the platform (<literal>[cpu]-[os]</literal>).
+       This format has built-in support in Nix, such as the
        <varname>builtins.currentSystem</varname> impure string.
       </para>
      </listitem>
@@ -149,14 +150,14 @@
      </term>
      <listitem>
       <para>
-       This is a 3- or 4- component shorthand for the platform. Examples of this
-       would be <literal>x86_64-unknown-linux-gnu</literal> and
+       This is a 3- or 4- component shorthand for the platform. Examples of
+       this would be <literal>x86_64-unknown-linux-gnu</literal> and
        <literal>aarch64-apple-darwin14</literal>. This is a standard format
        called the "LLVM target triple", as they are pioneered by LLVM. In the
        4-part form, this corresponds to
        <literal>[cpu]-[vendor]-[os]-[abi]</literal>. This format is strictly
-       more informative than the "Nix host double", as the previous format could
-       analogously be termed. This needs a better name than
+       more informative than the "Nix host double", as the previous format
+       could analogously be termed. This needs a better name than
        <varname>config</varname>!
       </para>
      </listitem>
@@ -167,11 +168,10 @@
      </term>
      <listitem>
       <para>
-       This is a Nix representation of a parsed LLVM target triple
-       with white-listed components. This can be specified directly,
-       or actually parsed from the <varname>config</varname>. See
-       <literal>lib.systems.parse</literal> for the exact
-       representation.
+       This is a Nix representation of a parsed LLVM target triple with
+       white-listed components. This can be specified directly, or actually
+       parsed from the <varname>config</varname>. See
+       <literal>lib.systems.parse</literal> for the exact representation.
       </para>
      </listitem>
     </varlistentry>
@@ -253,15 +253,15 @@
    <para>
     Some examples will make this clearer. If a package is being built with a
     <literal>(build, host, target)</literal> platform triple of <literal>(foo,
-    bar, bar)</literal>, then its build-time dependencies would have a triple of
-    <literal>(foo, foo, bar)</literal>, and <emphasis>those packages'</emphasis>
-    build-time dependencies would have a triple of <literal>(foo, foo,
-    foo)</literal>. In other words, it should take two "rounds" of following
-    build-time dependency edges before one reaches a fixed point where, by the
-    sliding window principle, the platform triple no longer changes. Indeed,
-    this happens with cross-compilation, where only rounds of native
-    dependencies starting with the second necessarily coincide with native
-    packages.
+    bar, bar)</literal>, then its build-time dependencies would have a triple
+    of <literal>(foo, foo, bar)</literal>, and <emphasis>those
+    packages'</emphasis> build-time dependencies would have a triple of
+    <literal>(foo, foo, foo)</literal>. In other words, it should take two
+    "rounds" of following build-time dependency edges before one reaches a
+    fixed point where, by the sliding window principle, the platform triple no
+    longer changes. Indeed, this happens with cross-compilation, where only
+    rounds of native dependencies starting with the second necessarily coincide
+    with native packages.
    </para>
 
    <note>
@@ -273,23 +273,24 @@
    </note>
 
    <para>
-    How does this work in practice? Nixpkgs is now structured so that build-time
-    dependencies are taken from <varname>buildPackages</varname>, whereas
-    run-time dependencies are taken from the top level attribute set. For
-    example, <varname>buildPackages.gcc</varname> should be used at build-time,
-    while <varname>gcc</varname> should be used at run-time. Now, for most of
-    Nixpkgs's history, there was no <varname>buildPackages</varname>, and most
-    packages have not been refactored to use it explicitly. Instead, one can use
-    the six (<emphasis>gasp</emphasis>) attributes used for specifying
-    dependencies as documented in <xref linkend="ssec-stdenv-dependencies"/>. We
-    "splice" together the run-time and build-time package sets with
-    <varname>callPackage</varname>, and then <varname>mkDerivation</varname> for
-    each of four attributes pulls the right derivation out. This splicing can be
-    skipped when not cross-compiling as the package sets are the same, but is a
-    bit slow for cross-compiling. Because of this, a best-of-both-worlds
-    solution is in the works with no splicing or explicit access of
-    <varname>buildPackages</varname> needed. For now, feel free to use either
-    method.
+    How does this work in practice? Nixpkgs is now structured so that
+    build-time dependencies are taken from <varname>buildPackages</varname>,
+    whereas run-time dependencies are taken from the top level attribute set.
+    For example, <varname>buildPackages.gcc</varname> should be used at
+    build-time, while <varname>gcc</varname> should be used at run-time. Now,
+    for most of Nixpkgs's history, there was no
+    <varname>buildPackages</varname>, and most packages have not been
+    refactored to use it explicitly. Instead, one can use the six
+    (<emphasis>gasp</emphasis>) attributes used for specifying dependencies as
+    documented in <xref linkend="ssec-stdenv-dependencies"/>. We "splice"
+    together the run-time and build-time package sets with
+    <varname>callPackage</varname>, and then <varname>mkDerivation</varname>
+    for each of four attributes pulls the right derivation out. This splicing
+    can be skipped when not cross-compiling as the package sets are the same,
+    but is a bit slow for cross-compiling. Because of this, a
+    best-of-both-worlds solution is in the works with no splicing or explicit
+    access of <varname>buildPackages</varname> needed. For now, feel free to
+    use either method.
    </para>
 
    <note>
@@ -311,8 +312,8 @@
     should be answered here. Ideally, the information above is exhaustive, so
     this section cannot provide any new information, but it is ludicrous and
     cruel to expect everyone to spend effort working through the interaction of
-    many features just to figure out the same answer to the same common problem.
-    Feel free to add to this list!
+    many features just to figure out the same answer to the same common
+    problem. Feel free to add to this list!
    </para>
 
    <qandaset>
@@ -434,14 +435,15 @@ nix-build &lt;nixpkgs&gt; --arg crossSystem '{ config = "&lt;arch&gt;-&lt;os&gt;
    build plan or package set. A simple "build vs deploy" dichotomy is adequate:
    the sliding window principle described in the previous section shows how to
    interpolate between the these two "end points" to get the 3 platform triple
-   for each bootstrapping stage. That means for any package a given package set,
-   even those not bound on the top level but only reachable via dependencies or
-   <varname>buildPackages</varname>, the three platforms will be defined as one
-   of <varname>localSystem</varname> or <varname>crossSystem</varname>, with the
-   former replacing the latter as one traverses build-time dependencies. A last
-   simple difference is that <varname>crossSystem</varname> should be null when
-   one doesn't want to cross-compile, while the <varname>*Platform</varname>s
-   are always non-null. <varname>localSystem</varname> is always non-null.
+   for each bootstrapping stage. That means for any package a given package
+   set, even those not bound on the top level but only reachable via
+   dependencies or <varname>buildPackages</varname>, the three platforms will
+   be defined as one of <varname>localSystem</varname> or
+   <varname>crossSystem</varname>, with the former replacing the latter as one
+   traverses build-time dependencies. A last simple difference is that
+   <varname>crossSystem</varname> should be null when one doesn't want to
+   cross-compile, while the <varname>*Platform</varname>s are always non-null.
+   <varname>localSystem</varname> is always non-null.
   </para>
  </section>
 <!--============================================================-->
@@ -455,13 +457,13 @@ nix-build &lt;nixpkgs&gt; --arg crossSystem '{ config = "&lt;arch&gt;-&lt;os&gt;
   <note>
    <para>
     If one explores Nixpkgs, they will see derivations with names like
-    <literal>gccCross</literal>. Such <literal>*Cross</literal> derivations is a
-    holdover from before we properly distinguished between the host and target
-    platforms—the derivation with "Cross" in the name covered the <literal>build
-    = host != target</literal> case, while the other covered the <literal>host =
-    target</literal>, with build platform the same or not based on whether one
-    was using its <literal>.nativeDrv</literal> or <literal>.crossDrv</literal>.
-    This ugliness will disappear soon.
+    <literal>gccCross</literal>. Such <literal>*Cross</literal> derivations is
+    a holdover from before we properly distinguished between the host and
+    target platforms—the derivation with "Cross" in the name covered the
+    <literal>build = host != target</literal> case, while the other covered the
+    <literal>host = target</literal>, with build platform the same or not based
+    on whether one was using its <literal>.nativeDrv</literal> or
+    <literal>.crossDrv</literal>. This ugliness will disappear soon.
    </para>
   </note>
  </section>
diff --git a/doc/functions/appimagetools.xml b/doc/functions/appimagetools.xml
index 270ab067bc39..4205c6da3851 100644
--- a/doc/functions/appimagetools.xml
+++ b/doc/functions/appimagetools.xml
@@ -5,11 +5,11 @@
  <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.
+  <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>
@@ -19,13 +19,13 @@
   </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.
+   <link xlink:href="https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format">the
+   specification</link> for details.
   </para>
 
   <itemizedlist>
@@ -34,7 +34,6 @@
      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.
@@ -46,7 +45,7 @@
    They can be told apart with <command>file -k</command>:
   </para>
 
-  <screen>
+<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
@@ -56,7 +55,8 @@ type2.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) (Lepton 3.x)
   </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.
+   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>
 
@@ -64,12 +64,11 @@ type2.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) (Lepton 3.x)
   <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>.
+   Depending on the type of AppImage you're wrapping, you'll have to use
+   <varname>wrapType1</varname> or <varname>wrapType2</varname>.
   </para>
 
-
-  <programlisting>
+<programlisting>
 appimageTools.wrapType2 { # or wrapType1
   name = "patchwork"; <co xml:id='ex-appimageTools-wrapping-1' />
   src = fetchurl { <co xml:id='ex-appimageTools-wrapping-2' />
@@ -79,7 +78,6 @@ appimageTools.wrapType2 { # or wrapType1
   extraPkgs = pkgs: with pkgs; [ ]; <co xml:id='ex-appimageTools-wrapping-3' />
 }</programlisting>
 
-
   <calloutlist>
    <callout arearefs='ex-appimageTools-wrapping-1'>
     <para>
@@ -93,29 +91,28 @@ appimageTools.wrapType2 { # or wrapType1
    </callout>
    <callout arearefs='ex-appimageTools-wrapping-2'>
     <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>
-
+     <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/functions/dockertools.xml b/doc/functions/dockertools.xml
index 2c8eb2cb7743..75db0bd3918c 100644
--- a/doc/functions/dockertools.xml
+++ b/doc/functions/dockertools.xml
@@ -24,9 +24,9 @@
 
   <para>
    This function is analogous to the <command>docker build</command> command,
-   in that it can be used to build a Docker-compatible repository tarball containing
-   a single image with one or multiple layers. As such, the result is suitable
-   for being loaded in Docker with <command>docker load</command>.
+   in that it can be used to build a Docker-compatible repository tarball
+   containing a single image with one or multiple layers. As such, the result
+   is suitable for being loaded in Docker with <command>docker load</command>.
   </para>
 
   <para>
@@ -190,8 +190,8 @@ buildImage {
     By default <function>buildImage</function> will use a static date of one
     second past the UNIX Epoch. This allows <function>buildImage</function> to
     produce binary reproducible images. When listing images with
-    <command>docker images</command>, the newly created images will be
-    listed like this:
+    <command>docker images</command>, the newly created images will be listed
+    like this:
    </para>
 <screen><![CDATA[
 $ docker images
@@ -402,9 +402,9 @@ pkgs.dockerTools.buildLayeredImage {