Merge branch 'master' into staging-next

13 files changed, 170 insertions, 663 deletions

diff --git a/doc/languages-frameworks/beam.xml b/doc/languages-frameworks/beam.xml
index dee7f2d74191..65f28d0a2d3b 100644
--- a/doc/languages-frameworks/beam.xml
+++ b/doc/languages-frameworks/beam.xml
@@ -7,12 +7,7 @@
   <title>Introduction</title>
 
   <para>
-   In this document and related Nix expressions, we use the term,
-   <emphasis>BEAM</emphasis>, to describe the environment. BEAM is the name of
-   the Erlang Virtual Machine and, as far as we're concerned, from a packaging
-   perspective, all languages that run on the BEAM are interchangeable. That
-   which varies, like the build system, is transparent to users of any given
-   BEAM package, so we make no distinction.
+   In this document and related Nix expressions, we use the term, <emphasis>BEAM</emphasis>, to describe the environment. BEAM is the name of the Erlang Virtual Machine and, as far as we're concerned, from a packaging perspective, all languages that run on the BEAM are interchangeable. That which varies, like the build system, is transparent to users of any given BEAM package, so we make no distinction.
   </para>
  </section>
 
@@ -20,57 +15,36 @@
   <title>Structure</title>
 
   <para>
-   All BEAM-related expressions are available via the top-level
-   <literal>beam</literal> attribute, which includes:
+   All BEAM-related expressions are available via the top-level <literal>beam</literal> attribute, which includes:
   </para>
 
   <itemizedlist>
    <listitem>
     <para>
-     <literal>interpreters</literal>: a set of compilers running on the BEAM,
-     including multiple Erlang/OTP versions
-     (<literal>beam.interpreters.erlangR19</literal>, etc), Elixir
-     (<literal>beam.interpreters.elixir</literal>) and LFE
-     (<literal>beam.interpreters.lfe</literal>).
+     <literal>interpreters</literal>: a set of compilers running on the BEAM, including multiple Erlang/OTP versions (<literal>beam.interpreters.erlangR19</literal>, etc), Elixir (<literal>beam.interpreters.elixir</literal>) and LFE (<literal>beam.interpreters.lfe</literal>).
     </para>
    </listitem>
    <listitem>
     <para>
-     <literal>packages</literal>: a set of package sets, each compiled with a
-     specific Erlang/OTP version, e.g.
-     <literal>beam.packages.erlangR19</literal>.
+     <literal>packages</literal>: a set of package sets, each compiled with a specific Erlang/OTP version, e.g. <literal>beam.packages.erlangR19</literal>.
     </para>
    </listitem>
   </itemizedlist>
 
   <para>
-   The default Erlang compiler, defined by
-   <literal>beam.interpreters.erlang</literal>, is aliased as
-   <literal>erlang</literal>. The default BEAM package set is defined by
-   <literal>beam.packages.erlang</literal> and aliased at the top level as
-   <literal>beamPackages</literal>.
+   The default Erlang compiler, defined by <literal>beam.interpreters.erlang</literal>, is aliased as <literal>erlang</literal>. The default BEAM package set is defined by <literal>beam.packages.erlang</literal> and aliased at the top level as <literal>beamPackages</literal>.
   </para>
 
   <para>
-   To create a package set built with a custom Erlang version, use the lambda,
-   <literal>beam.packagesWith</literal>, which accepts an Erlang/OTP derivation
-   and produces a package set similar to
-   <literal>beam.packages.erlang</literal>.
+   To create a package set built with a custom Erlang version, use the lambda, <literal>beam.packagesWith</literal>, which accepts an Erlang/OTP derivation and produces a package set similar to <literal>beam.packages.erlang</literal>.
   </para>
 
   <para>
-   Many Erlang/OTP distributions available in
-   <literal>beam.interpreters</literal> have versions with ODBC and/or Java
-   enabled. For example, there's
-   <literal>beam.interpreters.erlangR19_odbc_javac</literal>, which corresponds
-   to <literal>beam.interpreters.erlangR19</literal>.
+   Many Erlang/OTP distributions available in <literal>beam.interpreters</literal> have versions with ODBC and/or Java enabled. For example, there's <literal>beam.interpreters.erlangR19_odbc_javac</literal>, which corresponds to <literal>beam.interpreters.erlangR19</literal>.
   </para>
 
   <para xml:id="erlang-call-package">
-   We also provide the lambda,
-   <literal>beam.packages.erlang.callPackage</literal>, which simplifies
-   writing BEAM package definitions by injecting all packages from
-   <literal>beam.packages.erlang</literal> into the top-level context.
+   We also provide the lambda, <literal>beam.packages.erlang.callPackage</literal>, which simplifies writing BEAM package definitions by injecting all packages from <literal>beam.packages.erlang</literal> into the top-level context.
   </para>
  </section>
 
@@ -81,24 +55,16 @@
    <title>Rebar3</title>
 
    <para>
-    By default, Rebar3 wants to manage its own dependencies. This is perfectly
-    acceptable in the normal, non-Nix setup, but in the Nix world, it is not.
-    To rectify this, we provide two versions of Rebar3:
+    By default, Rebar3 wants to manage its own dependencies. This is perfectly acceptable in the normal, non-Nix setup, but in the Nix world, it is not. To rectify this, we provide two versions of Rebar3:
     <itemizedlist>
      <listitem>
       <para>
-       <literal>rebar3</literal>: patched to remove the ability to download
-       anything. When not running it via <literal>nix-shell</literal> or
-       <literal>nix-build</literal>, it's probably not going to work as
-       desired.
+       <literal>rebar3</literal>: patched to remove the ability to download anything. When not running it via <literal>nix-shell</literal> or <literal>nix-build</literal>, it's probably not going to work as desired.
       </para>
      </listitem>
      <listitem>
       <para>
-       <literal>rebar3-open</literal>: the normal, unmodified Rebar3. It should
-       work exactly as would any other version of Rebar3. Any Erlang package
-       should rely on <literal>rebar3</literal> instead. See
-       <xref
+       <literal>rebar3-open</literal>: the normal, unmodified Rebar3. It should work exactly as would any other version of Rebar3. Any Erlang package should rely on <literal>rebar3</literal> instead. See <xref
             linkend="rebar3-packages"/>.
       </para>
      </listitem>
@@ -110,10 +76,7 @@
    <title>Mix &amp; Erlang.mk</title>
 
    <para>
-    Both Mix and Erlang.mk work exactly as expected. There is a bootstrap
-    process that needs to be run for both, however, which is supported by the
-    <literal>buildMix</literal> and <literal>buildErlangMk</literal>
-    derivations, respectively.
+    Both Mix and Erlang.mk work exactly as expected. There is a bootstrap process that needs to be run for both, however, which is supported by the <literal>buildMix</literal> and <literal>buildErlangMk</literal> derivations, respectively.
    </para>
   </section>
  </section>
@@ -122,13 +85,7 @@
   <title>How to Install BEAM Packages</title>
 
   <para>
-   BEAM packages are not registered at the top level, simply because they are
-   not relevant to the vast majority of Nix users. They are installable using
-   the <literal>beam.packages.erlang</literal> attribute set (aliased as
-   <literal>beamPackages</literal>), which points to packages built by the
-   default Erlang/OTP version in Nixpkgs, as defined by
-   <literal>beam.interpreters.erlang</literal>. To list the available packages
-   in <literal>beamPackages</literal>, use the following command:
+   BEAM packages are not registered at the top level, simply because they are not relevant to the vast majority of Nix users. They are installable using the <literal>beam.packages.erlang</literal> attribute set (aliased as <literal>beamPackages</literal>), which points to packages built by the default Erlang/OTP version in Nixpkgs, as defined by <literal>beam.interpreters.erlang</literal>. To list the available packages in <literal>beamPackages</literal>, use the following command:
   </para>
 
 <screen>
@@ -143,8 +100,7 @@ beamPackages.rebar3-pc  pc-1.1.0
 </screen>
 
   <para>
-   To install any of those packages into your profile, refer to them by their
-   attribute path (first column):
+   To install any of those packages into your profile, refer to them by their attribute path (first column):
   </para>
 
 <screen>
@@ -152,9 +108,7 @@ beamPackages.rebar3-pc  pc-1.1.0
 </screen>
 
   <para>
-   The attribute path of any BEAM package corresponds to the name of that
-   particular package in <link xlink:href="https://hex.pm">Hex</link> or its
-   OTP Application/Release name.
+   The attribute path of any BEAM package corresponds to the name of that particular package in <link xlink:href="https://hex.pm">Hex</link> or its OTP Application/Release name.
   </para>
  </section>
 
@@ -168,13 +122,8 @@ beamPackages.rebar3-pc  pc-1.1.0
     <title>Rebar3 Packages</title>
 
     <para>
-     The Nix function, <literal>buildRebar3</literal>, defined in
-     <literal>beam.packages.erlang.buildRebar3</literal> and aliased at the top
-     level, can be used to build a derivation that understands how to build a
-     Rebar3 project. For example, we can build
-     <link
-        xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link>
-     as follows:
+     The Nix function, <literal>buildRebar3</literal>, defined in <literal>beam.packages.erlang.buildRebar3</literal> and aliased at the top level, can be used to build a derivation that understands how to build a Rebar3 project. For example, we can build <link
+        xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link> as follows:
     </para>
 
 <programlisting>
