doc: format the documentation (#57102)

1 files changed, 290 insertions, 280 deletions

diff --git a/doc/stdenv.xml b/doc/stdenv.xml
index 81bd4556193..68a3282d7d6 100644
--- a/doc/stdenv.xml
+++ b/doc/stdenv.xml
@@ -228,18 +228,17 @@ genericBuild
   </para>
 
   <para>
-   The extension of <envar>PATH</envar> with dependencies, alluded to
-   above, proceeds according to the relative platforms alone. The
-   process is carried out only for dependencies whose host platform
-   matches the new derivation's build platform i.e. dependencies which
-   run on the platform where the new derivation will be built.
+   The extension of <envar>PATH</envar> with dependencies, alluded to above,
+   proceeds according to the relative platforms alone. The process is carried
+   out only for dependencies whose host platform matches the new derivation's
+   build platform i.e. dependencies which run on the platform where the new
+   derivation will be built.
    <footnote xml:id="footnote-stdenv-native-dependencies-in-path">
     <para>
-     Currently, this means for native builds all dependencies are put
-     on the <envar>PATH</envar>. But in the future that may not be the
-     case for sake of matching cross: the platforms would be assumed
-     to be unique for native and cross builds alike, so only the
-     <varname>depsBuild*</varname> and
+     Currently, this means for native builds all dependencies are put on the
+     <envar>PATH</envar>. But in the future that may not be the case for sake
+     of matching cross: the platforms would be assumed to be unique for native
+     and cross builds alike, so only the <varname>depsBuild*</varname> and
      <varname>nativeBuildInputs</varname> would be added to the
      <envar>PATH</envar>.
     </para>
@@ -252,9 +251,10 @@ genericBuild
   <para>
    The dependency is propagated when it forces some of its other-transitive
    (non-immediate) downstream dependencies to also take it on as an immediate
-   dependency. Nix itself already takes a package's transitive dependencies into
-   account, but this propagation ensures nixpkgs-specific infrastructure like
-   setup hooks (mentioned above) also are run as if the propagated dependency.
+   dependency. Nix itself already takes a package's transitive dependencies
+   into account, but this propagation ensures nixpkgs-specific infrastructure
+   like setup hooks (mentioned above) also are run as if the propagated
+   dependency.
   </para>
 
   <para>
@@ -270,9 +270,9 @@ genericBuild
    described by the current dependency's platform offsets. This results in sort
    a transitive closure of the dependency relation, with the offsets being
    approximately summed when two dependency links are combined. We also prune
-   transitive dependencies whose combined offsets go out-of-bounds, which can be
-   viewed as a filter over that transitive closure removing dependencies that
-   are blatantly absurd.
+   transitive dependencies whose combined offsets go out-of-bounds, which can
+   be viewed as a filter over that transitive closure removing dependencies
+   that are blatantly absurd.
   </para>
 
   <para>
@@ -287,8 +287,8 @@ genericBuild
      propagation logic.
     </para>
    </footnote>
-   They're confusing in very different ways so... hopefully if something doesn't
-   make sense in one presentation, it will in the other!
+   They're confusing in very different ways so... hopefully if something
+   doesn't make sense in one presentation, it will in the other!
 <programlisting>
 let mapOffset(h, t, i) = i + (if i &lt;= 0 then h else t - 1)
 
@@ -324,31 +324,31 @@ let f(h, h + 1, i) = i + (if i &lt;= 0 then h else (h + 1) - 1)
 let f(h, h + 1, i) = i + (if i &lt;= 0 then h else h)
 let f(h, h + 1, i) = i + h
   </programlisting>
-   This is where "sum-like" comes in from above: We can just sum all of the host
-   offsets to get the host offset of the transitive dependency. The target
-   offset is the transitive dependency is simply the host offset + 1, just as it
-   was with the dependencies composed to make this transitive one; it can be
+   This is where "sum-like" comes in from above: We can just sum all of the
+   host offsets to get the host offset of the transitive dependency. The target
+   offset is the transitive dependency is simply the host offset + 1, just as
+   it was with the dependencies composed to make this transitive one; it can be
    ignored as it doesn't add any new information.
   </para>
 
   <para>
-   Because of the bounds checks, the uncommon cases are <literal>h = t</literal>
-   and <literal>h + 2 = t</literal>. In the former case, the motivation for
-   <function>mapOffset</function> is that since its host and target platforms
-   are the same, no transitive dependency of it should be able to "discover" an
-   offset greater than its reduced target offsets.
+   Because of the bounds checks, the uncommon cases are <literal>h =
+   t</literal> and <literal>h + 2 = t</literal>. In the former case, the
+   motivation for <function>mapOffset</function> is that since its host and
+   target platforms are the same, no transitive dependency of it should be able
+   to "discover" an offset greater than its reduced target offsets.
    <function>mapOffset</function> effectively "squashes" all its transitive
    dependencies' offsets so that none will ever be greater than the target
    offset of the original <literal>h = t</literal> package. In the other case,
-   <literal>h + 1</literal> is skipped over between the host and target offsets.
-   Instead of squashing the offsets, we need to "rip" them apart so no
+   <literal>h + 1</literal> is skipped over between the host and target
+   offsets. Instead of squashing the offsets, we need to "rip" them apart so no
    transitive dependencies' offset is that one.
   </para>
 
   <para>
-   Overall, the unifying theme here is that propagation shouldn't be introducing
-   transitive dependencies involving platforms the depending package is unaware
-   of. The offset bounds checking and definition of
+   Overall, the unifying theme here is that propagation shouldn't be
+   introducing transitive dependencies involving platforms the depending
+   package is unaware of. The offset bounds checking and definition of
    <function>mapOffset</function> together ensure that this is the case.
    Discovering a new offset is discovering a new platform, and since those
    platforms weren't in the derivation "spec" of the needing package, they
@@ -381,8 +381,8 @@ let f(h, h + 1, i) = i + h
       Since these packages are able to be run at build-time, they are always
       added to the <envar>PATH</envar>, as described above. But since these
       packages are only guaranteed to be able to run then, they shouldn't
-      persist as run-time dependencies. This isn't currently enforced, but could
-      be in the future.
+      persist as run-time dependencies. This isn't currently enforced, but
+      could be in the future.
      </para>
     </listitem>
    </varlistentry>
@@ -396,10 +396,10 @@ let f(h, h + 1, i) = i + h
       platform, and target platform is the new derivation's host platform. This
       means a <literal>-1</literal> host offset and <literal>0</literal> target
       offset from the new derivation's platforms. These are programs and
-      libraries used at build-time that, if they are a compiler or similar tool,
-      produce code to run at run-time—i.e. tools used to build the new
-      derivation. If the dependency doesn't care about the target platform (i.e.
-      isn't a compiler or similar tool), put it here, rather than in
+      libraries used at build-time that, if they are a compiler or similar
+      tool, produce code to run at run-time—i.e. tools used to build the new
+      derivation. If the dependency doesn't care about the target platform
+      (i.e. isn't a compiler or similar tool), put it here, rather than in
       <varname>depsBuildBuild</varname> or <varname>depsBuildTarget</varname>.
       This could be called <varname>depsBuildHost</varname> but
       <varname>nativeBuildInputs</varname> is used for historical continuity.
@@ -407,8 +407,9 @@ let f(h, h + 1, i) = i + h
      <para>
       Since these packages are able to be run at build-time, they are added to
       the <envar>PATH</envar>, as described above. But since these packages are
-      only guaranteed to be able to run then, they shouldn't persist as run-time
-      dependencies. This isn't currently enforced, but could be in the future.
+      only guaranteed to be able to run then, they shouldn't persist as
+      run-time dependencies. This isn't currently enforced, but could be in the
+      future.
      </para>
     </listitem>
    </varlistentry>
@@ -421,33 +422,36 @@ let f(h, h + 1, i) = i + h
       A list of dependencies whose host platform is the new derivation's build
       platform, and target platform is the new derivation's target platform.
       This means a <literal>-1</literal> host offset and <literal>1</literal>
-      target offset from the new derivation's platforms. These are programs used
-      at build time that produce code to run with code produced by the depending
-      package. Most commonly, these are tools used to build the runtime or
-      standard library that the currently-being-built compiler will inject into
-      any code it compiles. In many cases, the currently-being-built-compiler is
-      itself employed for that task, but when that compiler won't run (i.e. its
-      build and host platform differ) this is not possible. Other times, the
-      compiler relies on some other tool, like binutils, that is always built
-      separately so that the dependency is unconditional.
+      target offset from the new derivation's platforms. These are programs
+      used at build time that produce code to run with code produced by the
+      depending package. Most commonly, these are tools used to build the
+      runtime or standard library that the currently-being-built compiler will
+      inject into any code it compiles. In many cases, the
+      currently-being-built-compiler is itself employed for that task, but when
+      that compiler won't run (i.e. its build and host platform differ) this is
+      not possible. Other times, the compiler relies on some other tool, like
+      binutils, that is always built separately so that the dependency is
+      unconditional.
      </para>
      <para>
       This is a somewhat confusing concept to wrap one’s head around, and for
       good reason. As the only dependency type where the platform offsets are
       not adjacent integers, it requires thinking of a bootstrapping stage
-      <emphasis>two</emphasis> away from the current one. It and its use-case go
-      hand in hand and are both considered poor form: try to not need this sort
-      of dependency, and try to avoid building standard libraries and runtimes
-      in the same derivation as the compiler produces code using them. Instead
-      strive to build those like a normal library, using the newly-built
-      compiler just as a normal library would. In short, do not use this
-      attribute unless you are packaging a compiler and are sure it is needed.
+      <emphasis>two</emphasis> away from the current one. It and its use-case
+      go hand in hand and are both considered poor form: try to not need this
+      sort of dependency, and try to avoid building standard libraries and
+      runtimes in the same derivation as the compiler produces code using them.
+      Instead strive to build those like a normal library, using the
+      newly-built compiler just as a normal library would. In short, do not use
+      this attribute unless you are packaging a compiler and are sure it is
+      needed.
      </para>
      <para>
       Since these packages are able to run at build time, they are added to the
-      <envar>PATH</envar>, as described above. But since these packages are only
-      guaranteed to be able to run then, they shouldn't persist as run-time
-      dependencies. This isn't currently enforced, but could be in the future.
+      <envar>PATH</envar>, as described above. But since these packages are
+      only guaranteed to be able to run then, they shouldn't persist as
+      run-time dependencies. This isn't currently enforced, but could be in the
+      future.
      </para>
     </listitem>
    </varlistentry>
@@ -462,11 +466,11 @@ let f(h, h + 1, i) = i + h
       and <literal>0</literal> target offset from the new derivation's host
       platform. These are packages used at run-time to generate code also used
       at run-time. In practice, this would usually be tools used by compilers
-      for macros or a metaprogramming system, or libraries used by the macros or
-      metaprogramming code itself. It's always preferable to use a
-      <varname>depsBuildBuild</varname> dependency in the derivation being built
-      over a <varname>depsHostHost</varname> on the tool doing the building for
-      this purpose.
+      for macros or a metaprogramming system, or libraries used by the macros
+      or metaprogramming code itself. It's always preferable to use a
+      <varname>depsBuildBuild</varname> dependency in the derivation being
+      built over a <varname>depsHostHost</varname> on the tool doing the
+      building for this purpose.
      </para>
     </listitem>
    </varlistentry>
@@ -481,8 +485,8 @@ let f(h, h + 1, i) = i + h
       <literal>1</literal> target offset from the new derivation's host
       platform. This would be called <varname>depsHostTarget</varname> but for
       historical continuity. If the dependency doesn't care about the target
-      platform (i.e. isn't a compiler or similar tool), put it here, rather than
-      in <varname>depsBuildBuild</varname>.
+      platform (i.e. isn't a compiler or similar tool), put it here, rather
+      than in <varname>depsBuildBuild</varname>.
      </para>
      <para>
       These are often programs and libraries used by the new derivation at
@@ -664,10 +668,11 @@ passthru = {
       <literal>hello.baz.value1</literal>. We don't specify any usage or schema
       of <literal>passthru</literal> - it is meant for values that would be
       useful outside the derivation in other parts of a Nix expression (e.g. in
-      other derivations). An example would be to convey some specific dependency
-      of your derivation which contains a program with plugins support. Later,
-      others who make derivations with plugins can use passed-through dependency
-      to ensure that their plugin would be binary-compatible with built program.
+      other derivations). An example would be to convey some specific
+      dependency of your derivation which contains a program with plugins
+      support. Later, others who make derivations with plugins can use
+      passed-through dependency to ensure that their plugin would be
+      binary-compatible with built program.
      </para>
     </listitem>
    </varlistentry>
@@ -677,9 +682,9 @@ passthru = {
     </term>
     <listitem>
      <para>
-      A script to be run by <filename>maintainers/scripts/update.nix</filename> when
-      the package is matched. It needs to be an executable file, either on the file
-      system:
+      A script to be run by <filename>maintainers/scripts/update.nix</filename>
+      when the package is matched. It needs to be an executable file, either on
+      the file system:
 <programlisting>
 passthru.updateScript = ./update.sh;
 </programlisting>
@@ -695,16 +700,24 @@ passthru.updateScript = writeScript "update-zoom-us" ''
   update-source-version zoom-us "$version"
 '';
 </programlisting>
-      The attribute can also contain a list, a script followed by arguments to be passed to it:
+      The attribute can also contain a list, a script followed by arguments to
+      be passed to it:
 <programlisting>
 passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ];
 </programlisting>
-      Note that the update scripts will be run in parallel by default; you should avoid running <command>git commit</command> or any other commands that cannot handle that.
+      Note that the update scripts will be run in parallel by default; you
+      should avoid running <command>git commit</command> or any other commands
+      that cannot handle that.
      </para>
-
      <para>
       For information about how to run the updates, execute
-      <cmdsynopsis><command>nix-shell</command> <arg>maintainers/scripts/update.nix</arg></cmdsynopsis>.
+      <cmdsynopsis>
+       <command>nix-shell</command> 
+       <arg>
+        maintainers/scripts/update.nix
+       </arg>
+      </cmdsynopsis>
+      .
      </para>
     </listitem>
    </varlistentry>
@@ -1178,8 +1191,8 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
        By default, when cross compiling, the configure script has
        <option>--build=...</option> and <option>--host=...</option> passed.
        Packages can instead pass <literal>[ "build" "host" "target" ]</literal>
-       or a subset to control exactly which platform flags are passed. Compilers
-       and other tools can use this to also pass the target platform.
+       or a subset to control exactly which platform flags are passed.
+       Compilers and other tools can use this to also pass the target platform.
        <footnote xml:id="footnote-stdenv-build-time-guessing-impurity">
         <para>
          Eventually these will be passed building natively as well, to improve
@@ -1694,10 +1707,11 @@ installTargets = "install-bin install-doc";</programlisting>
      </term>
      <listitem>
       <para>
-       A package can export a <link linkend="ssec-setup-hooks">setup hook</link>
-       by setting this variable. The setup hook, if defined, is copied to
-       <filename>$out/nix-support/setup-hook</filename>. Environment variables
-       are then substituted in it using <function
+       A package can export a <link linkend="ssec-setup-hooks">setup
+       hook</link> by setting this variable. The setup hook, if defined, is
+       copied to <filename>$out/nix-support/setup-hook</filename>. Environment
+       variables are then substituted in it using
+       <function
        linkend="fun-substituteAll">substituteAll</function>.
       </para>
      </listitem>
@@ -1812,8 +1826,8 @@ set debug-file-directory ~/.nix-profile/lib/debug
      <listitem>
       <para>
        A list of dependencies used by the phase. This gets included in
-       <varname>nativeBuildInputs</varname> when <varname>doInstallCheck</varname> is
-       set.
+       <varname>nativeBuildInputs</varname> when
+       <varname>doInstallCheck</varname> is set.
       </para>
      </listitem>
     </varlistentry>
@@ -2160,10 +2174,11 @@ someVar=$(stripHash $name)
    dependency derivation is already built just the same—depending is just
    needing something to exist, and needing is idempotent. However, a dependency
    specified twice will have its setup hook run twice, and that could easily
-   change the build environment (though a well-written setup hook will therefore
-   strive to be idempotent so this is in fact not observable). More broadly,
-   setup hooks are anti-modular in that multiple dependencies, whether the same
-   or different, should not interfere and yet their setup hooks may well do so.
+   change the build environment (though a well-written setup hook will
+   therefore strive to be idempotent so this is in fact not observable). More
+   broadly, setup hooks are anti-modular in that multiple dependencies, whether
+   the same or different, should not interfere and yet their setup hooks may
+   well do so.
   </para>
 
   <para>
@@ -2185,11 +2200,12 @@ someVar=$(stripHash $name)
    Returning to the C compiler wrapper example, if the wrapper itself is an
    <literal>n</literal> dependency, then it only wants to accumulate flags from
    <literal>n + 1</literal> dependencies, as only those ones match the
-   compiler's target platform. The <envar>hostOffset</envar> variable is defined
-   with the current dependency's host offset <envar>targetOffset</envar> with
-   its target offset, before its setup hook is sourced. Additionally, since most
-   environment hooks don't care about the target platform, that means the setup
-   hook can append to the right bash array by doing something like
+   compiler's target platform. The <envar>hostOffset</envar> variable is
+   defined with the current dependency's host offset
+   <envar>targetOffset</envar> with its target offset, before its setup hook is
+   sourced. Additionally, since most environment hooks don't care about the
+   target platform, that means the setup hook can append to the right bash
+   array by doing something like
 <programlisting language="bash">
 addEnvHooks "$hostOffset" myBashFunction
   </programlisting>
@@ -2204,24 +2220,22 @@ addEnvHooks "$hostOffset" myBashFunction
   </para>
 
   <para>
-    First, let’s cover some setup hooks that are part of Nixpkgs
-    default stdenv. This means that they are run for every package
-    built using <function>stdenv.mkDerivation</function>. Some of
-    these are platform specific, so they may run on Linux but not
-    Darwin or vice-versa.
-    <variablelist>
+   First, let’s cover some setup hooks that are part of Nixpkgs default
+   stdenv. This means that they are run for every package built using
+   <function>stdenv.mkDerivation</function>. Some of these are platform
+   specific, so they may run on Linux but not Darwin or vice-versa.
+   <variablelist>
     <varlistentry>
      <term>
       <literal>move-docs.sh</literal>
      </term>
      <listitem>
-       <para>
+      <para>
        This setup hook moves any installed documentation to the
-       <literal>/share</literal> subdirectory directory. This includes
-       the man, doc and info directories. This is needed for legacy
-       programs that do not know how to use the
-       <literal>share</literal> subdirectory.
-       </para>
+       <literal>/share</literal> subdirectory directory. This includes the man,
+       doc and info directories. This is needed for legacy programs that do not
+       know how to use the <literal>share</literal> subdirectory.
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -2229,11 +2243,11 @@ addEnvHooks "$hostOffset" myBashFunction
       <literal>compress-man-pages.sh</literal>
      </term>
      <listitem>
-       <para>
-       This setup hook compresses any man pages that have been
-       installed. The compression is done using the gzip program. This
-       helps to reduce the installed size of packages.
-       </para>
+      <para>
+       This setup hook compresses any man pages that have been installed. The
+       compression is done using the gzip program. This helps to reduce the
+       installed size of packages.
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -2241,12 +2255,11 @@ addEnvHooks "$hostOffset" myBashFunction
       <literal>strip.sh</literal>
      </term>
      <listitem>
-       <para>
-       This runs the strip command on installed binaries and
-       libraries. This removes unnecessary information like debug
-       symbols when they are not needed. This also helps to reduce the
-       installed size of packages.
-       </para>
+      <para>
+       This runs the strip command on installed binaries and libraries. This
+       removes unnecessary information like debug symbols when they are not
+       needed. This also helps to reduce the installed size of packages.
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -2254,15 +2267,14 @@ addEnvHooks "$hostOffset" myBashFunction
       <literal>patch-shebangs.sh</literal>
      </term>
      <listitem>
-       <para>
-       This setup hook patches installed scripts to use the full path
-       to the shebang interpreter. A shebang interpreter is the first
-       commented line of a script telling the operating system which
-       program will run the script (e.g <literal>#!/bin/bash</literal>). In
-       Nix, we want an exact path to that interpreter to be used. This
-       often replaces <literal>/bin/sh</literal> with a path in the
-       Nix store.
-       </para>
+      <para>
+       This setup hook patches installed scripts to use the full path to the
+       shebang interpreter. A shebang interpreter is the first commented line
+       of a script telling the operating system which program will run the
+       script (e.g <literal>#!/bin/bash</literal>). In Nix, we want an exact
+       path to that interpreter to be used. This often replaces
+       <literal>/bin/sh</literal> with a path in the Nix store.
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -2270,12 +2282,12 @@ addEnvHooks "$hostOffset" myBashFunction
       <literal>audit-tmpdir.sh</literal>
      </term>
      <listitem>
-       <para>
-       This verifies that no references are left from the install
-       binaries to the directory used to build those binaries. This
-       ensures that the binaries do not need things outside the Nix
-       store. This is currently supported in Linux only.
-       </para>
+      <para>
+       This verifies that no references are left from the install binaries to
+       the directory used to build those binaries. This ensures that the
+       binaries do not need things outside the Nix store. This is currently
+       supported in Linux only.
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -2283,14 +2295,14 @@ addEnvHooks "$hostOffset" myBashFunction
       <literal>multiple-outputs.sh</literal>
      </term>
      <listitem>
-       <para>
-       This setup hook adds configure flags that tell packages to
-       install files into any one of the proper outputs listed in
-       <literal>outputs</literal>. This behavior can be turned off by setting
+      <para>
+       This setup hook adds configure flags that tell packages to install files
+       into any one of the proper outputs listed in <literal>outputs</literal>.
+       This behavior can be turned off by setting
        <literal>setOutputFlags</literal> to false in the derivation
-       environment. See <xref linkend="chap-multiple-output"/> for
-       more information.
-       </para>
+       environment. See <xref linkend="chap-multiple-output"/> for more
+       information.
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -2298,11 +2310,11 @@ addEnvHooks "$hostOffset" myBashFunction
       <literal>move-sbin.sh</literal>
      </term>
      <listitem>
-       <para>
-       This setup hook moves any binaries installed in the sbin
-       subdirectory into bin. In addition, a link is provided from
-       sbin to bin for compatibility.
-       </para>
+      <para>
+       This setup hook moves any binaries installed in the sbin subdirectory
+       into bin. In addition, a link is provided from sbin to bin for
+       compatibility.
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -2310,11 +2322,11 @@ addEnvHooks "$hostOffset" myBashFunction
       <literal>move-lib64.sh</literal>
      </term>
      <listitem>
-       <para>
-       This setup hook moves any libraries installed in the lib64
-       subdirectory into lib. In addition, a link is provided from
-       lib64 to lib for compatibility.
-       </para>
+      <para>
+       This setup hook moves any libraries installed in the lib64 subdirectory
+       into lib. In addition, a link is provided from lib64 to lib for
+       compatibility.
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -2322,10 +2334,10 @@ addEnvHooks "$hostOffset" myBashFunction
       <literal>set-source-date-epoch-to-latest.sh</literal>
      </term>
      <listitem>
-       <para>
-       This sets <literal>SOURCE_DATE_EPOCH</literal> to the
-       modification time of the most recent file.
-       </para>
+      <para>
+       This sets <literal>SOURCE_DATE_EPOCH</literal> to the modification time
+       of the most recent file.
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -2335,19 +2347,19 @@ addEnvHooks "$hostOffset" myBashFunction
      <listitem>
       <para>
        The Bintools Wrapper wraps the binary utilities for a bunch of
-       miscellaneous purposes. These are GNU Binutils when targetting Linux, and
-       a mix of cctools and GNU binutils for Darwin. [The "Bintools" name is
-       supposed to be a compromise between "Binutils" and "cctools" not denoting
-       any specific implementation.] Specifically, the underlying bintools
-       package, and a C standard library (glibc or Darwin's libSystem, just for
-       the dynamic loader) are all fed in, and dependency finding, hardening
-       (see below), and purity checks for each are handled by the Bintools
-       Wrapper. Packages typically depend on CC Wrapper, which in turn (at run
-       time) depends on the Bintools Wrapper.
-      </para>
-      <para>
-       The Bintools Wrapper was only just recently split off from CC Wrapper, so
-       the division of labor is still being worked out. For example, it
+       miscellaneous purposes. These are GNU Binutils when targetting Linux,
+       and a mix of cctools and GNU binutils for Darwin. [The "Bintools" name
+       is supposed to be a compromise between "Binutils" and "cctools" not
+       denoting any specific implementation.] Specifically, the underlying
+       bintools package, and a C standard library (glibc or Darwin's libSystem,
+       just for the dynamic loader) are all fed in, and dependency finding,
+       hardening (see below), and purity checks for each are handled by the
+       Bintools Wrapper. Packages typically depend on CC Wrapper, which in turn
+       (at run time) depends on the Bintools Wrapper.
+      </para>
+      <para>
+       The Bintools Wrapper was only just recently split off from CC Wrapper,
+       so the division of labor is still being worked out. For example, it
        shouldn't care about about the C standard library, but just take a
        derivation with the dynamic loader (which happens to be the glibc on
        linux). Dependency finding however is a task both wrappers will continue
@@ -2357,11 +2369,12 @@ addEnvHooks "$hostOffset" myBashFunction
        <varname>nativeBuildInputs</varname>) in environment variables. The
        Bintools Wrapper's setup hook causes any <filename>lib</filename> and
        <filename>lib64</filename> subdirectories to be added to
-       <envar>NIX_LDFLAGS</envar>. Since the CC Wrapper and the Bintools Wrapper
-       use the same strategy, most of the Bintools Wrapper code is sparsely
-       commented and refers to the CC Wrapper. But the CC Wrapper's code, by
-       contrast, has quite lengthy comments. The Bintools Wrapper merely cites
-       those, rather than repeating them, to avoid falling out of sync.
+       <envar>NIX_LDFLAGS</envar>. Since the CC Wrapper and the Bintools
+       Wrapper use the same strategy, most of the Bintools Wrapper code is
+       sparsely commented and refers to the CC Wrapper. But the CC Wrapper's
+       code, by contrast, has quite lengthy comments. The Bintools Wrapper
+       merely cites those, rather than repeating them, to avoid falling out of
+       sync.
       </para>
       <para>
        A final task of the setup hook is defining a number of standard
@@ -2370,8 +2383,8 @@ addEnvHooks "$hostOffset" myBashFunction
        under the assumption that the Bintools Wrapper's binaries will be on the
        path. Firstly, this helps poorly-written packages, e.g. ones that look
        for just <command>gcc</command> when <envar>CC</envar> isn't defined yet
-       <command>clang</command> is to be used. Secondly, this helps packages not
-       get confused when cross-compiling, in which case multiple Bintools
+       <command>clang</command> is to be used. Secondly, this helps packages
+       not get confused when cross-compiling, in which case multiple Bintools
        Wrappers may simultaneously be in use.
        <footnote xml:id="footnote-stdenv-per-platform-wrapper">
         <para>
@@ -2387,16 +2400,16 @@ addEnvHooks "$hostOffset" myBashFunction
        Wrappers, properly disambiguating them.
       </para>
       <para>
-       A problem with this final task is that the Bintools Wrapper is honest and
-       defines <envar>LD</envar> as <command>ld</command>. Most packages,
+       A problem with this final task is that the Bintools Wrapper is honest
+       and defines <envar>LD</envar> as <command>ld</command>. Most packages,
        however, firstly use the C compiler for linking, secondly use
        <envar>LD</envar> anyways, defining it as the C compiler, and thirdly,
-       only so define <envar>LD</envar> when it is undefined as a fallback. This
-       triple-threat means Bintools Wrapper will break those packages, as LD is
-       already defined as the actual linker which the package won't override yet
-       doesn't want to use. The workaround is to define, just for the
-       problematic package, <envar>LD</envar> as the C compiler. A good way to
-       do this would be <command>preConfigure = "LD=$CC"</command>.
+       only so define <envar>LD</envar> when it is undefined as a fallback.
+       This triple-threat means Bintools Wrapper will break those packages, as
+       LD is already defined as the actual linker which the package won't
+       override yet doesn't want to use. The workaround is to define, just for
+       the problematic package, <envar>LD</envar> as the C compiler. A good way
+       to do this would be <command>preConfigure = "LD=$CC"</command>.
       </para>
      </listitem>
     </varlistentry>
@@ -2406,13 +2419,13 @@ addEnvHooks "$hostOffset" myBashFunction
      </term>
      <listitem>
       <para>
-       The CC Wrapper wraps a C toolchain for a bunch of miscellaneous purposes.
-       Specifically, a C compiler (GCC or Clang), wrapped binary tools, and a C
-       standard library (glibc or Darwin's libSystem, just for the dynamic
-       loader) are all fed in, and dependency finding, hardening (see below),
-       and purity checks for each are handled by the CC Wrapper. Packages
-       typically depend on the CC Wrapper, which in turn (at run-time) depends
-       on the Bintools Wrapper.
+       The CC Wrapper wraps a C toolchain for a bunch of miscellaneous
+       purposes. Specifically, a C compiler (GCC or Clang), wrapped binary
+       tools, and a C standard library (glibc or Darwin's libSystem, just for
+       the dynamic loader) are all fed in, and dependency finding, hardening
+       (see below), and purity checks for each are handled by the CC Wrapper.
+       Packages typically depend on the CC Wrapper, which in turn (at run-time)
+       depends on the Bintools Wrapper.
       </para>
       <para>
        Dependency finding is undoubtedly the main task of the CC Wrapper. This
@@ -2434,14 +2447,13 @@ addEnvHooks "$hostOffset" myBashFunction
       </para>
      </listitem>
     </varlistentry>
-    </variablelist>
+   </variablelist>
   </para>
 
   <para>
-   Here are some more packages that provide a setup hook. Since the
-   list of hooks is extensible, this is not an exhaustive list the
-   mechanism is only to be used as a last resort, it might cover most
-   uses.
+   Here are some more packages that provide a setup hook. Since the list of
+   hooks is extensible, this is not an exhaustive list the mechanism is only to
+   be used as a last resort, it might cover most uses.
    <variablelist>
     <varlistentry>
      <term>
@@ -2499,11 +2511,11 @@ addEnvHooks "$hostOffset" myBashFunction
      <listitem>
       <para>
        The <varname>autoreconfHook</varname> derivation adds
-       <varname>autoreconfPhase</varname>, which runs autoreconf, libtoolize and
-       automake, essentially preparing the configure script in autotools-based
-       builds. Most autotools-based packages come with the configure script
-       pre-generated, but this hook is necessary for a few packages and when you
-       need to patch the package’s configure scripts.
+       <varname>autoreconfPhase</varname>, which runs autoreconf, libtoolize
+       and automake, essentially preparing the configure script in
+       autotools-based builds. Most autotools-based packages come with the
+       configure script pre-generated, but this hook is necessary for a few
+       packages and when you need to patch the package’s configure scripts.
       </para>
      </listitem>
     </varlistentry>
@@ -2547,9 +2559,9 @@ addEnvHooks "$hostOffset" myBashFunction
      </term>
      <listitem>
       <para>
-       Exports <envar>GDK_PIXBUF_MODULE_FILE</envar> environment variable to the
-       builder. Add librsvg package to <varname>buildInputs</varname> to get svg
-       support.
+       Exports <envar>GDK_PIXBUF_MODULE_FILE</envar> environment variable to
+       the builder. Add librsvg package to <varname>buildInputs</varname> to
+       get svg support.
       </para>
      </listitem>
     </varlistentry>
@@ -2594,21 +2606,20 @@ addEnvHooks "$hostOffset" myBashFunction
       </para>
       <para>
        This is useful for programs that use <citerefentry>
-        <refentrytitle>dlopen</refentrytitle>
-        <manvolnum>3</manvolnum>
-       </citerefentry> to load libraries at runtime.
+       <refentrytitle>dlopen</refentrytitle>
+       <manvolnum>3</manvolnum> </citerefentry> to load libraries at runtime.
       </para>
       <para>
-        In certain situations you may want to run the main command
-        (<command>autoPatchelf</command>) of the setup hook on a file or a set
-        of directories instead of unconditionally patching all outputs. This
-        can be done by setting the <envar>dontAutoPatchelf</envar> environment
-        variable to a non-empty value.
+       In certain situations you may want to run the main command
+       (<command>autoPatchelf</command>) of the setup hook on a file or a set
+       of directories instead of unconditionally patching all outputs. This can
+       be done by setting the <envar>dontAutoPatchelf</envar> environment
+       variable to a non-empty value.
       </para>
       <para>
-        The <command>autoPatchelf</command> command also recognizes a
-        <parameter class="command">--no-recurse</parameter> command line flag,
-        which prevents it from recursing into subdirectories.
+       The <command>autoPatchelf</command> command also recognizes a
+       <parameter class="command">--no-recurse</parameter> command line flag,
+       which prevents it from recursing into subdirectories.
       </para>
      </listitem>
     </varlistentry>
@@ -2619,22 +2630,22 @@ addEnvHooks "$hostOffset" myBashFunction
      <listitem>
       <para>
        This hook will make a build pause instead of stopping when a failure
-       happens. It prevents nix from cleaning up the build environment immediately and
-       allows the user to attach to a build environment using the
-       <command>cntr</command> command. Upon build error it will print
-       instructions on how to use <command>cntr</command>. Installing
-       cntr and running the command will provide shell access to the build
-       sandbox of failed build. At <filename>/var/lib/cntr</filename> the
-       sandboxed filesystem is mounted. All commands and files of the system are
-       still accessible within the shell. To execute commands from the sandbox
-       use the cntr exec subcommand. Note that <command>cntr</command> also
-       needs to be executed on the machine that is doing the build, which might
-       not be the case when remote builders are enabled.
-       <command>cntr</command> is only supported on Linux-based platforms. To
-       use it first add <literal>cntr</literal> to your
-       <literal>environment.systemPackages</literal> on NixOS or alternatively to
-       the root user on non-NixOS systems. Then in the package that is supposed
-       to be inspected, add <literal>breakpointHook</literal> to
+       happens. It prevents nix from cleaning up the build environment
+       immediately and allows the user to attach to a build environment using
+       the <command>cntr</command> command. Upon build error it will print
+       instructions on how to use <command>cntr</command>. Installing cntr and
+       running the command will provide shell access to the build sandbox of
+       failed build. At <filename>/var/lib/cntr</filename> the sandboxed
+       filesystem is mounted. All commands and files of the system are still
+       accessible within the shell. To execute commands from the sandbox use
+       the cntr exec subcommand. Note that <command>cntr</command> also needs
+       to be executed on the machine that is doing the build, which might not
+       be the case when remote builders are enabled. <command>cntr</command> is
+       only supported on Linux-based platforms. To use it first add
+       <literal>cntr</literal> to your
+       <literal>environment.systemPackages</literal> on NixOS or alternatively
+       to the root user on non-NixOS systems. Then in the package that is
+       supposed to be inspected, add <literal>breakpointHook</literal> to
        <literal>nativeBuildInputs</literal>.
 <programlisting>
          nativeBuildInputs = [ breakpointHook ];
@@ -2649,16 +2660,15 @@ addEnvHooks "$hostOffset" myBashFunction
       libiconv, libintl
      </term>
      <listitem>
-       <para>
-	 A few libraries automatically add to
-	 <literal>NIX_LDFLAGS</literal> their library, making their
-	 symbols automatically available to the linker. This includes
-	 libiconv and libintl (gettext). This is done to provide
-	 compatibility between GNU Linux, where libiconv and libintl
-	 are bundled in, and other systems where that might not be the
-	 case. Sometimes, this behavior is not desired. To disable
-	 this behavior, set <literal>dontAddExtraLibs</literal>.
-       </para>
+      <para>
+       A few libraries automatically add to <literal>NIX_LDFLAGS</literal>
+       their library, making their symbols automatically available to the
+       linker. This includes libiconv and libintl (gettext). This is done to
+       provide compatibility between GNU Linux, where libiconv and libintl are
+       bundled in, and other systems where that might not be the case.
+       Sometimes, this behavior is not desired. To disable this behavior, set
+       <literal>dontAddExtraLibs</literal>.
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -2666,17 +2676,17 @@ addEnvHooks "$hostOffset" myBashFunction
       cmake
      </term>
      <listitem>
-       <para>
-         Overrides the default configure phase to run the CMake command. By
-	 default, we use the Make generator of CMake. In
-         addition, dependencies are added automatically to CMAKE_PREFIX_PATH so
-         that packages are correctly detected by CMake. Some additional flags
-         are passed in to give similar behavior to configure-based packages. You
-         can disable this hook’s behavior by setting configurePhase to a custom
-         value, or by setting dontUseCmakeConfigure. cmakeFlags controls flags
-         passed only to CMake. By default, parallel building is enabled as CMake
-         supports parallel building almost everywhere. When Ninja is also in
-	 use, CMake will detect that and use the ninja generator.
+      <para>
+       Overrides the default configure phase to run the CMake command. By
+       default, we use the Make generator of CMake. In addition, dependencies
+       are added automatically to CMAKE_PREFIX_PATH so that packages are
+       correctly detected by CMake. Some additional flags are passed in to give
+       similar behavior to configure-based packages. You can disable this
+       hook’s behavior by setting configurePhase to a custom value, or by
+       setting dontUseCmakeConfigure. cmakeFlags controls flags passed only to
+       CMake. By default, parallel building is enabled as CMake supports
+       parallel building almost everywhere. When Ninja is also in use, CMake
+       will detect that and use the ninja generator.
       </para>
      </listitem>
     </varlistentry>
@@ -2685,12 +2695,12 @@ addEnvHooks "$hostOffset" myBashFunction
       xcbuildHook
      </term>
      <listitem>
-       <para>
-	 Overrides the build and install phases to run the “xcbuild” command.
-	 This hook is needed when a project only comes with build files for the
-	 XCode build system. You can disable this behavior by setting buildPhase
-	 and configurePhase to a custom value. xcbuildFlags controls flags
-	 passed only to xcbuild.
+      <para>
+       Overrides the build and install phases to run the “xcbuild” command.
+       This hook is needed when a project only comes with build files for the
+       XCode build system. You can disable this behavior by setting buildPhase
+       and configurePhase to a custom value. xcbuildFlags controls flags passed
+       only to xcbuild.
       </para>
      </listitem>
     </varlistentry>
@@ -2699,13 +2709,13 @@ addEnvHooks "$hostOffset" myBashFunction
       meson
      </term>
      <listitem>
-       <para>
-	 Overrides the configure phase to run meson to generate Ninja files. You
-	 can disable this behavior by setting configurePhase to a custom value,
-	 or by setting dontUseMesonConfigure. To run these files, you should
-	 accompany meson with ninja. mesonFlags controls only the flags passed
-	 to meson. By default, parallel building is enabled as Meson supports
-	 parallel building almost everywhere.
+      <para>
+       Overrides the configure phase to run meson to generate Ninja files. You
+       can disable this behavior by setting configurePhase to a custom value,
+       or by setting dontUseMesonConfigure. To run these files, you should
+       accompany meson with ninja. mesonFlags controls only the flags passed to
+       meson. By default, parallel building is enabled as Meson supports
+       parallel building almost everywhere.
       </para>
      </listitem>
     </varlistentry>
@@ -2714,11 +2724,11 @@ addEnvHooks "$hostOffset" myBashFunction
       ninja
      </term>
      <listitem>
-       <para>
-	 Overrides the build, install, and check phase to run ninja instead of
-	 make. You can disable this behavior with the dontUseNinjaBuild,
-	 dontUseNinjaInstall, and dontUseNinjaCheck, respectively. Parallel
-	 building is enabled by default in Ninja.
+      <para>
+       Overrides the build, install, and check phase to run ninja instead of
+       make. You can disable this behavior with the dontUseNinjaBuild,
+       dontUseNinjaInstall, and dontUseNinjaCheck, respectively. Parallel
+       building is enabled by default in Ninja.
       </para>
      </listitem>
     </varlistentry>
@@ -2727,9 +2737,9 @@ addEnvHooks "$hostOffset" myBashFunction
       unzip
      </term>
      <listitem>
-       <para>
-	 This setup hook will allow you to unzip .zip files specified in $src.
-	 There are many similar packages like unrar, undmg, etc.
+      <para>
+       This setup hook will allow you to unzip .zip files specified in $src.
+       There are many similar packages like unrar, undmg, etc.
       </para>
      </listitem>
     </varlistentry>
@@ -2738,11 +2748,11 @@ addEnvHooks "$hostOffset" myBashFunction
       wafHook
      </term>
      <listitem>
-       <para>
-	 Overrides the configure, build, and install phases. This will run the
-	 "waf" script used by many projects. If waf doesn’t exist, it will copy
-	 the version of waf available in Nixpkgs wafFlags can be used to pass
-	 flags to the waf script.
+      <para>
+       Overrides the configure, build, and install phases. This will run the
+       "waf" script used by many projects. If waf doesn’t exist, it will copy
+       the version of waf available in Nixpkgs wafFlags can be used to pass
+       flags to the waf script.
       </para>
      </listitem>
     </varlistentry>
@@ -2751,14 +2761,14 @@ addEnvHooks "$hostOffset" myBashFunction
       scons
      </term>
      <listitem>
-       <para>
-	 Overrides the build, install, and check phases. This uses the scons
-	 build system as a replacement for make. scons does not provide a
-	 configure phase, so everything is managed at build and install time.
+      <para>
+       Overrides the build, install, and check phases. This uses the scons
+       build system as a replacement for make. scons does not provide a
+       configure phase, so everything is managed at build and install time.
       </para>
      </listitem>
     </varlistentry>
-  </variablelist>
+   </variablelist>
   </para>
  </section>
  <section xml:id="sec-purity-in-nixpkgs">