doc: format the documentation (#57102)

7 files changed, 283 insertions, 300 deletions

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 {
 
   <para>
    This function is analogous to the <command>docker pull</command> command, in
-   that it can be used to pull a Docker image from a Docker registry. By default
-   <link xlink:href="https://hub.docker.com/">Docker Hub</link> is used to pull
-   images.
+   that it can be used to pull a Docker image from a Docker registry. By
+   default <link xlink:href="https://hub.docker.com/">Docker Hub</link> is used
+   to pull images.
   </para>
 
   <para>
@@ -484,10 +484,10 @@ sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b
 
   <para>
    This function is analogous to the <command>docker export</command> command,
-   in that it can be used to flatten a Docker image that contains multiple layers. It
-   is in fact the result of the merge of all the layers of the image. As such,
-   the result is suitable for being imported in Docker with <command>docker
-   import</command>.
+   in that it can be used to flatten a Docker image that contains multiple
+   layers. It is in fact the result of the merge of all the layers of the
+   image. As such, the result is suitable for being imported in Docker with
+   <command>docker import</command>.
   </para>
 
   <note>
diff --git a/doc/functions/fetchers.xml b/doc/functions/fetchers.xml
index b3bd2fe0f45e..a736008c9d41 100644
--- a/doc/functions/fetchers.xml
+++ b/doc/functions/fetchers.xml
@@ -5,24 +5,21 @@
  <title>Fetcher functions</title>
 
  <para>
-   When using Nix, you will frequently need to download source code
-   and other files from the internet. Nixpkgs comes with a few helper
-   functions that allow you to fetch fixed-output derivations in a
-   structured way.
+  When using Nix, you will frequently need to download source code and other
+  files from the internet. Nixpkgs comes with a few helper functions that allow
+  you to fetch fixed-output derivations in a structured way.
  </para>
 
  <para>
-   The two fetcher primitives are <function>fetchurl</function> and
-   <function>fetchzip</function>. Both of these have two required
-   arguments, a URL and a hash. The hash is typically
-   <literal>sha256</literal>, although many more hash algorithms are
-   supported. Nixpkgs contributors are currently recommended to use
-   <literal>sha256</literal>. This hash will be used by Nix to
-   identify your source. A typical usage of fetchurl is provided
-   below.
+  The two fetcher primitives are <function>fetchurl</function> and
+  <function>fetchzip</function>. Both of these have two required arguments, a
+  URL and a hash. The hash is typically <literal>sha256</literal>, although
+  many more hash algorithms are supported. Nixpkgs contributors are currently
+  recommended to use <literal>sha256</literal>. This hash will be used by Nix
+  to identify your source. A typical usage of fetchurl is provided below.
  </para>
 
- <programlisting><![CDATA[
+<programlisting><![CDATA[
 { stdenv, fetchurl }:
 
 stdenv.mkDerivation {
@@ -35,172 +32,163 @@ stdenv.mkDerivation {
 ]]></programlisting>
 
  <para>
-   The main difference between <function>fetchurl</function> and
-   <function>fetchzip</function> is in how they store the contents.
-   <function>fetchurl</function> will store the unaltered contents of
-   the URL within the Nix store. <function>fetchzip</function> on the
-   other hand will decompress the archive for you, making files and
-   directories directly accessible in the future.
-   <function>fetchzip</function> can only be used with archives.
-   Despite the name, <function>fetchzip</function> is not limited to
-   .zip files and can also be used with any tarball.
+  The main difference between <function>fetchurl</function> and
+  <function>fetchzip</function> is in how they store the contents.
+  <function>fetchurl</function> will store the unaltered contents of the URL
+  within the Nix store. <function>fetchzip</function> on the other hand will
+  decompress the archive for you, making files and directories directly
+  accessible in the future. <function>fetchzip</function> can only be used with
+  archives. Despite the name, <function>fetchzip</function> is not limited to
+  .zip files and can also be used with any tarball.
  </para>
 
  <para>
-   <function>fetchpatch</function> works very similarly to
-   <function>fetchurl</function> with the same arguments expected. It
-   expects patch files as a source and and performs normalization on
-   them before computing the checksum. For example it will remove
-   comments or other unstable parts that are sometimes added by
-   version control systems and can change over time.
+  <function>fetchpatch</function> works very similarly to
+  <function>fetchurl</function> with the same arguments expected. It expects
+  patch files as a source and and performs normalization on them before
+  computing the checksum. For example it will remove comments or other unstable
+  parts that are sometimes added by version control systems and can change over
+  time.
  </para>
 
  <para>
-   Other fetcher functions allow you to add source code directly from
-   a VCS such as subversion or git. These are mostly straightforward
-   names based on the name of the command used with the VCS system.
-   Because they give you a working repository, they act most like
-   <function>fetchzip</function>.
+  Other fetcher functions allow you to add source code directly from a VCS such
+  as subversion or git. These are mostly straightforward names based on the
+  name of the command used with the VCS system. Because they give you a working
+  repository, they act most like <function>fetchzip</function>.
  </para>
 
  <variablelist>
-   <varlistentry>
-     <term>
-      <literal>fetchsvn</literal>
-     </term>
-     <listitem>
-      <para>
-       Used with Subversion. Expects <literal>url</literal> to a
-       Subversion directory, <literal>rev</literal>, and
-       <literal>sha256</literal>.
-      </para>
-     </listitem>
-   </varlistentry>
-   <varlistentry>
-     <term>
-      <literal>fetchgit</literal>
-     </term>
-     <listitem>
-      <para>
-       Used with Git. Expects <literal>url</literal> to a Git repo,
-       <literal>rev</literal>, and <literal>sha256</literal>.
-       <literal>rev</literal> in this case can be full the git commit
-       id (SHA1 hash) or a tag name like
-       <literal>refs/tags/v1.0</literal>.
-      </para>
-     </listitem>
-   </varlistentry>
-   <varlistentry>
-     <term>
-      <literal>fetchfossil</literal>
-     </term>
-     <listitem>
-      <para>
-       Used with Fossil. Expects <literal>url</literal> to a Fossil
-       archive, <literal>rev</literal>, and <literal>sha256</literal>.
-      </para>
-     </listitem>
-   </varlistentry>
-   <varlistentry>
-     <term>
-      <literal>fetchcvs</literal>
-     </term>
-     <listitem>
-      <para>
-       Used with CVS. Expects <literal>cvsRoot</literal>,
-       <literal>tag</literal>, and <literal>sha256</literal>.
-      </para>
-     </listitem>
-   </varlistentry>
-   <varlistentry>
-     <term>
-      <literal>fetchhg</literal>
-     </term>
-     <listitem>
-      <para>
-       Used with Mercurial. Expects <literal>url</literal>,
-       <literal>rev</literal>, and <literal>sha256</literal>.
-      </para>
-     </listitem>
-   </varlistentry>
+  <varlistentry>
+   <term>
+    <literal>fetchsvn</literal>
+   </term>
+   <listitem>
+    <para>
+     Used with Subversion. Expects <literal>url</literal> to a Subversion
+     directory, <literal>rev</literal>, and <literal>sha256</literal>.
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <literal>fetchgit</literal>
+   </term>
+   <listitem>
+    <para>
+     Used with Git. Expects <literal>url</literal> to a Git repo,
+     <literal>rev</literal>, and <literal>sha256</literal>.
+     <literal>rev</literal> in this case can be full the git commit id (SHA1
+     hash) or a tag name like <literal>refs/tags/v1.0</literal>.
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <literal>fetchfossil</literal>
+   </term>
+   <listitem>
+    <para>
+     Used with Fossil. Expects <literal>url</literal> to a Fossil archive,
+     <literal>rev</literal>, and <literal>sha256</literal>.
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <literal>fetchcvs</literal>
+   </term>
+   <listitem>
+    <para>
+     Used with CVS. Expects <literal>cvsRoot</literal>, <literal>tag</literal>,
+     and <literal>sha256</literal>.
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <literal>fetchhg</literal>
+   </term>
+   <listitem>
+    <para>
+     Used with Mercurial. Expects <literal>url</literal>,
+     <literal>rev</literal>, and <literal>sha256</literal>.
+    </para>
+   </listitem>
+  </varlistentry>
  </variablelist>
 
  <para>
-   A number of fetcher functions wrap part of
-   <function>fetchurl</function> and <function>fetchzip</function>.
-   They are mainly convenience functions intended for commonly used
-   destinations of source code in Nixpkgs. These wrapper fetchers are
-   listed below.
+  A number of fetcher functions wrap part of <function>fetchurl</function> and
+  <function>fetchzip</function>. They are mainly convenience functions intended
+  for commonly used destinations of source code in Nixpkgs. These wrapper
+  fetchers are listed below.
  </para>
 
  <variablelist>
-   <varlistentry>
-     <term>
-      <literal>fetchFromGitHub</literal>
-     </term>
-     <listitem>
-      <para>
-        <function>fetchFromGitHub</function> expects four arguments.
-        <literal>owner</literal> is a string corresponding to the
-        GitHub user or organization that controls this repository.
-        <literal>repo</literal> corresponds to the name of the
-        software repository. These are located at the top of every
-        GitHub HTML page as
-        <literal>owner</literal>/<literal>repo</literal>.
-        <literal>rev</literal> corresponds to the Git commit hash or
-        tag (e.g <literal>v1.0</literal>) that will be downloaded from
-        Git. Finally, <literal>sha256</literal> corresponds to the
-        hash of the extracted directory. Again, other hash algorithms
-        are also available but <literal>sha256</literal> is currently
-        preferred.
-      </para>
-     </listitem>
-   </varlistentry>
-   <varlistentry>
-     <term>
-      <literal>fetchFromGitLab</literal>
-     </term>
-     <listitem>
-      <para>
-       This is used with GitLab repositories. The arguments expected
-       are very similar to fetchFromGitHub above.
-      </para>
-     </listitem>
-   </varlistentry>
-   <varlistentry>
-     <term>
-      <literal>fetchFromBitbucket</literal>
-     </term>
-     <listitem>
-      <para>
-       This is used with BitBucket repositories. The arguments expected
-       are very similar to fetchFromGitHub above.
-      </para>
-     </listitem>
-   </varlistentry>
-   <varlistentry>
-     <term>
-      <literal>fetchFromSavannah</literal>
-     </term>
-     <listitem>
-      <para>
-       This is used with Savannah repositories. The arguments expected
-       are very similar to fetchFromGitHub above.
-      </para>
-     </listitem>
-   </varlistentry>
-   <varlistentry>
-     <term>
-      <literal>fetchFromRepoOrCz</literal>
-     </term>
-     <listitem>
-      <para>
-       This is used with repo.or.cz repositories. The arguments
-       expected are very similar to fetchFromGitHub above.
-      </para>
-     </listitem>
-   </varlistentry>
+  <varlistentry>
+   <term>
+    <literal>fetchFromGitHub</literal>
+   </term>
+   <listitem>
+    <para>
+     <function>fetchFromGitHub</function> expects four arguments.
+     <literal>owner</literal> is a string corresponding to the GitHub user or
+     organization that controls this repository. <literal>repo</literal>
+     corresponds to the name of the software repository. These are located at
+     the top of every GitHub HTML page as
+     <literal>owner</literal>/<literal>repo</literal>. <literal>rev</literal>
+     corresponds to the Git commit hash or tag (e.g <literal>v1.0</literal>)
+     that will be downloaded from Git. Finally, <literal>sha256</literal>
+     corresponds to the hash of the extracted directory. Again, other hash
+     algorithms are also available but <literal>sha256</literal> is currently
+     preferred.
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <literal>fetchFromGitLab</literal>
+   </term>
+   <listitem>
+    <para>
+     This is used with GitLab repositories. The arguments expected are very
+     similar to fetchFromGitHub above.
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <literal>fetchFromBitbucket</literal>
+   </term>
+   <listitem>
+    <para>
+     This is used with BitBucket repositories. The arguments expected are very
+     similar to fetchFromGitHub above.
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <literal>fetchFromSavannah</literal>
+   </term>
+   <listitem>
+    <para>
+     This is used with Savannah repositories. The arguments expected are very
+     similar to fetchFromGitHub above.
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <literal>fetchFromRepoOrCz</literal>
+   </term>
+   <listitem>
+    <para>
+     This is used with repo.or.cz repositories. The arguments expected are very
+     similar to fetchFromGitHub above.
+    </para>
+   </listitem>
+  </varlistentry>
  </variablelist>
-
-
 </section>
diff --git a/doc/functions/library.xml b/doc/functions/library.xml
index b01de3c6e413..e6aedaa6efdd 100644
--- a/doc/functions/library.xml
+++ b/doc/functions/library.xml
@@ -13,12 +13,17 @@
 
  <xi:include href="./library/attrsets.xml" />
 
- <!-- These docs are generated via nixdoc. To add another generated
+<!-- These docs are generated via nixdoc. To add another generated
       library function file to this list, the file
       `lib-function-docs.nix` must also be updated. -->
+
  <xi:include href="./library/generated/strings.xml" />
+
  <xi:include href="./library/generated/trivial.xml" />
+
  <xi:include href="./library/generated/lists.xml" />
+
  <xi:include href="./library/generated/debug.xml" />
+
  <xi:include href="./library/generated/options.xml" />
 </section>
diff --git a/doc/functions/nix-gitignore.xml b/doc/functions/nix-gitignore.xml
index 465b38e0bf1d..9011570d1eae 100644
--- a/doc/functions/nix-gitignore.xml
+++ b/doc/functions/nix-gitignore.xml
@@ -14,15 +14,15 @@
   <title>Usage</title>
 
   <para>
-  <literal>pkgs.nix-gitignore</literal> exports a number of functions, but
-  you'll most likely need either <literal>gitignoreSource</literal> or
-  <literal>gitignoreSourcePure</literal>. As their first argument, they both
-  accept either 1. a file with gitignore lines or 2. a string
-  with gitignore lines, or 3. a list of either of the two. They will be
-  concatenated into a single big string.
+   <literal>pkgs.nix-gitignore</literal> exports a number of functions, but
+   you'll most likely need either <literal>gitignoreSource</literal> or
+   <literal>gitignoreSourcePure</literal>. As their first argument, they both
+   accept either 1. a file with gitignore lines or 2. a string with gitignore
+   lines, or 3. a list of either of the two. They will be concatenated into a
+   single big string.
   </para>
 
-  <programlisting><![CDATA[
+<programlisting><![CDATA[
 { pkgs ? import <nixpkgs> {} }:
 
  nix-gitignore.gitignoreSource [] ./source
@@ -40,24 +40,29 @@
   ]]></programlisting>
 
   <para>
-  These functions are derived from the <literal>Filter</literal> functions
-  by setting the first filter argument to <literal>(_: _: true)</literal>:
+   These functions are derived from the <literal>Filter</literal> functions by
+   setting the first filter argument to <literal>(_: _: true)</literal>:
   </para>
 
-  <programlisting><![CDATA[
+<programlisting><![CDATA[
 gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);
 gitignoreSource = gitignoreFilterSource (_: _: true);
   ]]></programlisting>
 
   <para>
-  Those filter functions accept the same arguments the <literal>builtins.filterSource</literal> function would pass to its filters, thus <literal>fn: gitignoreFilterSourcePure fn ""</literal> should be extensionally equivalent to <literal>filterSource</literal>. The file is blacklisted iff it's blacklisted by either your filter or the gitignoreFilter.
+   Those filter functions accept the same arguments the
+   <literal>builtins.filterSource</literal> function would pass to its filters,
+   thus <literal>fn: gitignoreFilterSourcePure fn ""</literal> should be
+   extensionally equivalent to <literal>filterSource</literal>. The file is
+   blacklisted iff it's blacklisted by either your filter or the
+   gitignoreFilter.
   </para>
 
   <para>
-  If you want to make your own filter from scratch, you may use
- </para>
+   If you want to make your own filter from scratch, you may use
+  </para>
 
-  <programlisting><![CDATA[
+<programlisting><![CDATA[
 gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;
   ]]></programlisting>
  </section>
@@ -66,10 +71,11 @@ gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;
   <title>gitignore files in subdirectories</title>
 
   <para>
-  If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function:
- </para>
+   If you wish to use a filter that would search for .gitignore files in
+   subdirectories, just like git does by default, use this function:
+  </para>
 
-  <programlisting><![CDATA[
+<programlisting><![CDATA[
 gitignoreFilterRecursiveSource = filter: patterns: root:
 # OR
 gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true);
diff --git a/doc/functions/prefer-remote-fetch.xml b/doc/functions/prefer-remote-fetch.xml
index 85f08f4eae14..2ccad9218062 100644
--- a/doc/functions/prefer-remote-fetch.xml
+++ b/doc/functions/prefer-remote-fetch.xml
@@ -7,17 +7,15 @@
  <para>
   <function>prefer-remote-fetch</function> is an overlay that download sources
   on remote builder. This is useful when the evaluating machine has a slow
-  upload while the builder can fetch faster directly from the source.
-  To use it, put the following snippet as a new overlay:
-  <programlisting>
+  upload while the builder can fetch faster directly from the source. To use
+  it, put the following snippet as a new overlay:
+<programlisting>
     self: super:
       (super.prefer-remote-fetch self super)
   </programlisting>
-
-  A full configuration example for that sets the overlay up for your own account,
-  could look like this
-
-  <programlisting>
+  A full configuration example for that sets the overlay up for your own
+  account, could look like this
+<programlisting>
     $ mkdir ~/.config/nixpkgs/overlays/
     $ cat &gt; ~/.config/nixpkgs/overlays/prefer-remote-fetch.nix &lt;&lt;EOF
       self: super: super.prefer-remote-fetch self super
diff --git a/doc/functions/trivial-builders.xml b/doc/functions/trivial-builders.xml
index 92a07aedb5b9..1fd92ecfe262 100644
--- a/doc/functions/trivial-builders.xml
+++ b/doc/functions/trivial-builders.xml
@@ -5,12 +5,11 @@
  <title>Trivial builders</title>
 
  <para>
-   Nixpkgs provides a couple of functions that help with building
-   derivations. The most important one,
-   <function>stdenv.mkDerivation</function>, has already been
-   documented above. The following functions wrap
-   <function>stdenv.mkDerivation</function>, making it easier to use
-   in certain cases.
+  Nixpkgs provides a couple of functions that help with building derivations.
+  The most important one, <function>stdenv.mkDerivation</function>, has already
+  been documented above. The following functions wrap
+  <function>stdenv.mkDerivation</function>, making it easier to use in certain
+  cases.
  </para>
 
  <variablelist>
@@ -19,26 +18,23 @@
     <literal>runCommand</literal>
    </term>
    <listitem>
-     <para>
-       This takes three arguments, <literal>name</literal>,
-       <literal>env</literal>, and <literal>buildCommand</literal>.
-       <literal>name</literal> is just the name that Nix will append
-       to the store path in the same way that
-       <literal>stdenv.mkDerivation</literal> uses its
-       <literal>name</literal> attribute. <literal>env</literal> is an
-       attribute set specifying environment variables that will be set
-       for this derivation. These attributes are then passed to the
-       wrapped <literal>stdenv.mkDerivation</literal>.
-       <literal>buildCommand</literal> specifies the commands that
-       will be run to create this derivation. Note that you will need
-       to create <literal>$out</literal> for Nix to register the
-       command as successful.
-     </para>
-     <para>
-       An example of using <literal>runCommand</literal> is provided
-       below.
-     </para>
-     <programlisting>
+    <para>
+     This takes three arguments, <literal>name</literal>,
+     <literal>env</literal>, and <literal>buildCommand</literal>.
+     <literal>name</literal> is just the name that Nix will append to the store
+     path in the same way that <literal>stdenv.mkDerivation</literal> uses its
+     <literal>name</literal> attribute. <literal>env</literal> is an attribute
+     set specifying environment variables that will be set for this derivation.
+     These attributes are then passed to the wrapped
+     <literal>stdenv.mkDerivation</literal>. <literal>buildCommand</literal>
+     specifies the commands that will be run to create this derivation. Note
+     that you will need to create <literal>$out</literal> for Nix to register
+     the command as successful.
+    </para>
+    <para>
+     An example of using <literal>runCommand</literal> is provided below.
+    </para>
+<programlisting>
        (import &lt;nixpkgs&gt; {}).runCommand "my-example" {} ''
          echo My example command is running
 
@@ -65,41 +61,35 @@
     <literal>runCommandCC</literal>
    </term>
    <listitem>
-     <para>
-       This works just like <literal>runCommand</literal>. The only
-       difference is that it also provides a C compiler in
-       <literal>buildCommand</literal>’s environment. To minimize your
-       dependencies, you should only use this if you are sure you will
-       need a C compiler as part of running your command.
+    <para>
+     This works just like <literal>runCommand</literal>. The only difference is
+     that it also provides a C compiler in <literal>buildCommand</literal>’s
+     environment. To minimize your dependencies, you should only use this if
+     you are sure you will need a C compiler as part of running your command.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
-    <literal>writeTextFile</literal>, <literal>writeText</literal>,
-    <literal>writeTextDir</literal>, <literal>writeScript</literal>,
-    <literal>writeScriptBin</literal>
+    <literal>writeTextFile</literal>, <literal>writeText</literal>, <literal>writeTextDir</literal>, <literal>writeScript</literal>, <literal>writeScriptBin</literal>
    </term>
    <listitem>
-     <para>
-       These functions write <literal>text</literal> to the Nix store.
-       This is useful for creating scripts from Nix expressions.
-       <literal>writeTextFile</literal> takes an attribute set and
-       expects two arguments, <literal>name</literal> and
-       <literal>text</literal>. <literal>name</literal> corresponds to
-       the name used in the Nix store path. <literal>text</literal>
-       will be the contents of the file. You can also set
-       <literal>executable</literal> to true to make this file have
-       the executable bit set.
-     </para>
-     <para>
-       Many more commands wrap <literal>writeTextFile</literal>
-       including <literal>writeText</literal>,
-       <literal>writeTextDir</lit