@@ -196,25 +145,16 @@ buildRebar3 rec {
 </programlisting>
 
     <para>
-     Such derivations are callable with
-     <literal>beam.packages.erlang.callPackage</literal> (see
-     <xref
-        linkend="erlang-call-package"/>). To call this package using
-     the normal <literal>callPackage</literal>, refer to dependency packages
-     via <literal>beamPackages</literal>, e.g.
-     <literal>beamPackages.ibrowse</literal>.
+     Such derivations are callable with <literal>beam.packages.erlang.callPackage</literal> (see <xref
+        linkend="erlang-call-package"/>). To call this package using the normal <literal>callPackage</literal>, refer to dependency packages via <literal>beamPackages</literal>, e.g. <literal>beamPackages.ibrowse</literal>.
     </para>
 
     <para>
-     Notably, <literal>buildRebar3</literal> includes
-     <literal>beamDeps</literal>, while <literal>stdenv.mkDerivation</literal>
-     does not. BEAM dependencies added there will be correctly handled by the
-     system.
+     Notably, <literal>buildRebar3</literal> includes <literal>beamDeps</literal>, while <literal>stdenv.mkDerivation</literal> does not. BEAM dependencies added there will be correctly handled by the system.
     </para>
 
     <para>
-     If a package needs to compile native code via Rebar3's port compilation
-     mechanism, add <literal>compilePort = true;</literal> to the derivation.
+     If a package needs to compile native code via Rebar3's port compilation mechanism, add <literal>compilePort = true;</literal> to the derivation.
     </para>
    </section>
 
@@ -222,9 +162,7 @@ buildRebar3 rec {
     <title>Erlang.mk Packages</title>
 
     <para>
-     Erlang.mk functions similarly to Rebar3, except we use
-     <literal>buildErlangMk</literal> instead of
-     <literal>buildRebar3</literal>.
+     Erlang.mk functions similarly to Rebar3, except we use <literal>buildErlangMk</literal> instead of <literal>buildRebar3</literal>.
     </para>
 
 <programlisting>
@@ -257,8 +195,7 @@ buildErlangMk {
     <title>Mix Packages</title>
 
     <para>
-     Mix functions similarly to Rebar3, except we use
-     <literal>buildMix</literal> instead of <literal>buildRebar3</literal>.
+     Mix functions similarly to Rebar3, except we use <literal>buildMix</literal> instead of <literal>buildRebar3</literal>.
     </para>
 
 <programlisting>
@@ -323,11 +260,7 @@ buildHex {
    <title>Accessing an Environment</title>
 
    <para>
-    Often, we simply want to access a valid environment that contains a
-    specific package and its dependencies. We can accomplish that with the
-    <literal>env</literal> attribute of a derivation. For example, let's say we
-    want to access an Erlang REPL with <literal>ibrowse</literal> loaded up. We
-    could do the following:
+    Often, we simply want to access a valid environment that contains a specific package and its dependencies. We can accomplish that with the <literal>env</literal> attribute of a derivation. For example, let's say we want to access an Erlang REPL with <literal>ibrowse</literal> loaded up. We could do the following:
    </para>
 
 <screen>
@@ -373,8 +306,7 @@ ok</computeroutput>
 </screen>
 
    <para>
-    Notice the <literal>-A beamPackages.ibrowse.env</literal>. That is the key
-    to this functionality.
+    Notice the <literal>-A beamPackages.ibrowse.env</literal>. That is the key to this functionality.
    </para>
   </section>
 
@@ -382,11 +314,7 @@ ok</computeroutput>
    <title>Creating a Shell</title>
 
    <para>
-    Getting access to an environment often isn't enough to do real development.
-    Usually, we need to create a <literal>shell.nix</literal> file and do our
-    development inside of the environment specified therein. This file looks a
-    lot like the packaging described above, except that <literal>src</literal>
-    points to the project root and we call the package directly.
+    Getting access to an environment often isn't enough to do real development. Usually, we need to create a <literal>shell.nix</literal> file and do our development inside of the environment specified therein. This file looks a lot like the packaging described above, except that <literal>src</literal> points to the project root and we call the package directly.
    </para>
 
 <programlisting>
@@ -414,8 +342,7 @@ in
     <title>Building in a Shell (for Mix Projects)</title>
 
     <para>
-     We can leverage the support of the derivation, irrespective of the build
-     derivation, by calling the commands themselves.
+     We can leverage the support of the derivation, irrespective of the build derivation, by calling the commands themselves.
     </para>
 
 <programlisting>
@@ -477,12 +404,8 @@ analyze: build plt
 </programlisting>
 
     <para>
-     Using a <literal>shell.nix</literal> as described (see
-     <xref
-      linkend="creating-a-shell"/>) should just work. Aside from
-     <literal>test</literal>, <literal>plt</literal>, and
-     <literal>analyze</literal>, the Make targets work just fine for all of the
-     build derivations.
+     Using a <literal>shell.nix</literal> as described (see <xref
+      linkend="creating-a-shell"/>) should just work. Aside from <literal>test</literal>, <literal>plt</literal>, and <literal>analyze</literal>, the Make targets work just fine for all of the build derivations.
     </para>
    </section>
   </section>
@@ -492,25 +415,14 @@ analyze: build plt
   <title>Generating Packages from Hex with <literal>hex2nix</literal></title>
 
   <para>
-   Updating the <link xlink:href="https://hex.pm">Hex</link> package set
-   requires
-   <link
-    xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link>.
-   Given the path to the Erlang modules (usually
-   <literal>pkgs/development/erlang-modules</literal>), it will dump a file
-   called <literal>hex-packages.nix</literal>, containing all the packages that
-   use a recognized build system in
-   <link
-    xlink:href="https://hex.pm">Hex</link>. It can't be determined,
-   however, whether every package is buildable.
+   Updating the <link xlink:href="https://hex.pm">Hex</link> package set requires <link
+    xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link>. Given the path to the Erlang modules (usually <literal>pkgs/development/erlang-modules</literal>), it will dump a file called <literal>hex-packages.nix</literal>, containing all the packages that use a recognized build system in <link
+    xlink:href="https://hex.pm">Hex</link>. It can't be determined, however, whether every package is buildable.
   </para>
 
   <para>
-   To make life easier for our users, try to build every
-   <link
-      xlink:href="https://hex.pm">Hex</link> package and remove those
-   that fail. To do that, simply run the following command in the root of your
-   <literal>nixpkgs</literal> repository:
+   To make life easier for our users, try to build every <link
+      xlink:href="https://hex.pm">Hex</link> package and remove those that fail. To do that, simply run the following command in the root of your <literal>nixpkgs</literal> repository:
   </para>
 
 <screen>
@@ -518,11 +430,8 @@ analyze: build plt
 </screen>
 
   <para>
-   That will attempt to build every package in <literal>beamPackages</literal>.
-   Then manually remove those that fail. Hopefully, someone will improve
-   <link
-      xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link>
-   in the future to automate the process.
+   That will attempt to build every package in <literal>beamPackages</literal>. Then manually remove those that fail. Hopefully, someone will improve <link
+      xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link> in the future to automate the process.
   </para>
  </section>
 </section>
diff --git a/doc/languages-frameworks/bower.xml b/doc/languages-frameworks/bower.xml
index 118f6e10473a..b0738cad293b 100644
--- a/doc/languages-frameworks/bower.xml
+++ b/doc/languages-frameworks/bower.xml
@@ -4,32 +4,22 @@
  <title>Bower</title>
 
  <para>
-  <link xlink:href="http://bower.io">Bower</link> is a package manager for web
-  site front-end components. Bower packages (comprising of build artefacts and
-  sometimes sources) are stored in <command>git</command> repositories,
-  typically on Github. The package registry is run by the Bower team with
-  package metadata coming from the <filename>bower.json</filename> file within
-  each package.
+  <link xlink:href="http://bower.io">Bower</link> is a package manager for web site front-end components. Bower packages (comprising of build artefacts and sometimes sources) are stored in <command>git</command> repositories, typically on Github. The package registry is run by the Bower team with package metadata coming from the <filename>bower.json</filename> file within each package.
  </para>
 
  <para>
-  The end result of running Bower is a <filename>bower_components</filename>
-  directory which can be included in the web app's build process.
+  The end result of running Bower is a <filename>bower_components</filename> directory which can be included in the web app's build process.
  </para>
 
  <para>
-  Bower can be run interactively, by installing
-  <varname>nodePackages.bower</varname>. More interestingly, the Bower
-  components can be declared in a Nix derivation, with the help of
-  <varname>nodePackages.bower2nix</varname>.
+  Bower can be run interactively, by installing <varname>nodePackages.bower</varname>. More interestingly, the Bower components can be declared in a Nix derivation, with the help of <varname>nodePackages.bower2nix</varname>.
  </para>
 
  <section xml:id="ssec-bower2nix-usage">
   <title><command>bower2nix</command> usage</title>
 
   <para>
-   Suppose you have a <filename>bower.json</filename> with the following
-   contents:
+   Suppose you have a <filename>bower.json</filename> with the following contents:
    <example xml:id="ex-bowerJson">
     <title><filename>bower.json</filename></title>
 <programlisting language="json">
@@ -45,8 +35,7 @@
   </para>
 
   <para>
-   Running <command>bower2nix</command> will produce something like the
-   following output:
+   Running <command>bower2nix</command> will produce something like the following output:
 <programlisting language="nix">
 <![CDATA[{ fetchbower, buildEnv }:
 buildEnv { name = "bower-env"; ignoreCollisions = true; paths = [
@@ -58,15 +47,11 @@ buildEnv { name = "bower-env"; ignoreCollisions = true; paths = [
   </para>
 
   <para>
-   Using the <command>bower2nix</command> command line arguments, the output
-   can be redirected to a file. A name like
-   <filename>bower-packages.nix</filename> would be fine.
+   Using the <command>bower2nix</command> command line arguments, the output can be redirected to a file. A name like <filename>bower-packages.nix</filename> would be fine.
   </para>
 
   <para>
-   The resulting derivation is a union of all the downloaded Bower packages
-   (and their dependencies). To use it, they still need to be linked together
-   by Bower, which is where <varname>buildBowerComponents</varname> is useful.
+   The resulting derivation is a union of all the downloaded Bower packages (and their dependencies). To use it, they still need to be linked together by Bower, which is where <varname>buildBowerComponents</varname> is useful.
   </para>
  </section>
 
@@ -74,10 +59,7 @@ buildEnv { name = "bower-env"; ignoreCollisions = true; paths = [
   <title><varname>buildBowerComponents</varname> function</title>
 
   <para>
-   The function is implemented in
-   <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/bower-modules/generic/default.nix">
-   <filename>pkgs/development/bower-modules/generic/default.nix</filename></link>.
-   Example usage:
+   The function is implemented in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/bower-modules/generic/default.nix"> <filename>pkgs/development/bower-modules/generic/default.nix</filename></link>. Example usage:
    <example xml:id="ex-buildBowerComponents">
     <title>buildBowerComponents</title>
 <programlisting language="nix">
@@ -91,34 +73,27 @@ bowerComponents = buildBowerComponents {
   </para>
 
   <para>
-   In <xref linkend="ex-buildBowerComponents" />, the following arguments are
-   of special significance to the function:
+   In <xref linkend="ex-buildBowerComponents" />, the following arguments are of special significance to the function:
    <calloutlist>
     <callout arearefs="ex-buildBowerComponents-1">
      <para>
-      <varname>generated</varname> specifies the file which was created by
-      <command>bower2nix</command>.
+      <varname>generated</varname> specifies the file which was created by <command>bower2nix</command>.
      </para>
     </callout>
     <callout arearefs="ex-buildBowerComponents-2">
      <para>
-      <varname>src</varname> is your project's sources. It needs to contain a
-      <filename>bower.json</filename> file.
+      <varname>src</varname> is your project's sources. It needs to contain a <filename>bower.json</filename> file.
      </para>
     </callout>
    </calloutlist>
   </para>
 
   <para>
-   <varname>buildBowerComponents</varname> will run Bower to link together the
-   output of <command>bower2nix</command>, resulting in a
-   <filename>bower_components</filename> directory which can be used.
+   <varname>buildBowerComponents</varname> will run Bower to link together the output of <command>bower2nix</command>, resulting in a <filename>bower_components</filename> directory which can be used.
   </para>
 
   <para>
-   Here is an example of a web frontend build process using
-   <command>gulp</command>. You might use <command>grunt</command>, or anything
-   else.
+   Here is an example of a web frontend build process using <command>gulp</command>. You might use <command>grunt</command>, or anything else.
   </para>
 
   <example xml:id="ex-bowerGulpFile">
@@ -174,21 +149,17 @@ pkgs.stdenv.mkDerivation {
    <calloutlist>
     <callout arearefs="ex-buildBowerComponentsDefault-1">
      <para>
-      The result of <varname>buildBowerComponents</varname> is an input to the
-      frontend build.
+      The result of <varname>buildBowerComponents</varname> is an input to the frontend build.
      </para>
     </callout>
     <callout arearefs="ex-buildBowerComponentsDefault-2">
      <para>
-      Whether to symlink or copy the <filename>bower_components</filename>
-      directory depends on the build tool in use. In this case a copy is used
-      to avoid <command>gulp</command> silliness with permissions.
+      Whether to symlink or copy the <filename>bower_components</filename> directory depends on the build tool in use. In this case a copy is used to avoid <command>gulp</command> silliness with permissions.
      </para>
     </callout>
     <callout arearefs="ex-buildBowerComponentsDefault-3">
      <para>
-      <command>gulp</command> requires <varname>HOME</varname> to refer to a
-      writeable directory.
+      <command>gulp</command> requires <varname>HOME</varname> to refer to a writeable directory.
      </para>
     </callout>
     <callout arearefs="ex-buildBowerComponentsDefault-4">
@@ -210,17 +181,13 @@ pkgs.stdenv.mkDerivation {
     </term>
     <listitem>
      <para>
-      This means that Bower was looking for a package version which doesn't
-      exist in the generated <filename>bower-packages.nix</filename>.
+      This means that Bower was looking for a package version which doesn't exist in the generated <filename>bower-packages.nix</filename>.
      </para>
      <para>
-      If <filename>bower.json</filename> has been updated, then run
-      <command>bower2nix</command> again.
+      If <filename>bower.json</filename> has been updated, then run <command>bower2nix</command> again.
      </para>
      <para>
-      It could also be a bug in <command>bower2nix</command> or
-      <command>fetchbower</command>. If possible, try reformulating the version
-      specification in <filename>bower.json</filename>.
+      It could also be a bug in <command>bower2nix</command> or <command>fetchbower</command>. If possible, try reformulating the version specification in <filename>bower.json</filename>.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/languages-frameworks/coq.xml b/doc/languages-frameworks/coq.xml
index 4314df5c9df2..86d9226166f5 100644
--- a/doc/languages-frameworks/coq.xml
+++ b/doc/languages-frameworks/coq.xml
@@ -4,31 +4,19 @@
  <title>Coq</title>
 
  <para>
-  Coq libraries should be installed in
-  <literal>$(out)/lib/coq/${coq.coq-version}/user-contrib/</literal>. Such
-  directories are automatically added to the <literal>$COQPATH</literal>
-  environment variable by the hook defined in the Coq derivation.
+  Coq libraries should be installed in <literal>$(out)/lib/coq/${coq.coq-version}/user-contrib/</literal>. Such directories are automatically added to the <literal>$COQPATH</literal> environment variable by the hook defined in the Coq derivation.
  </para>
 
  <para>
-  Some extensions (plugins) might require OCaml and sometimes other OCaml
-  packages. The <literal>coq.ocamlPackages</literal> attribute can be used to
-  depend on the same package set Coq was built against.
+  Some extensions (plugins) might require OCaml and sometimes other OCaml packages. The <literal>coq.ocamlPackages</literal> attribute can be used to depend on the same package set Coq was built against.
  </para>
 
  <para>
-  Coq libraries may be compatible with some specific versions of Coq only. The
-  <literal>compatibleCoqVersions</literal> attribute is used to precisely
-  select those versions of Coq that are compatible with this derivation.
+  Coq libraries may be compatible with some specific versions of Coq only. The <literal>compatibleCoqVersions</literal> attribute is used to precisely select those versions of Coq that are compatible with this derivation.
  </para>
 
  <para>
-  Here is a simple package example. It is a pure Coq library, thus it depends
-  on Coq. It builds on the Mathematical Components library, thus it also takes
-  <literal>mathcomp</literal> as <literal>buildInputs</literal>. Its
-  <literal>Makefile</literal> has been generated using
-  <literal>coq_makefile</literal> so we only have to set the
-  <literal>$COQLIB</literal> variable at install time.
+  Here is a simple package example. It is a pure Coq library, thus it depends on Coq. It builds on the Mathematical Components library, thus it also takes <literal>mathcomp</literal> as <literal>buildInputs</literal>. Its <literal>Makefile</literal> has been generated using <literal>coq_makefile</literal> so we only have to set the <literal>$COQLIB</literal> variable at install time.
  </para>
 
 <programlisting>
diff --git a/doc/languages-frameworks/gnome.xml b/doc/languages-frameworks/gnome.xml
index 290057863b24..8b3151d5bf94 100644
--- a/doc/languages-frameworks/gnome.xml
+++ b/doc/languages-frameworks/gnome.xml
@@ -5,53 +5,26 @@
   <title>Packaging GNOME applications</title>
 
   <para>
-   Programs in the GNOME universe are written in various languages but they all
-   use GObject-based libraries like GLib, GTK or GStreamer. These libraries are
-   often modular, relying on looking into certain directories to find their
-   modules. However, due to Nix’s specific file system organization, this
-   will fail without our intervention. Fortunately, the libraries usually allow
-   overriding the directories through environment variables, either natively or
-   thanks to a patch in nixpkgs.
-   <link xlink:href="#fun-wrapProgram">Wrapping</link> the executables to
-   ensure correct paths are available to the application constitutes a
-   significant part of packaging a modern desktop application. In this section,
-   we will describe various modules needed by such applications, environment
-   variables needed to make the modules load, and finally a script that will do
-   the work for us.
+   Programs in the GNOME universe are written in various languages but they all use GObject-based libraries like GLib, GTK or GStreamer. These libraries are often modular, relying on looking into certain directories to find their modules. However, due to Nix’s specific file system organization, this will fail without our intervention. Fortunately, the libraries usually allow overriding the directories through environment variables, either natively or thanks to a patch in nixpkgs. <link xlink:href="#fun-wrapProgram">Wrapping</link> the executables to ensure correct paths are available to the application constitutes a significant part of packaging a modern desktop application. In this section, we will describe various modules needed by such applications, environment variables needed to make the modules load, and finally a script that will do the work for us.
   </para>
 
   <section xml:id="ssec-gnome-settings">
    <title>Settings</title>
 
    <para>
-    <link xlink:href="https://developer.gnome.org/gio/stable/GSettings.html">GSettings</link>
-    API is often used for storing settings. GSettings schemas are required, to
-    know the type and other metadata of the stored values. GLib looks for
-    <filename>glib-2.0/schemas/gschemas.compiled</filename> files inside the
-    directories of <envar>XDG_DATA_DIRS</envar>.
+    <link xlink:href="https://developer.gnome.org/gio/stable/GSettings.html">GSettings</link> API is often used for storing settings. GSettings schemas are required, to know the type and other metadata of the stored values. GLib looks for <filename>glib-2.0/schemas/gschemas.compiled</filename> files inside the directories of <envar>XDG_DATA_DIRS</envar>.
    </para>
 
    <para>
-    On Linux, GSettings API is implemented using
-    <link xlink:href="https://wiki.gnome.org/Projects/dconf">dconf</link>
-    backend. You will need to add <literal>dconf</literal> GIO module to
-    <envar>GIO_EXTRA_MODULES</envar> variable, otherwise the
-    <literal>memory</literal> backend will be used and the saved settings will
-    not be persistent.
+    On Linux, GSettings API is implemented using <link xlink:href="https://wiki.gnome.org/Projects/dconf">dconf</link> backend. You will need to add <literal>dconf</literal> GIO module to <envar>GIO_EXTRA_MODULES</envar> variable, otherwise the <literal>memory</literal> backend will be used and the saved settings will not be persistent.
    </para>
 
    <para>
-    Last you will need the dconf database D-Bus service itself. You can enable
-    it using <option>programs.dconf.enable</option>.
+    Last you will need the dconf database D-Bus service itself. You can enable it using <option>programs.dconf.enable</option>.
    </para>
 
    <para>
-    Some applications will also require
-    <package>gsettings-desktop-schemas</package> for things like reading proxy
-    configuration or user interface customization. This dependency is often not
-    mentioned by upstream, you should grep for
-    <literal>org.gnome.desktop</literal> and
-    <literal>org.gnome.system</literal> to see if the schemas are needed.
+    Some applications will also require <package>gsettings-desktop-schemas</package> for things like reading proxy configuration or user interface customization. This dependency is often not mentioned by upstream, you should grep for <literal>org.gnome.desktop</literal> and <literal>org.gnome.system</literal> to see if the schemas are needed.
    </para>
   </section>
 
@@ -59,16 +32,7 @@
    <title>Icons</title>
 
    <para>
-    When an application uses icons, an icon theme should be available in
-    <envar>XDG_DATA_DIRS</envar>. The package for the default, icon-less
-    <link xlink:href="https://www.freedesktop.org/wiki/Software/icon-theme/">hicolor-icon-theme</link>
-    contains <link linkend="ssec-gnome-hooks-hicolor-icon-theme">a setup
-    hook</link> that will pick up icon themes from
-    <literal>buildInputs</literal> and pass it to our wrapper. Unfortunately,
-    relying on that would mean every user has to download the theme included in
-    the package expression no matter their preference. For that reason, we
-    leave the installation of icon theme on the user. If you use one of the
-    desktop environments, you probably already have an icon theme installed.
+    When an application uses icons, an icon theme should be available in <envar>XDG_DATA_DIRS</envar>. The package for the default, icon-less <link xlink:href="https://www.freedesktop.org/wiki/Software/icon-theme/">hicolor-icon-theme</link> contains <link linkend="ssec-gnome-hooks-hicolor-icon-theme">a setup hook</link> that will pick up icon themes from <literal>buildInputs</literal> and pass it to our wrapper. Unfortunately, relying on that would mean every user has to download the theme included in the package expression no matter their preference. For that reason, we leave the installation of icon theme on the user. If you use one of the desktop environments, you probably already have an icon theme installed.
    </para>
   </section>
 
@@ -76,12 +40,7 @@
    <title>GTK Themes</title>
 
    <para>
-    Previously, a GTK theme needed to be in <envar>XDG_DATA_DIRS</envar>. This
-    is no longer necessary for most programs since GTK incorporated Adwaita
-    theme. Some programs (for example, those designed for
-    <link xlink:href="https://elementary.io/docs/human-interface-guidelines#human-interface-guidelines">elementary
-    HIG</link>) might require a special theme like
-    <package>pantheon.elementary-gtk-theme</package>.
+    Previously, a GTK theme needed to be in <envar>XDG_DATA_DIRS</envar>. This is no longer necessary for most programs since GTK incorporated Adwaita theme. Some programs (for example, those designed for <link xlink:href="https://elementary.io/docs/human-interface-guidelines#human-interface-guidelines">elementary HIG</link>) might require a special theme like <package>pantheon.elementary-gtk-theme</package>.
    </para>
   </section>
 
@@ -89,10 +48,7 @@
    <title>GObject introspection typelibs</title>
 
    <para>
-    <link xlink:href="https://wiki.gnome.org/Projects/GObjectIntrospection">GObject
-    introspection</link> allows applications to use C libraries in other
-    languages easily. It does this through <literal>typelib</literal> files
-    searched in <envar>GI_TYPELIB_PATH</envar>.
+    <link xlink:href="https://wiki.gnome.org/Projects/GObjectIntrospection">GObject introspection</link> allows applications to use C libraries in other languages easily. It does this through <literal>typelib</literal> files searched in <envar>GI_TYPELIB_PATH</envar>.
    </para>
   </section>
 
@@ -100,11 +56,7 @@
    <title>Various plug-ins</title>
 
    <para>
-    If your application uses
-    <link xlink:href="https://gstreamer.freedesktop.org/">GStreamer</link> or
-    <link xlink:href="https://wiki.gnome.org/Projects/Grilo">Grilo</link>, you
-    should set <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> and
-    <envar>GRL_PLUGIN_PATH</envar>, respectively.
+    If your application uses <link xlink:href="https://gstreamer.freedesktop.org/">GStreamer</link> or <link xlink:href="https://wiki.gnome.org/Projects/Grilo">Grilo</link>, you should set <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> and <envar>GRL_PLUGIN_PATH</envar>, respectively.
    </para>
   </section>
  </section>
@@ -113,8 +65,7 @@
   <title>Onto <package>wrapGAppsHook</package></title>
 
   <para>
-   Given the requirements above, the package expression would become messy
-   quickly:
+   Given the requirements above, the package expression would become messy quickly:
 <programlisting>
 preFixup = ''
   for f in $(find $out/bin/ $out/libexec/ -type f -executable); do
@@ -128,76 +79,48 @@ preFixup = ''
   done
 '';
 </programlisting>
-   Fortunately, there is <package>wrapGAppsHook</package>, that does the
-   wrapping for us. In particular, it works in conjunction with other setup
-   hooks that will populate the variable:
+   Fortunately, there is <package>wrapGAppsHook</package>, that does the wrapping for us. In particular, it works in conjunction with other setup hooks that will populate the variable:
    <itemizedlist>
     <listitem xml:id="ssec-gnome-hooks-wrapgappshook">
      <para>
-      <package>wrapGAppsHook</package> itself will add the package’s
-      <filename>share</filename> directory to <envar>XDG_DATA_DIRS</envar>.
+      <package>wrapGAppsHook</package> itself will add the package’s <filename>share</filename> directory to <envar>XDG_DATA_DIRS</envar>.
      </para>
     </listitem>
     <listitem xml:id="ssec-gnome-hooks-glib">
      <para>
-      <package>glib</package> setup hook will populate
-      <envar>GSETTINGS_SCHEMAS_PATH</envar> and then
-      <package>wrapGAppsHook</package> will prepend it to
-      <envar>XDG_DATA_DIRS</envar>.
+      <package>glib</package> setup hook will populate <envar>GSETTINGS_SCHEMAS_PATH</envar> and then <package>wrapGAppsHook</package> will prepend it to <envar>XDG_DATA_DIRS</envar>.
      </para>
     </listitem>
     <listitem xml:id="ssec-gnome-hooks-dconf">
      <para>
-      <package>gnome3.dconf.lib</package> is a dependency of
-      <package>wrapGAppsHook</package>, which then also adds it to the
-      <envar>GIO_EXTRA_MODULES</envar> variable.
+      <package>gnome3.dconf.lib</package> is a dependency of <package>wrapGAppsHook</package>, which then also adds it to the <envar>GIO_EXTRA_MODULES</envar> variable.
      </para>
     </listitem>
     <listitem xml:id="ssec-gnome-hooks-hicolor-icon-theme">
      <para>
-      <package>hicolor-icon-theme</package>’s setup hook will add icon themes
-      to <envar>XDG_ICON_DIRS</envar> which is prepended to
-      <envar>XDG_DATA_DIRS</envar> by <package>wrapGAppsHook</package>.
+      <package>hicolor-icon-theme</package>’s setup hook will add icon themes to <envar>XDG_ICON_DIRS</envar> which is prepended to <envar>XDG_DATA_DIRS</envar> by <package>wrapGAppsHook</package>.
      </para>
     </listitem>
     <listitem xml:id="ssec-gnome-hooks-gobject-introspection">
      <para>
-      <package>gobject-introspection</package> setup hook populates
-      <envar>GI_TYPELIB_PATH</envar> variable with
-      <filename>lib/girepository-1.0</filename> directories of dependencies,
-      which is then added to wrapper by <package>wrapGAppsHook</package>. It
-      also adds <filename>share</filename> directories of dependencies to
-      <envar>XDG_DATA_DIRS</envar>, which is intended to promote GIR files but
-      it also
-      <link xlink:href="https://github.com/NixOS/nixpkgs/issues/32790">pollutes
-      the closures</link> of packages using <package>wrapGAppsHook</package>.
+      <package>gobject-introspection</package> setup hook populates <envar>GI_TYPELIB_PATH</envar> variable with <filename>lib/girepository-1.0</filename> directories of dependencies, which is then added to wrapper by <package>wrapGAppsHook</package>. It also adds <filename>share</filename> directories of dependencies to <envar>XDG_DATA_DIRS</envar>, which is intended to promote GIR files but it also <link xlink:href="https://github.com/NixOS/nixpkgs/issues/32790">pollutes the closures</link> of packages using <package>wrapGAppsHook</package>.
      </para>
      <warning>
       <para>
-       The setup hook
-       <link xlink:href="https://github.com/NixOS/nixpkgs/issues/56943">currently</link>
-       does not work in expressions with <literal>strictDeps</literal> enabled,
-       like Python packages. In those cases, you will need to disable it with
-       <code>strictDeps = false;</code>.
+       The setup hook <link xlink:href="https://github.com/NixOS/nixpkgs/issues/56943">currently</link> does not work in expressions with <literal>strictDeps</literal> enabled, like Python packages. In those cases, you will need to disable it with <code>strictDeps = false;</code>.
       </para>
      </warning>
     </listitem>
     <listitem xml:id="ssec-gnome-hooks-gst-grl-plugins">
      <para>
-      Setup hooks of <package>gst_all_1.gstreamer</package> and
-      <package>gnome3.grilo</package> will populate the
-      <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> and
-      <envar>GRL_PLUGIN_PATH</envar> variables, respectively, which will then
-      be added to the wrapper by <literal>wrapGAppsHook</literal>.
+      Setup hooks of <package>gst_all_1.gstreamer</package> and <package>gnome3.grilo</package> will populate the <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> and <envar>GRL_PLUGIN_PATH</envar> variables, respectively, which will then be added to the wrapper by <literal>wrapGAppsHook</literal>.
      </para>
     </listitem>
    </itemizedlist>
   </para>
 
   <para>
-   You can also pass additional arguments to <literal>makeWrapper</literal>
-   using <literal>gappsWrapperArgs</literal> in <literal>preFixup</literal>
-   hook:
+   You can also pass additional arguments to <literal>makeWrapper</literal> using <literal>gappsWrapperArgs</literal> in <literal>preFixup</literal> hook:
 <programlisting>
 preFixup = ''
   gappsWrapperArgs+=(
@@ -215,13 +138,7 @@ preFixup = ''
   <title>Updating GNOME packages</title>
 
   <para>
-   Most GNOME package offer
-   <link linkend="var-passthru-updateScript"><literal>updateScript</literal></link>,
-   it is therefore possible to update to latest source tarball by running
-   <command>nix-shell maintainers/scripts/update.nix --argstr package
-   gnome3.nautilus</command> or even en masse with <command>nix-shell
-   maintainers/scripts/update.nix --argstr path gnome3</command>. Read the
-   package’s <filename>NEWS</filename> file to see what changed.
+   Most GNOME package offer <link linkend="var-passthru-updateScript"><literal>updateScript</literal></link>, it is therefore possible to update to latest source tarball by running <command>nix-shell maintainers/scripts/update.nix --argstr package gnome3.nautilus</command> or even en masse with <command>nix-shell maintainers/scripts/update.nix --argstr path gnome3</command>. Read the package’s <filename>NEWS</filename> file to see what changed.
   </para>
  </section>
 
@@ -235,17 +152,7 @@ preFixup = ''
     </term>
     <listitem>
      <para>
-      There are no schemas avalable in <envar>XDG_DATA_DIRS</envar>.
-      Temporarily add a random package containing schemas like
-      <package>gsettings-desktop-schemas</package> to
-      <literal>buildInputs</literal>.
-      <link linkend="ssec-gnome-hooks-glib"><package>glib</package></link> and
-      <link linkend="ssec-gnome-hooks-wrapgappshook"><package>wrapGAppsHook</package></link>
-      setup hooks will take care of making the schemas available to application
-      and you will see the actual missing schemas with the
-      <link linkend="ssec-gnome-common-issues-missing-schema">next
-      error</link>. Or you can try looking through the source code for the
-      actual schemas used.
+      There are no schemas avalable in <envar>XDG_DATA_DIRS</envar>. Temporarily add a random package containing schemas like <package>gsettings-desktop-schemas</package> to <literal>buildInputs</literal>. <link linkend="ssec-gnome-hooks-glib"><package>glib</package></link> and <link linkend="ssec-gnome-hooks-wrapgappshook"><package>wrapGAppsHook</package></link> setup hooks will take care of making the schemas available to application and you will see the actual missing schemas with the <link linkend="ssec-gnome-common-issues-missing-schema">next error</link>. Or you can try looking through the source code for the actual schemas used.
      </para>
     </listitem>
    </varlistentry>
@@ -255,11 +162,7 @@ preFixup = ''
     </term>
     <listitem>
      <para>
-      Package is missing some GSettings schemas. You can find out the package
-      containing the schema with <command>nix-locate
-      <replaceable>org.gnome.foo</replaceable>.gschema.xml</command> and let
-      the hooks handle the wrapping as
-      <link linkend="ssec-gnome-common-issues-no-schemas">above</link>.
+      Package is missing some GSettings schemas. You can find out the package containing the schema with <command>nix-locate <replaceable>org.gnome.foo</replaceable>.gschema.xml</command> and let the hooks handle the wrapping as <link linkend="ssec-gnome-common-issues-no-schemas">above</link>.
      </para>
     </listitem>
    </varlistentry>
@@ -269,14 +172,7 @@ preFixup = ''
     </term>
     <listitem>
      <para>
-      This is because derivers like
-      <function>python.pkgs.buildPythonApplication</function> or
-      <function>qt5.mkDerivation</function> have setup-hooks automatically
-      added that produce wrappers with <package>makeWrapper</package>. The
-      simplest way to workaround that is to disable the
-      <package>wrapGAppsHook</package> automatic wrapping with
-      <code>dontWrapGApps = true;</code> and pass the arguments it intended to
-      pass to <package>makeWrapper</package> to another.
+      This is because derivers like <function>python.pkgs.buildPythonApplication</function> or <function>qt5.mkDerivation</function> have setup-hooks automatically added that produce wrappers with <package>makeWrapper</package>. The simplest way to workaround that is to disable the <package>wrapGAppsHook</package> automatic wrapping with <code>dontWrapGApps = true;</code> and pass the arguments it intended to pass to <package>makeWrapper</package> to another.
      </para>
      <para>
       In the case of a Python application it could look like:
@@ -328,55 +224,34 @@ mkDerivation {
     </term>
     <listitem>
      <para>
-      You can rely on applications depending on the library set the necessary
-      environment variables but that it often easy to miss. Instead we
-      recommend to patch the paths in the source code whenever possible. Here
-      are some examples:
+      You can rely on applications depending on the library set the necessary environment variables but that it often easy to miss. Instead we recommend to patch the paths in the source code whenever possible. Here are some examples:
       <itemizedlist>
        <listitem xml:id="ssec-gnome-common-issues-unwrappable-package-gnome-shell-ext">
         <para>
-         <link xlink:href="https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/gnome-3/core/gnome-shell-extensions/default.nix#L21-L24">Replacing
-         a <envar>GI_TYPELIB_PATH</envar> in GNOME Shell extension</link> –
-         we are using <function>substituteAll</function> to include the path to
-         a typelib into a patch.
+         <link xlink:href="https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/gnome-3/core/gnome-shell-extensions/default.nix#L21-L24">Replacing a <envar>GI_TYPELIB_PATH</envar> in GNOME Shell extension</link> – we are using <function>substituteAll</function> to include the path to a typelib into a patch.
         </para>
        </listitem>
        <listitem xml:id="ssec-gnome-common-issues-unwrappable-package-gsettings">
         <para>
-         The following examples are hardcoding GSettings schema paths. To get
-         the schema paths we use the functions
+         The following examples are hardcoding GSettings schema paths. To get the schema paths we use the functions
          <itemizedlist>
           <listitem>
            <para>
-            <function>glib.getSchemaPath</function> Takes a nix package
-            attribute as an argument.
+            <function>glib.getSchemaPath</function> Takes a nix package attribute as an argument.
            </para>
           </listitem>
           <listitem>
            <para>
-            <function>glib.makeSchemaPath</function> Takes a package output
-            like <literal>$out</literal> and a derivation name. You should use
-            this if the schemas you need to hardcode are in the same
-            derivation.
+            <function>glib.makeSchemaPath</function> Takes a package output like <literal>$out</literal> and a derivation name. You should use this if the schemas you need to hardcode are in the same derivation.
            </para>
           </listitem>
          </itemizedlist>
         </para>
         <para xml:id="ssec-gnome-common-issues-unwrappable-package-gsettings-vala">
-         <link xlink:href="https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/pantheon/apps/elementary-files/default.nix#L78-L86">Hard-coding
-         GSettings schema path in Vala plug-in (dynamically loaded
-         library)</link> – here, <function>substituteAll</function> cannot be
-         used since the schema comes from the same package preventing us from
-         pass its path to the function, probably due to a
-         <link xlink:href="https://github.com/NixOS/nix/issues/1846">Nix
-         bug</link>.
+         <link xlink:href="https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/pantheon/apps/elementary-files/default.nix#L78-L86">Hard-coding GSettings schema path in Vala plug-in (dynamically loaded library)</link> – here, <function>substituteAll</function> cannot be used since the schema comes from the same package preventing us from pass its path to the function, probably due to a <link xlink:href="https://github.com/NixOS/nix/issues/1846">Nix bug</link>.
         </para>
         <para xml:id="ssec-gnome-common-issues-unwrappable-package-gsettings-c">
-         <link xlink:href="https://github.com/NixOS/nixpkgs/blob/29c120c065d03b000224872251bed93932d42412/pkgs/development/libraries/glib-networking/default.nix#L31-L34">Hard-coding
-         GSettings schema path in C library</link> – nothing special other
-         than using
-         <link xlink:href="https://github.com/NixOS/nixpkgs/pull/67957#issuecomment-527717467">Coccinelle
-         patch</link> to generate the patch itself.
+         <link xlink:href="https://github.com/NixOS/nixpkgs/blob/29c120c065d03b000224872251bed93932d42412/pkgs/development/libraries/glib-networking/default.nix#L31-L34">Hard-coding GSettings schema path in C library</link> – nothing special other than using <link xlink:href="https://github.com/NixOS/nixpkgs/pull/67957#issuecomment-527717467">Coccinelle patch</link> to generate the patch itself.
         </para>
        </listitem>
       </itemizedlist>
diff --git a/doc/languages-frameworks/go.xml b/doc/languages-frameworks/go.xml
index b2b4962cb5f6..288a90298631 100644
--- a/doc/languages-frameworks/go.xml
+++ b/doc/languages-frameworks/go.xml
@@ -7,21 +7,16 @@
   <title>Go modules</title>
 
   <para>
-   The function <varname> buildGoModule </varname> builds Go programs managed
-   with Go modules. It builds a
-   <link xlink:href="https://github.com/golang/go/wiki/Modules">Go
-   modules</link> through a two phase build:
+   The function <varname> buildGoModule </varname> builds Go programs managed with Go modules. It builds a <link xlink:href="https://github.com/golang/go/wiki/Modules">Go modules</link> through a two phase build:
    <itemizedlist>
     <listitem>
      <para>
-      An intermediate fetcher derivation. This derivation will be used to fetch
-      all of the dependencies of the Go module.
+      An intermediate fetcher derivation. This derivation will be used to fetch all of the dependencies of the Go module.
      </para>
     </listitem>
     <listitem>
      <para>
-      A final derivation will use the output of the intermediate derivation to
-      build the binaries and produce the final output.
+      A final derivation will use the output of the intermediate derivation to build the binaries and produce the final output.
      </para>
     </listitem>
    </itemizedlist>
@@ -57,21 +52,16 @@ pet = buildGoModule rec {
   </example>
 
   <para>
-   <xref linkend='ex-buildGoModule'/> is an example expression using
-   buildGoModule, the following arguments are of special significance to the
-   function:
+   <xref linkend='ex-buildGoModule'/> is an example expression using buildGoModule, the following arguments are of special significance to the function:
    <calloutlist>
     <callout arearefs='ex-buildGoModule-1'>
      <para>
-      <varname>modSha256</varname> is the hash of the output of the
-      intermediate fetcher derivation.
+      <varname>modSha256</varname> is the hash of the output of the intermediate fetcher derivation.
      </para>
     </callout>
     <callout arearefs='ex-buildGoModule-2'>
      <para>
-      <varname>subPackages</varname> limits the builder from building child
-      packages that have not been listed. If <varname>subPackages</varname> is
-      not specified, all child packages will be built.
+      <varname>subPackages</varname> limits the builder from building child packages that have not been listed. If <varname>subPackages</varname> is not specified, all child packages will be built.
      </para>
     </callout>
    </calloutlist>
@@ -82,8 +72,7 @@ pet = buildGoModule rec {
   <title>Go legacy</title>
 
   <para>
-   The function <varname> buildGoPackage </varname> builds legacy Go programs,
-   not supporting Go modules.
+   The function <varname> buildGoPackage </varname> builds legacy Go programs, not supporting Go modules.
   </para>
 
   <example xml:id='ex-buildGoPackage'>
@@ -111,49 +100,36 @@ deis = buildGoPackage rec {
   </example>
 
   <para>
-   <xref linkend='ex-buildGoPackage'/> is an example expression using
-   buildGoPackage, the following arguments are of special significance to the
-   function:
+   <xref linkend='ex-buildGoPackage'/> is an example expression using buildGoPackage, the following arguments are of special significance to the function:
    <calloutlist>
     <callout arearefs='ex-buildGoPackage-1'>
      <para>
-      <varname>goPackagePath</varname> specifies the package's canonical Go
-      import path.
+      <varname>goPackagePath</varname> specifies the package's canonical Go import path.
      </para>
     </callout>
     <callout arearefs='ex-buildGoPackage-2'>
      <para>
-      <varname>subPackages</varname> limits the builder from building child
-      packages that have not been listed. If <varname>subPackages</varname> is
-      not specified, all child packages will be built.
+      <varname>subPackages</varname> limits the builder from building child packages that have not been listed. If <varname>subPackages</varname> is not specified, all child packages will be built.
      </para>
      <para>
-      In this example only <literal>github.com/deis/deis/client</literal> will
-      be built.
+      In this example only <literal>github.com/deis/deis/client</literal> will be built.
      </para>
     </callout>
     <callout arearefs='ex-buildGoPackage-3'>
      <para>
-      <varname>goDeps</varname> is where the Go dependencies of a Go program
-      are listed as a list of package source identified by Go import path. It
-      could be imported as a separate <varname>deps.nix</varname> file for
-      readability. The dependency data structure is described below.
+      <varname>goDeps</varname> is where the Go dependencies of a Go program are listed as a list of package source identified by Go import path. It could be imported as a separate <varname>deps.nix</varname> file for readability. The dependency data structure is described below.
      </para>
     </callout>
     <callout arearefs='ex-buildGoPackage-4'>
      <para>
-      <varname>buildFlags</varname> is a list of flags passed to the go build
-      command.
+      <varname>buildFlags</varname> is a list of flags passed to the go build command.
      </para>
     </callout>
    </calloutlist>
   </para>
 
   <para>
-   The <varname>goDeps</varname> attribute can be imported from a separate
-   <varname>nix</varname> file that defines which Go libraries are needed and
-   should be included in <varname>GOPATH</varname> for
-   <varname>buildPhase</varname>.
+   The <varname>goDeps</varname> attribute can be imported from a separate <varname>nix</varname> file that defines which Go libraries are needed and should be included in <varname>GOPATH</varname> for <varname>buildPhase</varname>.
   </para>
 
   <example xml:id='ex-goDeps'>
@@ -196,27 +172,18 @@ deis = buildGoPackage rec {
     </callout>
     <callout arearefs='ex-goDeps-3'>
      <para>
-      <varname>fetch type</varname> that needs to be used to get package
-      source. If <varname>git</varname> is used there should be
-      <varname>url</varname>, <varname>rev</varname> and
-      <varname>sha256</varname> defined next to it.
+      <varname>fetch type</varname> that needs to be used to get package source. If <varname>git</varname> is used there should be <varname>url</varname>, <varname>rev</varname> and <varname>sha256</varname> defined next to it.
      </para>
     </callout>
    </calloutlist>
   </para>
 
   <para>
-   To extract dependency information from a Go package in automated way use
-   <link xlink:href="https://github.com/kamilchm/go2nix">go2nix</link>. It can
-   produce complete derivation and <varname>goDeps</varname> file for Go
-   programs.
+   To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/kamilchm/go2nix">go2nix</link>. It can produce complete derivation and <varname>goDeps</varname> file for Go programs.
   </para>
 
   <para>
-   <varname>buildGoPackage</varname> produces
-   <xref linkend='chap-multiple-output' xrefstyle="select: title" /> where
-   <varname>bin</varname> includes program binaries. You can test build a Go
-   binary as follows:
+   <varname>buildGoPackage</varname> produces <xref linkend='chap-multiple-output' xrefstyle="select: title" /> where <varname>bin</varname> includes program binaries. You can test build a Go binary as follows:
 <screen>
 <prompt>$ </prompt>nix-build -A deis.bin
 </screen>
@@ -224,13 +191,11 @@ deis = buildGoPackage rec {
 <screen>
 <prompt>$ </prompt>nix-build -A deis.all
 </screen>
-   <varname>bin</varname> output will be installed by default with
-   <varname>nix-env -i</varname> or <varname>systemPackages</varname>.
+   <varname>bin</varname> output will be installed by default with <varname>nix-env -i</varname> or <varname>systemPackages</varname>.
   </para>
 
   <para>
-   You may use Go packages installed into the active Nix profiles by adding the
-   following to your ~/.bashrc:
+   You may use Go packages installed into the active Nix profiles by adding the following to your ~/.bashrc:
 <screen>
 for p in $NIX_PROFILES; do
     GOPATH="$p/share/go:$GOPATH"
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index 5836294b7748..cd0b48adb14a 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -3,12 +3,7 @@
          xml:id="chap-language-support">
  <title>Support for specific programming languages and frameworks</title>
  <para>
-  The <link linkend="chap-stdenv">standard build environment</link> makes it
-  easy to build typical Autotools-based packages with very little code. Any
-  other kind of package can be accomodated by overriding the appropriate phases
-  of <literal>stdenv</literal>. However, there are specialised functions in
-  Nixpkgs to easily build packages for other programming languages, such as
-  Perl or Haskell. These are described in this chapter.
+  The <link linkend="chap-stdenv">standard build environment</link> makes it easy to build typical Autotools-based packages with very little code. Any other kind of package can be accomodated by overriding the appropriate phases of <literal>stdenv</literal>. However, there are specialised functions in Nixpkgs to easily build packages for other programming languages, such as Perl or Haskell. These are described in this chapter.
  </para>
  <xi:include href="android.section.xml" />
  <xi:include href="beam.xml" />
diff --git a/doc/languages-frameworks/java.xml b/doc/languages-frameworks/java.xml
index 68a1a097984d..bf0fc4883922 100644
--- a/doc/languages-frameworks/java.xml
+++ b/doc/languages-frameworks/java.xml
@@ -15,37 +15,24 @@ stdenv.mkDerivation {
   buildPhase = "ant";
 }
 </programlisting>
-  Note that <varname>jdk</varname> is an alias for the OpenJDK (self-built
-  where available, or pre-built via Zulu). Platforms with OpenJDK not (yet) in
-  Nixpkgs (<literal>Aarch32</literal>, <literal>Aarch64</literal>) point to the
-  (unfree) <literal>oraclejdk</literal>.
+  Note that <varname>jdk</varname> is an alias for the OpenJDK (self-built where available, or pre-built via Zulu). Platforms with OpenJDK not (yet) in Nixpkgs (<literal>Aarch32</literal>, <literal>Aarch64</literal>) point to the (unfree) <literal>oraclejdk</literal>.
  </para>
 
  <para>
-  JAR files that are intended to be used by other packages should be installed
-  in <filename>$out/share/java</filename>. JDKs have a stdenv setup hook that
-  add any JARs in the <filename>share/java</filename> directories of the build
-  inputs to the <envar>CLASSPATH</envar> environment variable. For instance, if
-  the package <literal>libfoo</literal> installs a JAR named
-  <filename>foo.jar</filename> in its <filename>share/java</filename>
-  directory, and another package declares the attribute
+  JAR files that are intended to be used by other packages should be installed in <filename>$out/share/java</filename>. JDKs have a stdenv setup hook that add any JARs in the <filename>share/java</filename> directories of the build inputs to the <envar>CLASSPATH</envar> environment variable. For instance, if the package <literal>libfoo</literal> installs a JAR named <filename>foo.jar</filename> in its <filename>share/java</filename> directory, and another package declares the attribute
 <programlisting>
 buildInputs = [ libfoo ];
 nativeBuildInputs = [ jdk ];
 </programlisting>
-  then <envar>CLASSPATH</envar> will be set to
-  <filename>/nix/store/...-libfoo/share/java/foo.jar</filename>.
+  then <envar>CLASSPATH</envar> will be set to <filename>/nix/store/...-libfoo/share/java/foo.jar</filename>.
  </para>
 
  <para>
-  Private JARs should be installed in a location like
-  <filename>$out/share/<replaceable>package-name</replaceable></filename>.
+  Private JARs should be installed in a location like <filename>$out/share/<replaceable>package-name</replaceable></filename>.
  </para>
 
  <para>
-  If your Java package provides a program, you need to generate a wrapper
-  script to run it using the OpenJRE. You can use
-  <literal>makeWrapper</literal> for this:
+  If your Java package provides a program, you need to generate a wrapper script to run it using the OpenJRE. You can use <literal>makeWrapper</literal> for this:
 <programlisting>
 nativeBuildInputs = [ makeWrapper ];
 
@@ -56,30 +43,21 @@ installPhase =
       --add-flags "-cp $out/share/java/foo.jar org.foo.Main"
   '';
 </programlisting>
-  Note the use of <literal>jre</literal>, which is the part of the OpenJDK
-  package that contains the Java Runtime Environment. By using
-  <literal>${jre}/bin/java</literal> instead of
-  <literal>${jdk}/bin/java</literal>, you prevent your package from depending
-  on the JDK at runtime.
+  Note the use of <literal>jre</literal>, which is the part of the OpenJDK package that contains the Java Runtime Environment. By using <literal>${jre}/bin/java</literal> instead of <literal>${jdk}/bin/java</literal>, you prevent your package from depending on the JDK at runtime.
  </para>
 
  <para>
-  Note all JDKs passthru <literal>home</literal>, so if your application
-  requires environment variables like <envar>JAVA_HOME</envar> being set, that
-  can be done in a generic fashion with the <literal>--set</literal> argument
-  of <literal>makeWrapper</literal>:
+  Note all JDKs passthru <literal>home</literal>, so if your application requires environment variables like <envar>JAVA_HOME</envar> being set, that can be done in a generic fashion with the <literal>--set</literal> argument of <literal>makeWrapper</literal>:
 <programlisting>
 --set JAVA_HOME ${jdk.home}
 </programlisting>
  </para>
 
  <para>
-  It is possible to use a different Java compiler than <command>javac</command>
-  from the OpenJDK. For instance, to use the GNU Java Compiler:
+  It is possible to use a different Java compiler than <command>javac</command> from the OpenJDK. For instance, to use the GNU Java Compiler:
 <programlisting>
 nativeBuildInputs = [ gcj ant ];
 </programlisting>
-  Here, Ant will automatically use <command>gij</command> (the GNU Java
-  Runtime) instead of the OpenJRE.
+  Here, Ant will automatically use <command>gij</command> (the GNU Java Runtime) instead of the OpenJRE.
  </para>
 </section>
diff --git a/doc/languages-frameworks/lua.xml b/doc/languages-frameworks/lua.xml
index 5144bb24ff6e..bcca6b737539 100644
--- a/doc/languages-frameworks/lua.xml
+++ b/doc/languages-frameworks/lua.xml
@@ -4,18 +4,11 @@
  <title>Lua</title>
 
  <para>
-  Lua packages are built by the <varname>buildLuaPackage</varname> function.
-  This function is implemented in
-  <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules/generic/default.nix">
-  <filename>pkgs/development/lua-modules/generic/default.nix</filename></link>
-  and works similarly to <varname>buildPerlPackage</varname>. (See
-  <xref linkend="sec-language-perl"/> for details.)
+  Lua packages are built by the <varname>buildLuaPackage</varname> function. This function is implemented in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules/generic/default.nix"> <filename>pkgs/development/lua-modules/generic/default.nix</filename></link> and works similarly to <varname>buildPerlPackage</varname>. (See <xref linkend="sec-language-perl"/> for details.)
  </para>
 
  <para>
-  Lua packages are defined in
-  <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/lua-packages.nix"><filename>pkgs/top-level/lua-packages.nix</filename></link>.
-  Most of them are simple. For example:
+  Lua packages are defined in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/lua-packages.nix"><filename>pkgs/top-level/lua-packages.nix</filename></link>. Most of them are simple. For example:
 <programlisting>
 fileSystem = buildLuaPackage {
   name = "filesystem-1.6.2";
@@ -33,16 +26,11 @@ fileSystem = buildLuaPackage {
  </para>
 
  <para>
-  Though, more complicated package should be placed in a seperate file in
-  <link
+  Though, more complicated package should be placed in a seperate file in <link
   xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules"><filename>pkgs/development/lua-modules</filename></link>.
  </para>
 
  <para>
-  Lua packages accept additional parameter <varname>disabled</varname>, which
-  defines the condition of disabling package from luaPackages. For example, if
-  package has <varname>disabled</varname> assigned to <literal>lua.luaversion
-  != "5.1"</literal>, it will not be included in any luaPackages except
-  lua51Packages, making it only be built for lua 5.1.
+  Lua packages accept additional parameter <varname>disabled</varname>, which defines the condition of disabling package from luaPackages. For example, if package has <varname>disabled</varname> assigned to <literal>lua.luaversion != "5.1"</literal>, it will not be included in any luaPackages except lua51Packages, making it only be built for lua 5.1.
  </para>
 </section>
diff --git a/doc/languages-frameworks/ocaml.xml b/doc/languages-frameworks/ocaml.xml
index b7006ecba998..a0ea209b493c 100644
--- a/doc/languages-frameworks/ocaml.xml
+++ b/doc/languages-frameworks/ocaml.xml
@@ -4,35 +4,15 @@
  <title>OCaml</title>
 
  <para>
-  OCaml libraries should be installed in
-  <literal>$(out)/lib/ocaml/${ocaml.version}/site-lib/</literal>. Such
-  directories are automatically added to the <literal>$OCAMLPATH</literal>
-  environment variable when building another package that depends on them or
-  when opening a <literal>nix-shell</literal>.
+  OCaml libraries should be installed in <literal>$(out)/lib/ocaml/${ocaml.version}/site-lib/</literal>. Such directories are automatically added to the <literal>$OCAMLPATH</literal> environment variable when building another package that depends on them or when opening a <literal>nix-shell</literal>.
  </para>
 
  <para>
-  Given that most of the OCaml ecosystem is now built with dune, nixpkgs
-  includes a convenience build support function called
-  <literal>buildDunePackage</literal> that will build an OCaml package using
-  dune, OCaml and findlib and any additional dependencies provided as
-  <literal>buildInputs</literal> or <literal>propagatedBuildInputs</literal>.
+  Given that most of the OCaml ecosystem is now built with dune, nixpkgs includes a convenience build support function called <literal>buildDunePackage</literal> that will build an OCaml package using dune, OCaml and findlib and any additional dependencies provided as <literal>buildInputs</literal> or <literal>propagatedBuildInputs</literal>.
  </para>
 
  <para>
-  Here is a simple package example. It defines an (optional) attribute
-  <literal>minimumOCamlVersion</literal> that will be used to throw a
-  descriptive evaluation error if building with an older OCaml is attempted. It
-  uses the <literal>fetchFromGitHub</literal> fetcher to get its source. It
-  sets the <literal>doCheck</literal> (optional) attribute to
-  <literal>true</literal> which means that tests will be run with <literal>dune
-  runtest -p angstrom</literal> after the build (<literal>dune build -p
-  angstrom</literal>) is complete. It uses <literal>alcotest</literal> as a
-  build input (because it is needed to run the tests) and
-  <literal>bigstringaf</literal> and <literal>result</literal> as propagated
-  build inputs (thus they will also be available to libraries depending on this
-  library). The library will be installed using the
-  <literal>angstrom.install</literal> file that dune generates.
+  Here is a simple package example. It defines an (optional) attribute <literal>minimumOCamlVersion</literal> that will be used to throw a descriptive evaluation error if building with an older OCaml is attempted. It uses the <literal>fetchFromGitHub</literal> fetcher to get its source. It sets the <literal>doCheck</literal> (optional) attribute to <literal>true</literal> which means that tests will be run with <literal>dune runtest -p angstrom</literal> after the build (<literal>dune build -p angstrom</literal>) is complete. It uses <literal>alcotest</literal> as a build input (because it is needed to run the tests) and <literal>bigstringaf</literal> and <literal>result</literal> as propagated build inputs (thus they will also be available to libraries depending on this library). The library will be installed using the <literal>angstrom.install</literal> file that dune generates.
  </para>
 
 <programlisting>
@@ -65,11 +45,7 @@ buildDunePackage rec {
 </programlisting>
 
  <para>
-  Here is a second example, this time using a source archive generated with
-  <literal>dune-release</literal>. It is a good idea to use this archive when
-  it is available as it will usually contain substituted variables such as a
-  <literal>%%VERSION%%</literal> field. This library does not depend on any
-  other OCaml library and no tests are run after building it.
+  Here is a second example, this time using a source archive generated with <literal>dune-release</literal>. It is a good idea to use this archive when it is available as it will usually contain substituted variables such as a <literal>%%VERSION%%</literal> field. This library does not depend on any other OCaml library and no tests are run after building it.
  </para>
 
 <programlisting>
diff --git a/doc/languages-frameworks/perl.xml b/doc/languages-frameworks/perl.xml
index d5911cf67fd7..d9b6b2721c67 100644
--- a/doc/languages-frameworks/perl.xml
+++ b/doc/languages-frameworks/perl.xml
@@ -4,24 +4,13 @@
  <title>Perl</title>
 
  <para>
-  Nixpkgs provides a function <varname>buildPerlPackage</varname>, a generic
-  package builder function for any Perl package that has a standard
-  <varname>Makefile.PL</varname>. It’s implemented in
-  <link
+  Nixpkgs provides a function <varname>buildPerlPackage</varname>, a generic package builder function for any Perl package that has a standard <varname>Makefile.PL</varname>. It’s implemented in <link
 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>.
  </para>
 
  <para>
-  Perl packages from CPAN are defined in
-  <link
-xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>,
-  rather than <filename>pkgs/all-packages.nix</filename>. Most Perl packages
-  are so straight-forward to build that they are defined here directly, rather
-  than having a separate function for each package called from
-  <filename>perl-packages.nix</filename>. However, more complicated packages
-  should be put in a separate file, typically in
-  <filename>pkgs/development/perl-modules</filename>. Here is an example of the
-  former:
+  Perl packages from CPAN are defined in <link
+xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>, rather than <filename>pkgs/all-packages.nix</filename>. Most Perl packages are so straight-forward to build that they are defined here directly, rather than having a separate function for each package called from <filename>perl-packages.nix</filename>. However, more complicated packages should be put in a separate file, typically in <filename>pkgs/development/perl-modules</filename>. Here is an example of the former:
 <programlisting>
 ClassC3 = buildPerlPackage rec {
   name = "Class-C3-0.21";
@@ -31,32 +20,22 @@ ClassC3 = buildPerlPackage rec {
   };
 };
 </programlisting>
-  Note the use of <literal>mirror://cpan/</literal>, and the
-  <literal>${name}</literal> in the URL definition to ensure that the name
-  attribute is consistent with the source that we’re actually downloading.
-  Perl packages are made available in <filename>all-packages.nix</filename>
-  through the variable <varname>perlPackages</varname>. For instance, if you
-  have a package that needs <varname>ClassC3</varname>, you would typically
-  write
+  Note the use of <literal>mirror://cpan/</literal>, and the <literal>${name}</literal> in the URL definition to ensure that the name attribute is consistent with the source that we’re actually downloading. Perl packages are made available in <filename>all-packages.nix</filename> through the variable <varname>perlPackages</varname>. For instance, if you have a package that needs <varname>ClassC3</varname>, you would typically write
 <programlisting>
 foo = import ../path/to/foo.nix {
   inherit stdenv fetchurl ...;
   inherit (perlPackages) ClassC3;
 };
 </programlisting>
-  in <filename>all-packages.nix</filename>. You can test building a Perl
-  package as follows:
+  in <filename>all-packages.nix</filename>. You can test building a Perl package as follows:
 <screen>
 <prompt>$ </prompt>nix-build -A perlPackages.ClassC3
 </screen>
-  <varname>buildPerlPackage</varname> adds <literal>perl-</literal> to the
-  start of the name attribute, so the package above is actually called
-  <literal>perl-Class-C3-0.21</literal>. So to install it, you can say:
+  <varname>buildPerlPackage</varname> adds <literal>perl-</literal> to the start of the name attribute, so the package above is actually called <literal>perl-Class-C3-0.21</literal>. So to install it, you can say:
 <screen>
 <prompt>$ </prompt>nix-env -i perl-Class-C3
 </screen>
-  (Of course you can also install using the attribute name: <literal>nix-env -i
-  -A perlPackages.ClassC3</literal>.)
+  (Of course you can also install using the attribute name: <literal>nix-env -i -A perlPackages.ClassC3</literal>.)
  </para>
 
  <para>
@@ -64,40 +43,24 @@ foo = import ../path/to/foo.nix {
   <orderedlist>
    <listitem>
     <para>
-     In the configure phase, it calls <literal>perl Makefile.PL</literal> to
-     generate a Makefile. You can set the variable
-     <varname>makeMakerFlags</varname> to pass flags to
-     <filename>Makefile.PL</filename>
+     In the configure phase, it calls <literal>perl Makefile.PL</literal> to generate a Makefile. You can set the variable <varname>makeMakerFlags</varname> to pass flags to <filename>Makefile.PL</filename>
     </para>
    </listitem>
    <listitem>
     <para>
-     It adds the contents of the <envar>PERL5LIB</envar> environment variable
-     to <literal>#! .../bin/perl</literal> line of Perl scripts as
-     <literal>-I<replaceable>dir</replaceable></literal> flags. This ensures
-     that a script can find its dependencies. (This can cause this shebang line
-     to become too long for Darwin to handle; see the note below.)
+     It adds the contents of the <envar>PERL5LIB</envar> environment variable to <literal>#! .../bin/perl</literal> line of Perl scripts as <literal>-I<replaceable>dir</replaceable></literal> flags. This ensures that a script can find its dependencies. (This can cause this shebang line to become too long for Darwin to handle; see the note below.)
     </para>
    </listitem>
    <listitem>
     <para>
-     In the fixup phase, it writes the propagated build inputs
-     (<varname>propagatedBuildInputs</varname>) to the file
-     <filename>$out/nix-support/propagated-user-env-packages</filename>.
-     <command>nix-env</command> recursively installs all packages listed in
-     this file when you install a package that has it. This ensures that a Perl
-     package can find its dependencies.
+     In the fixup phase, it writes the propagated build inputs (<varname>propagatedBuildInputs</varname>) to the file <filename>$out/nix-support/propagated-user-env-packages</filename>. <command>nix-env</command> recursively installs all packages listed in this file when you install a package that has it. This ensures that a Perl package can find its dependencies.
     </para>
    </listitem>
   </orderedlist>
  </para>
 
  <para>
-  <varname>buildPerlPackage</varname> is built on top of
-  <varname>stdenv</varname>, so everything can be customised in the usual way.
-  For instance, the <literal>BerkeleyDB</literal> module has a
-  <varname>preConfigure</varname> hook to generate a configuration file used by
-  <filename>Makefile.PL</filename>:
+  <varname>buildPerlPackage</varname> is built on top of <varname>stdenv</varname>, so everything can be customised in the usual way. For instance, the <literal>BerkeleyDB</literal> module has a <varname>preConfigure</varname> hook to generate a configuration file used by <filename>Makefile.PL</filename>:
 <programlisting>
 { buildPerlPackage, fetchurl, db }:
 
@@ -118,12 +81,7 @@ buildPerlPackage rec {
  </para>
 
  <para>
-  Dependencies on other Perl packages can be specified in the
-  <varname>buildInputs</varname> and <varname>propagatedBuildInputs</varname>
-  attributes. If something is exclusively a build-time dependency, use
-  <varname>buildInputs</varname>; if it’s (also) a runtime dependency, use
-  <varname>propagatedBuildInputs</varname>. For instance, this builds a Perl
-  module that has runtime dependencies on a bunch of other modules:
+  Dependencies on other Perl packages can be specified in the <varname>buildInputs</varname> and <varname>propagatedBuildInputs</varname> attributes. If something is exclusively a build-time dependency, use <varname>buildInputs</varname>; if it’s (also) a runtime dependency, use <varname>propagatedBuildInputs</varname>. For instance, this builds a Perl module that has runtime dependencies on a bunch of other modules:
 <programlisting>
 ClassC3Componentised = buildPerlPackage rec {
   name = "Class-C3-Componentised-1.0004";
@@ -139,11 +97,7 @@ ClassC3Componentised = buildPerlPackage rec {
  </para>
 
  <para>
-  On Darwin, if a script has too many
-  <literal>-I<replaceable>dir</replaceable></literal> flags in its first line
-  (its “shebang line”), it will not run. This can be worked around by
-  calling the <literal>shortenPerlShebang</literal> function from the
-  <literal>postInstall</literal> phase:
+  On Darwin, if a script has too many <literal>-I<replaceable>dir</replaceable></literal> flags in its first line (its “shebang line”), it will not run. This can be worked around by calling the <literal>shortenPerlShebang</literal> function from the <literal>postInstall</literal> phase:
 <programlisting>
 { stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }:
 
@@ -162,20 +116,14 @@ ImageExifTool = buildPerlPackage {
   '';
 };
 </programlisting>
-  This will remove the <literal>-I</literal> flags from the shebang line,
-  rewrite them in the <literal>use lib</literal> form, and put them on the next
-  line instead. This function can be given any number of Perl scripts as
-  arguments; it will modify them in-place.
+  This will remove the <literal>-I</literal> flags from the shebang line, rewrite them in the <literal>use lib</literal> form, and put them on the next line instead. This function can be given any number of Perl scripts as arguments; it will modify them in-place.
  </para>
 
  <section xml:id="ssec-generation-from-CPAN">
   <title>Generation from CPAN</title>
 
   <para>
-   Nix expressions for Perl packages can be generated (almost) automatically
-   from CPAN. This is done by the program
-   <command>nix-generate-from-cpan</command>, which can be installed as
-   follows:
+   Nix expressions for Perl packages can be generated (almost) automatically from CPAN. This is done by the program <command>nix-generate-from-cpan</command>, which can be installed as follows:
   </para>
 
 <screen>
@@ -183,9 +131,7 @@ ImageExifTool = buildPerlPackage {
 </screen>
 
   <para>
-   This program takes a Perl module name, looks it up on CPAN, fetches and
-   unpacks the corresponding package, and prints a Nix expression on standard
-   output. For example:
+   This program takes a Perl module name, looks it up on CPAN, fetches and unpacks the corresponding package, and prints a Nix expression on standard output. For example:
 <screen>
 <prompt>$ </prompt>nix-generate-from-cpan XML::Simple
   XMLSimple = buildPerlPackage rec {
@@ -201,9 +147,7 @@ ImageExifTool = buildPerlPackage {
     };
   };
 </screen>
-   The output can be pasted into
-   <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you
-   need it.
+   The output can be pasted into <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you need it.
   </para>
  </section>
 
@@ -211,13 +155,7 @@ ImageExifTool = buildPerlPackage {
   <title>Cross-compiling modules</title>
 
   <para>
-   Nixpkgs has experimental support for cross-compiling Perl modules. In many
-   cases, it will just work out of the box, even for modules with native
-   extensions. Sometimes, however, the Makefile.PL for a module may
-   (indirectly) import a native module. In that case, you will need to make a
-   stub for that module that will satisfy the Makefile.PL and install it into
-   <filename>lib/perl5/site_perl/cross_perl/${perl.version}</filename>. See the
-   <varname>postInstall</varname> for <varname>DBI</varname> for an example.
+   Nixpkgs has experimental support for cross-compiling Perl modules. In many cases, it will just work out of the box, even for modules with native extensions. Sometimes, however, the Makefile.PL for a module may (indirectly) import a native module. In that case, you will need to make a stub for that module that will satisfy the Makefile.PL and install it into <filename>lib/perl5/site_perl/cross_perl/${perl.version}</filename>. See the <varname>postInstall</varname> for <varname>DBI</varname> for an example.
   </para>
  </section>
 </section>
diff --git a/doc/languages-frameworks/qt.xml b/doc/languages-frameworks/qt.xml
index d6f3314ab08d..8d97de504ad3 100644
--- a/doc/languages-frameworks/qt.xml
+++ b/doc/languages-frameworks/qt.xml
@@ -4,11 +4,7 @@
  <title>Qt</title>
 
  <para>
-  This section describes the differences between Nix expressions for Qt
-  libraries and applications and Nix expressions for other C++ software. Some
-  knowledge of the latter is assumed. There are primarily two problems which
-  the Qt infrastructure is designed to address: ensuring consistent versioning
-  of all dependencies and finding dependencies at runtime.
+  This section describes the differences between Nix expressions for Qt libraries and applications and Nix expressions for other C++ software. Some knowledge of the latter is assumed. There are primarily two problems which the Qt infrastructure is designed to address: ensuring consistent versioning of all dependencies and finding dependencies at runtime.
  </para>
 
  <example xml:id='qt-default-nix'>
@@ -28,38 +24,26 @@ mkDerivation { <co xml:id='qt-default-nix-co-2' />
  <calloutlist>
   <callout arearefs='qt-default-nix-co-1'>
    <para>
-    Import <literal>mkDerivation</literal> and Qt (such as
-    <literal>qtbase</literal> modules directly. <emphasis>Do not</emphasis>
-    import Qt package sets; the Qt versions of dependencies may not be
-    coherent, causing build and runtime failures.
+    Import <literal>mkDerivation</literal> and Qt (such as <literal>qtbase</literal> modules directly. <emphasis>Do not</emphasis> import Qt package sets; the Qt versions of dependencies may not be coherent, causing build and runtime failures.
    </para>
   </callout>
   <callout arearefs='qt-default-nix-co-2'>
    <para>
-    Use <literal>mkDerivation</literal> instead of
-    <literal>stdenv.mkDerivation</literal>. <literal>mkDerivation</literal> is
-    a wrapper around <literal>stdenv.mkDerivation</literal> which applies some
-    Qt-specific settings. This deriver accepts the same arguments as
-    <literal>stdenv.mkDerivation</literal>; refer to
-    <xref linkend='chap-stdenv' /> for details.
+    Use <literal>mkDerivation</literal> instead of <literal>stdenv.mkDerivation</literal>. <literal>mkDerivation</literal> is a wrapper around <literal>stdenv.mkDerivation</literal> which applies some Qt-specific settings. This deriver accepts the same arguments as <literal>stdenv.mkDerivation</literal>; refer to <xref linkend='chap-stdenv' /> for details.
    </para>
    <para>
-    To use another deriver instead of <literal>stdenv.mkDerivation</literal>,
-    use <literal>mkDerivationWith</literal>:
+    To use another deriver instead of <literal>stdenv.mkDerivation</literal>, use <literal>mkDerivationWith</literal>:
 <programlisting>
 mkDerivationWith myDeriver {
   # ...
 }
 </programlisting>
-    If you cannot use <literal>mkDerivationWith</literal>, please refer to
-    <xref linkend='qt-runtime-dependencies' />.
+    If you cannot use <literal>mkDerivationWith</literal>, please refer to <xref linkend='qt-runtime-dependencies' />.
    </para>
   </callout>
   <callout arearefs='qt-default-nix-co-3'>
    <para>
-    <literal>mkDerivation</literal> accepts the same arguments as
-    <literal>stdenv.mkDerivation</literal>, such as
-    <literal>buildInputs</literal>.
+    <literal>mkDerivation</literal> accepts the same arguments as <literal>stdenv.mkDerivation</literal>, such as <literal>buildInputs</literal>.
    </para>
   </callout>
  </calloutlist>
@@ -67,10 +51,7 @@ mkDerivationWith myDeriver {
  <formalpara xml:id='qt-runtime-dependencies'>
   <title>Locating runtime dependencies</title>
   <para>
-   Qt applications need to be wrapped to find runtime dependencies. If you
-   cannot use <literal>mkDerivation</literal> or
-   <literal>mkDerivationWith</literal> above, include
-   <literal>wrapQtAppsHook</literal> in <literal>nativeBuildInputs</literal>:
+   Qt applications need to be wrapped to find runtime dependencies. If you cannot use <literal>mkDerivation</literal> or <literal>mkDerivationWith</literal> above, include <literal>wrapQtAppsHook</literal> in <literal>nativeBuildInputs</literal>:
 <programlisting>
 stdenv.mkDerivation {
   # ...
@@ -82,9 +63,7 @@ stdenv.mkDerivation {
  </formalpara>
 
  <para>
-  Entries added to <literal>qtWrapperArgs</literal> are used to modify the
-  wrappers created by <literal>wrapQtAppsHook</literal>. The entries are passed
-  as arguments to <xref linkend='fun-wrapProgram' />.
+  Entries added to <literal>qtWrapperArgs</literal> are used to modify the wrappers created by <literal>wrapQtAppsHook</literal>. The entries are passed as arguments to <xref linkend='fun-wrapProgram' />.
 <programlisting>
 mkDerivation {
   # ...
@@ -95,10 +74,7 @@ mkDerivation {
  </para>
 
  <para>
-  Set <literal>dontWrapQtApps</literal> to stop applications from being wrapped
-  automatically. It is required to wrap applications manually with
-  <literal>wrapQtApp</literal>, using the syntax of
-  <xref linkend='fun-wrapProgram' />:
+  Set <literal>dontWrapQtApps</literal> to stop applications from being wrapped automatically. It is required to wrap applications manually with <literal>wrapQtApp</literal>, using the syntax of <xref linkend='fun-wrapProgram' />:
 <programlisting>
 mkDerivation {
   # ...
@@ -113,17 +89,12 @@ mkDerivation {
 
  <note>
   <para>
-   <literal>wrapQtAppsHook</literal> ignores files that are non-ELF
-   executables. This means that scripts won't be automatically wrapped so
-   you'll need to manually wrap them as previously mentioned. An example of
-   when you'd always need to do this is with Python applications that use PyQT.
+   <literal>wrapQtAppsHook</literal> ignores files that are non-ELF executables. This means that scripts won't be automatically wrapped so you'll need to manually wrap them as previously mentioned. An example of when you'd always need to do this is with Python applications that use PyQT.
   </para>
  </note>
 
  <para>
-  Libraries are built with every available version of Qt. Use the
-  <literal>meta.broken</literal> attribute to disable the package for
-  unsupported Qt versions:
+  Libraries are built with every available version of Qt. Use the <literal>meta.broken</literal> attribute to disable the package for unsupported Qt versions:
 <programlisting>
 mkDerivation {
   # ...
@@ -137,9 +108,7 @@ mkDerivation {
  <formalpara>
   <title>Adding a library to Nixpkgs</title>
   <para>
-   Add a Qt library to <filename>all-packages.nix</filename> by adding it to
-   the collection inside <literal>mkLibsForQt5</literal>. This ensures that the
-   library is built with every available version of Qt as needed.
+   Add a Qt library to <filename>all-packages.nix</filename> by adding it to the collection inside <literal>mkLibsForQt5</literal>. This ensures that the library is built with every available version of Qt as needed.
    <example xml:id='qt-library-all-packages-nix'>
     <title>Adding a Qt library to <filename>all-packages.nix</filename></title>
 <programlisting>
@@ -162,10 +131,7 @@ mkDerivation {
  <formalpara>
   <title>Adding an application to Nixpkgs</title>
   <para>
-   Add a Qt application to <filename>all-packages.nix</filename> using
-   <literal>libsForQt5.callPackage</literal> instead of the usual
-   <literal>callPackage</literal>. The former ensures that all dependencies are
-   built with the same version of Qt.
+   Add a Qt application to <filename>all-packages.nix</filename> using <literal>libsForQt5.callPackage</literal> instead of the usual <literal>callPackage</literal>. The former ensures that all dependencies are built with the same version of Qt.
    <example xml:id='qt-application-all-packages-nix'>
     <title>Adding a Qt application to <filename>all-packages.nix</filename></title>
 <programlisting>
diff --git a/doc/languages-frameworks/ruby.xml b/doc/languages-frameworks/ruby.xml
index df4e5acb22cb..b28745fd6e27 100644
--- a/doc/languages-frameworks/ruby.xml
+++ b/doc/languages-frameworks/ruby.xml
@@ -4,11 +4,7 @@
  <title>Ruby</title>
 
  <para>
-  There currently is support to bundle applications that are packaged as Ruby
-  gems. The utility "bundix" allows you to write a
-  <filename>Gemfile</filename>, let bundler create a
-  <filename>Gemfile.lock</filename>, and then convert this into a nix
-  expression that contains all Gem dependencies automatically.
+  There currently is support to bundle applications that are packaged as Ruby gems. The utility "bundix" allows you to write a <filename>Gemfile</filename>, let bundler create a <filename>Gemfile.lock</filename>, and then convert this into a nix expression that contains all Gem dependencies automatically.
  </para>
 
  <para>
@@ -45,9 +41,7 @@ bundlerEnv rec {
 </screen>
 
  <para>
-  Please check in the <filename>Gemfile</filename>,
-  <filename>Gemfile.lock</filename> and the <filename>gemset.nix</filename> so
-  future updates can be run easily.
+  Please check in the <filename>Gemfile</filename>, <filename>Gemfile.lock</filename> and the <filename>gemset.nix</filename> so future updates can be run easily.
  </para>
 
  <para>
@@ -62,10 +56,7 @@ $ nix-shell -p bundix --run 'bundix'
 </screen>
 
  <para>
-  For tools written in Ruby - i.e. where the desire is to install a package and
-  then execute e.g. <command>rake</command> at the command line, there is an
-  alternative builder called <literal>bundlerApp</literal>. Set up the
-  <filename>gemset.nix</filename> the same way, and then, for example:
+  For tools written in Ruby - i.e. where the desire is to install a package and then execute e.g. <command>rake</command> at the command line, there is an alternative builder called <literal>bundlerApp</literal>. Set up the <filename>gemset.nix</filename> the same way, and then, for example:
  </para>
 
 <screen>
@@ -87,29 +78,11 @@ bundlerApp {
 </screen>
 
  <para>
-  The chief advantage of <literal>bundlerApp</literal> over
-  <literal>bundlerEnv</literal> is the executables introduced in the
-  environment are precisely those selected in the <literal>exes</literal> list,
-  as opposed to <literal>bundlerEnv</literal> which adds all the executables
-  made available by gems in the gemset, which can mean e.g.
-  <command>rspec</command> or <command>rake</command> in unpredictable versions
-  available from various packages.
+  The chief advantage of <literal>bundlerApp</literal> over <literal>bundlerEnv</literal> is the executables introduced in the environment are precisely those selected in the <literal>exes</literal> list, as opposed to <literal>bundlerEnv</literal> which adds all the executables made available by gems in the gemset, which can mean e.g. <command>rspec</command> or <command>rake</command> in unpredictable versions available from various packages.
  </para>
 
  <para>
-  Resulting derivations for both builders also have two helpful attributes,
-  <literal>env</literal> and <literal>wrappedRuby</literal>. The first one
-  allows one to quickly drop into <command>nix-shell</command> with the
-  specified environment present. E.g. <command>nix-shell -A sensu.env</command>
-  would give you an environment with Ruby preset so it has all the libraries
-  necessary for <literal>sensu</literal> in its paths. The second one can be
-  used to make derivations from custom Ruby scripts which have
-  <filename>Gemfile</filename>s with their dependencies specified. It is a
-  derivation with <command>ruby</command> wrapped so it can find all the needed
-  dependencies. For example, to make a derivation <literal>my-script</literal>
-  for a <filename>my-script.rb</filename> (which should be placed in
-  <filename>bin</filename>) you should run <command>bundix</command> as
-  specified above and then use <literal>bundlerEnv</literal> like this:
+  Resulting derivations for both builders also have two helpful attributes, <literal>env</literal> and <literal>wrappedRuby</literal>. The first one allows one to quickly drop into <command>nix-shell</command> with the specified environment present. E.g. <command>nix-shell -A sensu.env</command> would give you an environment with Ruby preset so it has all the libraries necessary for <literal>sensu</literal> in its paths. The second one can be used to make derivations from custom Ruby scripts which have <filename>Gemfile</filename>s with their dependencies specified. It is a derivation with <command>ruby</command> wrapped so it can find all the needed dependencies. For example, to make a derivation <literal>my-script</literal> for a <filename>my-script.rb</filename> (which should be placed in <filename>bin</filename>) you should run <command>bundix</command> as specified above and then use <literal>bundlerEnv</literal> like this:
  </para>
 
 <programlisting>
diff --git a/doc/languages-frameworks/texlive.xml b/doc/languages-frameworks/texlive.xml
index 97f274933bef..7876cc213b66 100644
--- a/doc/languages-frameworks/texlive.xml
+++ b/doc/languages-frameworks/texlive.xml
@@ -4,8 +4,7 @@
  <title>TeX Live</title>
 
  <para>
-  Since release 15.09 there is a new TeX Live packaging that lives entirely
-  under attribute <varname>texlive</varname>.
+  Since release 15.09 there is a new TeX Live packaging that lives entirely under attribute <varname>texlive</varname>.
  </para>
 
  <section xml:id="sec-language-texlive-users-guide">
@@ -14,28 +13,23 @@
   <itemizedlist>
    <listitem>
     <para>
-     For basic usage just pull <varname>texlive.combined.scheme-basic</varname>
-     for an environment with basic LaTeX support.
+     For basic usage just pull <varname>texlive.combined.scheme-basic</varname> for an environment with basic LaTeX support.
     </para>
    </listitem>
    <listitem>
     <para>
-     It typically won't work to use separately installed packages together.
-     Instead, you can build a custom set of packages like this:
+     It typically won't work to use separately installed packages together. Instead, you can build a custom set of packages like this:
 <programlisting>
 texlive.combine {
   inherit (texlive) scheme-small collection-langkorean algorithms cm-super;
 }
 </programlisting>
-     There are all the schemes, collections and a few thousand packages, as
-     defined upstream (perhaps with tiny differences).
+     There are all the schemes, collections and a few thousand packages, as defined upstream (perhaps with tiny differences).
     </para>
    </listitem>
    <listitem>
     <para>
-     By default you only get executables and files needed during runtime, and a
-     little documentation for the core packages. To change that, you need to
-     add <varname>pkgFilter</varname> function to <varname>combine</varname>.
+     By default you only get executables and files needed during runtime, and a little documentation for the core packages. To change that, you need to add <varname>pkgFilter</varname> function to <varname>combine</varname>.
 <programlisting>
 texlive.combine {
   # inherit (texlive) whatever-you-want;
@@ -59,10 +53,7 @@ nix-repl> texlive.collection-<TAB>
    </listitem>
    <listitem>
     <para>
-     Note that the wrapper assumes that the result has a chance to be useful.
-     For example, the core executables should be present, as well as some core
-     data files. The supported way of ensuring this is by including some
-     scheme, for example <varname>scheme-basic</varname>, into the combination.
+     Note that the wrapper assumes that the result has a chance to be useful. For example, the core executables should be present, as well as some core data files. The supported way of ensuring this is by including some scheme, for example <varname>scheme-basic</varname>, into the combination.
     </para>
    </listitem>
   </itemizedlist>
@@ -84,14 +75,12 @@ nix-repl> texlive.collection-<TAB>
    </listitem>
    <listitem>
     <para>
-     feature/bug: when a package is rejected by <varname>pkgFilter</varname>,
-     its dependencies are still propagated;
+     feature/bug: when a package is rejected by <varname>pkgFilter</varname>, its dependencies are still propagated;
     </para>
    </listitem>
    <listitem>
     <para>
-     in case of any bugs or feature requests, file a github issue or better a
-     pull request and /cc @vcunat.
+     in case of any bugs or feature requests, file a github issue or better a pull request and /cc @vcunat.
     </para>
    </listitem>
   </itemizedlist>