nixpkgs docs: format =)

11 files changed, 912 insertions, 838 deletions

diff --git a/doc/languages-frameworks/beam.xml b/doc/languages-frameworks/beam.xml
index 1a18ed27237c..ac7a83ed4265 100644
--- a/doc/languages-frameworks/beam.xml
+++ b/doc/languages-frameworks/beam.xml
@@ -1,124 +1,137 @@
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="sec-beam">
+ <title>BEAM Languages (Erlang, Elixir &amp; LFE)</title>
 
-  <title>BEAM Languages (Erlang, Elixir &amp; LFE)</title>
-  <section xml:id="beam-introduction">
-    <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.
-    </para>
-  </section>
-  <section xml:id="beam-structure">
-    <title>Structure</title>
-    <para>
-      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>).
-        </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>.
-        </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>.
-    </para>
+ <section xml:id="beam-introduction">
+  <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.
+  </para>
+ </section>
+
+ <section xml:id="beam-structure">
+  <title>Structure</title>
+
+  <para>
+   All BEAM-related expressions are available via the top-level
+   <literal>beam</literal> attribute, which includes:
+  </para>
+
+  <itemizedlist>
+   <listitem>
     <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>.
+     <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>
-      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>.
+     <literal>packages</literal>: a set of package sets, each compiled with a
+     specific Erlang/OTP version, e.g.
+     <literal>beam.packages.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.
-    </para>
-  </section>
-  <section xml:id="build-tools">
+   </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>.
+  </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>.
+  </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>.
+  </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.
+  </para>
+ </section>
+
+ <section xml:id="build-tools">
   <title>Build Tools</title>
+
   <section xml:id="build-tools-rebar3">
-    <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:
-      <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.
-          </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
+   <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:
+    <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.
+      </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
             linkend="rebar3-packages"/>.
-          </para>
-        </listitem>
-      </itemizedlist>
-    </para>
+      </para>
+     </listitem>
+    </itemizedlist>
+   </para>
   </section>
+
   <section xml:id="build-tools-other">
-    <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.
-    </para>
+   <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.
+   </para>
   </section>
-</section>
+ </section>
 
-<section xml:id="how-to-install-beam-packages">
+ <section xml:id="how-to-install-beam-packages">
   <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>
 
-  <programlisting>
+<programlisting>
 $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -qaP -A beamPackages
 beamPackages.esqlite    esqlite-0.2.1
 beamPackages.goldrush   goldrush-0.1.7
@@ -128,34 +141,43 @@ beamPackages.lager      lager-3.0.2
 beamPackages.meck       meck-0.8.3
 beamPackages.rebar3-pc  pc-1.1.0
   </programlisting>
+
   <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>
-  <programlisting>
+
+<programlisting>
 $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
   </programlisting>
+
   <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>
-<section xml:id="packaging-beam-applications">
+ </section>
+
+ <section xml:id="packaging-beam-applications">
   <title>Packaging BEAM Applications</title>
+
   <section  xml:id="packaging-erlang-applications">
-    <title>Erlang Applications</title>
-    <section xml:id="rebar3-packages">
-      <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:
-      </para>
-      <programlisting>
+   <title>Erlang Applications</title>
+
+   <section xml:id="rebar3-packages">
+    <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:
+    </para>
+
+<programlisting>
         { stdenv, fetchFromGitHub, buildRebar3, ibrowse, jsx, erlware_commons }:
 
         buildRebar3 rec {
@@ -172,33 +194,40 @@ $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
           beamDeps = [ ibrowse jsx erlware_commons ];
         }
       </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>.
-      </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.
-      </para>
-      <para>
-        If a package needs to compile native code via Rebar3's port compilation
-        mechanism, add <literal>compilePort = true;</literal> to the derivation.
-      </para>
-    </section>
-    <section xml:id="erlang-mk-packages">
-      <title>Erlang.mk Packages</title>
-      <para>
-        Erlang.mk functions similarly to Rebar3, except we use
-        <literal>buildErlangMk</literal> instead of
-        <literal>buildRebar3</literal>.
-      </para>
-      <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>.
+    </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.
+    </para>
+
+    <para>
+     If a package needs to compile native code via Rebar3's port compilation
+     mechanism, add <literal>compilePort = true;</literal> to the derivation.
+    </para>
+   </section>
+
+   <section xml:id="erlang-mk-packages">
+    <title>Erlang.mk Packages</title>
+
+    <para>
+     Erlang.mk functions similarly to Rebar3, except we use
+     <literal>buildErlangMk</literal> instead of
+     <literal>buildRebar3</literal>.
+    </para>
+
+<programlisting>
         { buildErlangMk, fetchHex, cowlib, ranch }:
 
         buildErlangMk {
@@ -222,14 +251,17 @@ $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
           };
         }
       </programlisting>
-    </section>
-    <section xml:id="mix-packages">
-      <title>Mix Packages</title>
-      <para>
-        Mix functions similarly to Rebar3, except we use
-        <literal>buildMix</literal> instead of <literal>buildRebar3</literal>.
-      </para>
-      <programlisting>
+   </section>
+
+   <section xml:id="mix-packages">
+    <title>Mix Packages</title>
+
+    <para>
+     Mix functions similarly to Rebar3, except we use
+     <literal>buildMix</literal> instead of <literal>buildRebar3</literal>.
+    </para>
+
+<programlisting>
         { buildMix, fetchHex, plug, absinthe }:
 
         buildMix {
@@ -253,10 +285,12 @@ $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
           };
         }
       </programlisting>
-      <para>
-        Alternatively, we can use <literal>buildHex</literal> as a shortcut:
-      </para>
-      <programlisting>
+
+    <para>
+     Alternatively, we can use <literal>buildHex</literal> as a shortcut:
+    </para>
+
+<programlisting>
         { buildHex, buildMix, plug, absinthe }:
 
         buildHex {
@@ -278,21 +312,25 @@ $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
          };
        }
       </programlisting>
-    </section>
+   </section>
   </section>
-</section>
-<section xml:id="how-to-develop">
+ </section>
+
+ <section xml:id="how-to-develop">
   <title>How to Develop</title>
+
   <section xml:id="accessing-an-environment">
-    <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:
-    </para>
-    <programlisting>
+   <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:
+   </para>
+
+<programlisting>
       $ nix-shell -A beamPackages.ibrowse.env --run "erl"
       Erlang/OTP 18 [erts-7.0] [source] [64-bit] [smp:4:4] [async-threads:10] [hipe] [kernel-poll:false]
 
@@ -333,22 +371,25 @@ $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
       ok
       2>
     </programlisting>
-    <para>
-      Notice the <literal>-A beamPackages.ibrowse.env</literal>. That is the key
-      to this functionality.
-    </para>
+
+   <para>
+    Notice the <literal>-A beamPackages.ibrowse.env</literal>. That is the key
+    to this functionality.
+   </para>
   </section>
+
   <section xml:id="creating-a-shell">
-    <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.
-    </para>
-    <programlisting>
+   <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.
+   </para>
+
+<programlisting>
 { pkgs ? import &quot;&lt;nixpkgs&quot;&gt; {} }:
 
 with pkgs;
@@ -368,13 +409,16 @@ in
 
   drv
     </programlisting>
-    <section xml:id="building-in-a-shell">
+
+   <section xml:id="building-in-a-shell">
     <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>
+
+<programlisting>
 # =============================================================================
 # Variables
 # =============================================================================
@@ -431,44 +475,54 @@ analyze: build plt
         $(NIX_SHELL) --run "mix dialyzer --no-compile"
 
     </programlisting>
+
     <para>
-      Using a <literal>shell.nix</literal> as described (see <xref
+     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.
+     <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>
-</section>
-</section>
-<section xml:id="generating-packages-from-hex-with-hex2nix">
+ </section>
+
+ <section xml:id="generating-packages-from-hex-with-hex2nix">
   <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.
-    </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:
-    </para>
-    <programlisting>
+   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:
+  </para>
+
+<programlisting>
 $ nix-build -A beamPackages
     </programlisting>
-    <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.
-    </para>
-</section>
+
+  <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.
+  </para>
+ </section>
 </section>
diff --git a/doc/languages-frameworks/bower.xml b/doc/languages-frameworks/bower.xml
index 742d3c2e9fe5..db7536cdc14e 100644
--- a/doc/languages-frameworks/bower.xml
+++ b/doc/languages-frameworks/bower.xml
@@ -1,40 +1,37 @@
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="sec-bower">
-
-<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.
-</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.
-</para>
-
-<para>
+ <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.
+ </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.
+ </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>.
-</para>
+ </para>
 
-<section xml:id="ssec-bower2nix-usage">
+ <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:
-
-
-<example xml:id="ex-bowerJson"><title><filename>bower.json</filename></title>
+  <para>
+   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">
 <![CDATA[{
   "name": "my-web-app",
@@ -44,14 +41,12 @@
   }
 }]]>
 </programlisting>
-</example>
-</para>
-
-
-<para>
-  Running <command>bower2nix</command> will produce something like the
-  following output:
+   </example>
+  </para>
 
+  <para>
+   Running <command>bower2nix</command> will produce something like the
+   following output:
 <programlisting language="nix">
 <![CDATA[{ fetchbower, buildEnv }:
 buildEnv { name = "bower-env"; ignoreCollisions = true; paths = [
@@ -60,31 +55,31 @@ buildEnv { name = "bower-env"; ignoreCollisions = true; paths = [
   (fetchbower "jquery" "2.2.2" "1.9.1 - 2" "10sp5h98sqwk90y4k6hbdviwqzvzwqf47r3r51pakch5ii2y7js1")
 ]; }]]>
 </programlisting>
-</para>
-
+  </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.
-</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.
+  </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.
-</para>
-</section>
+  <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.
+  </para>
+ </section>
 
-<section xml:id="ssec-build-bower-components"><title><varname>buildBowerComponents</varname> function</title>
+ <section xml:id="ssec-build-bower-components">
+  <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:
-
-<example xml:id="ex-buildBowerComponents"><title>buildBowerComponents</title>
+   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">
 bowerComponents = buildBowerComponents {
   name = "my-web-app";
@@ -92,42 +87,42 @@ bowerComponents = buildBowerComponents {
   src = myWebApp; <co xml:id="ex-buildBowerComponents-2" />
 };
 </programlisting>
-</example>
+   </example>
   </para>
 
-<para>
-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>.
-    </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.
-    </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.
-</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.
-</para>
-
-<example xml:id="ex-bowerGulpFile"><title>Example build script (<filename>gulpfile.js</filename>)</title>
+  <para>
+   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>.
+     </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.
+     </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.
+  </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.
+  </para>
+
+  <example xml:id="ex-bowerGulpFile">
+   <title>Example build script (<filename>gulpfile.js</filename>)</title>
 <programlisting language="javascript">
 <![CDATA[var gulp = require('gulp');
 
@@ -142,10 +137,10 @@ gulp.task('build', [], function () {
     .pipe(gulp.dest("./gulpdist/"));
 });]]>
 </programlisting>
-</example>
+  </example>
 
-<example xml:id="ex-buildBowerComponentsDefaultNix">
-  <title>Full example — <filename>default.nix</filename></title>
+  <example xml:id="ex-buildBowerComponentsDefaultNix">
+   <title>Full example — <filename>default.nix</filename></title>
 <programlisting language="nix">
 { myWebApp ? { outPath = ./.; name = "myWebApp"; }
 , pkgs ? import &lt;nixpkgs&gt; {}
@@ -172,73 +167,63 @@ pkgs.stdenv.mkDerivation {
   installPhase = "mv gulpdist $out";
 }
 </programlisting>
-</example>
-
-<para>
-A few notes about <xref linkend="ex-buildBowerComponentsDefaultNix" />:
-
-<calloutlist>
-  <callout arearefs="ex-buildBowerComponentsDefault-1">
-    <para>
-      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.
-    </para>
-  </callout>
-
-  <callout arearefs="ex-buildBowerComponentsDefault-3">
-    <para>
-      <command>gulp</command> requires <varname>HOME</varname> to
-      refer to a writeable directory.
-    </para>
-  </callout>
-
-  <callout arearefs="ex-buildBowerComponentsDefault-4">
-    <para>
+  </example>
+
+  <para>
+   A few notes about <xref linkend="ex-buildBowerComponentsDefaultNix" />:
+   <calloutlist>
+    <callout arearefs="ex-buildBowerComponentsDefault-1">
+     <para>
+      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.
+     </para>
+    </callout>
+    <callout arearefs="ex-buildBowerComponentsDefault-3">
+     <para>
+      <command>gulp</command> requires <varname>HOME</varname> to refer to a
+      writeable directory.
+     </para>
+    </callout>
+    <callout arearefs="ex-buildBowerComponentsDefault-4">
+     <para>
       The actual build command. Other tools could be used.
-    </para>
-  </callout>
-</calloutlist>
-</para>
-</section>
+     </para>
+    </callout>
+   </calloutlist>
+  </para>
+ </section>
 
-<section xml:id="ssec-bower2nix-troubleshooting">
+ <section xml:id="ssec-bower2nix-troubleshooting">
   <title>Troubleshooting</title>
 
-<variablelist>
-
-  <varlistentry>
-    <term>
-    <literal>ENOCACHE</literal> errors from
+  <variablelist>
+   <varlistentry>
+    <term><literal>ENOCACHE</literal> errors from
     <varname>buildBowerComponents</varname>
     </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>.
-      </para>
-      <para>
-        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>.
-      </para>
+     <para>
+      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.
+     </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>.
+     </para>
     </listitem>
-  </varlistentry>
-</variablelist>
-
-</section>
-
+   </varlistentry>
+  </variablelist>
+ </section>
 </section>
diff --git a/doc/languages-frameworks/coq.xml b/doc/languages-frameworks/coq.xml
index 0ce1abd6194c..d5f2574039f2 100644
--- a/doc/languages-frameworks/coq.xml
+++ b/doc/languages-frameworks/coq.xml
@@ -1,36 +1,38 @@
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="sec-language-coq">
+ <title>Coq</title>
 
-<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.
-  </para>
-  <para>
-    Some libraries require OCaml and sometimes also Camlp5 or findlib.
-    The exact versions that were used to build Coq are saved in the
-    <literal>coq.ocaml</literal> and <literal>coq.camlp5</literal>
-    and <literal>coq.findlib</literal> attributes.
-  </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.
-  </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.
-  </para>
-  <programlisting>
+ <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.
+ </para>
+
+ <para>
+  Some libraries require OCaml and sometimes also Camlp5 or findlib. The exact
+  versions that were used to build Coq are saved in the
+  <literal>coq.ocaml</literal> and <literal>coq.camlp5</literal> and
+  <literal>coq.findlib</literal> attributes.
+ </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.
+ </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.
+ </para>
+
+<programlisting>
 { stdenv, fetchFromGitHub, coq, mathcomp }:
 
 stdenv.mkDerivation rec {
diff --git a/doc/languages-frameworks/go.xml b/doc/languages-frameworks/go.xml
index 54ea60c90212..ab4c9f0f7c88 100644
--- a/doc/languages-frameworks/go.xml
+++ b/doc/languages-frameworks/go.xml
@@ -1,14 +1,14 @@
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="sec-language-go">
+ <title>Go</title>
 
-<title>Go</title>
+ <para>
+  The function <varname>buildGoPackage</varname> builds standard Go programs.
+ </para>
 
-<para>The function <varname>buildGoPackage</varname> builds
-standard Go programs.
-</para>
-
-<example xml:id='ex-buildGoPackage'><title>buildGoPackage</title>
+ <example xml:id='ex-buildGoPackage'>
+  <title>buildGoPackage</title>
 <programlisting>
 deis = buildGoPackage rec {
   name = "deis-${version}";
@@ -29,55 +29,56 @@ deis = buildGoPackage rec {
   buildFlags = "--tags release"; <co xml:id='ex-buildGoPackage-4' />
 }
 </programlisting>
-</example>
-
-<para><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'>
+ </example>
+
+ <para>
+  <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'>
+   </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'>
+   </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'>
+   </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>.
-</para>
-
-<example xml:id='ex-goDeps'><title>deps.nix</title>
+   </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>.
+ </para>
+
+ <example xml:id='ex-goDeps'>
+  <title>deps.nix</title>
 <programlisting>
 [ <co xml:id='ex-goDeps-1' />
   {
@@ -100,67 +101,60 @@ the following arguments are of special significance to the function:
   }
 ]
 </programlisting>
-</example>
+ </example>
 
-<para>
-
-<calloutlist>
-
-  <callout arearefs='ex-goDeps-1'>
+ <para>
+  <calloutlist>
+   <callout arearefs='ex-goDeps-1'>
     <para>
-      <varname>goDeps</varname> is a list of Go dependencies.
+     <varname>goDeps</varname> is a list of Go dependencies.
     </para>
-  </callout>
-
-  <callout arearefs='ex-goDeps-2'>
+   </callout>
+   <callout arearefs='ex-goDeps-2'>
     <para>
-      <varname>goPackagePath</varname> specifies Go package import path.
+     <varname>goPackagePath</varname> specifies Go package import path.
     </para>
-  </callout>
-
-  <callout arearefs='ex-goDeps-3'>
+   </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.</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:
-
-  <screen>
+   </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.
+ </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:
+<screen>
     $ nix-build -A deis.bin
   </screen>
-
   or build all outputs with:
-
-  <screen>
+<screen>
     $ 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>.
+ </para>
 
-  <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:
-
+ <para>
+  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"
 done
 </screen>
-</para>
-
+ </para>
 </section>
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index a1c265f67484..f22984cb56b0 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -1,36 +1,31 @@
 <chapter xmlns="http://docbook.org/ns/docbook"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          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.</para>
-
-
-<xi:include href="beam.xml" />
-<xi:include href="bower.xml" />
-<xi:include href="coq.xml" />
-<xi:include href="go.xml" />
-<xi:include href="haskell.section.xml" />
-<xi:include href="idris.section.xml" />
-<xi:include href="java.xml" />
-<xi:include href="lua.xml" />
-<xi:include href="node.section.xml" />
-<xi:include href="perl.xml" />
-<xi:include href="python.section.xml" />
-<xi:include href="qt.xml" />
-<xi:include href="r.section.xml" />
-<xi:include href="ruby.xml" />
-<xi:include href="rust.section.xml" />
-<xi:include href="texlive.xml" />
-<xi:include href="vim.section.xml" />
-<xi:include href="emscripten.section.xml" />
-
-
+ <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.
+ </para>
+ <xi:include href="beam.xml" />
+ <xi:include href="bower.xml" />
+ <xi:include href="coq.xml" />
+ <xi:include href="go.xml" />
+ <xi:include href="haskell.section.xml" />
+ <xi:include href="idris.section.xml" />
+ <xi:include href="java.xml" />
+ <xi:include href="lua.xml" />
+ <xi:include href="node.section.xml" />
+ <xi:include href="perl.xml" />
+ <xi:include href="python.section.xml" />
+ <xi:include href="qt.xml" />
+ <xi:include href="r.section.xml" />
+ <xi:include href="ruby.xml" />
+ <xi:include href="rust.section.xml" />
+ <xi:include href="texlive.xml" />
+ <xi:include href="vim.section.xml" />
+ <xi:include href="emscripten.section.xml" />
 </chapter>
diff --git a/doc/languages-frameworks/java.xml b/doc/languages-frameworks/java.xml
index 2507cc2c469a..dcf4d17fa57d 100644
--- a/doc/languages-frameworks/java.xml
+++ b/doc/languages-frameworks/java.xml
@@ -1,11 +1,10 @@
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="sec-language-java">
+ <title>Java</title>
 
-<title>Java</title>
-
-<para>Ant-based Java packages are typically built from source as follows:
-
+ <para>
+  Ant-based Java packages are typically built from source as follows:
 <programlisting>
 stdenv.mkDerivation {
   name = "...";
@@ -16,33 +15,33 @@ stdenv.mkDerivation {
   buildPhase = "ant";
 }
 </programlisting>
-
-Note that <varname>jdk</varname> is an alias for the OpenJDK.</para>
-
-<para>JAR files that are intended to be used by other packages should
-be installed in <filename>$out/share/java</filename>.  The OpenJDK has
-a stdenv setup hook that adds 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
-
+  Note that <varname>jdk</varname> is an alias for the OpenJDK.
+ </para>
+
+ <para>
+  JAR files that are intended to be used by other packages should be installed
+  in <filename>$out/share/java</filename>. The OpenJDK has a stdenv setup hook
+  that adds 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 = [ jdk libfoo ];
 </programlisting>
-
-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>.</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:
-
+  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>.
+ </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:
 <programlisting>
 buildInputs = [ makeWrapper ];
 
@@ -53,23 +52,20 @@ 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.</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:
-
+  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>
+  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>
 buildInputs = [ gcj ant ];
 </programlisting>
-
-Here, Ant will automatically use <command>gij</command> (the GNU Java
-Runtime) instead of the OpenJRE.</para>
-
+  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 39b086af4cb1..210140299960 100644
--- a/doc/languages-frameworks/lua.xml
+++ b/doc/languages-frameworks/lua.xml
@@ -1,24 +1,22 @@
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="sec-language-lua">
+ <title>Lua</title>
 
-<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">
+ <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.)
-</para>
+ </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>.
+ <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:
-
-  <programlisting>
+<programlisting>
 fileSystem = buildLuaPackage {
   name = "filesystem-1.6.2";
   src = fetchurl {
@@ -32,20 +30,19 @@ fileSystem = buildLuaPackage {
   };
 };
   </programlisting>
-</para>
+ </para>
 
-<para>
+ <para>
   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.
-</para>
+ </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.
+ </para>
 </section>
-
diff --git a/doc/languages-frameworks/perl.xml b/doc/languages-frameworks/perl.xml
index 149fcb275a09..2fe64999e139 100644
--- a/doc/languages-frameworks/perl.xml
+++ b/doc/languages-frameworks/perl.xml
@@ -1,24 +1,27 @@
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="sec-language-perl">
-
-<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
-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
+ <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
+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:
-
+  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";
@@ -28,74 +31,72 @@ 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>
 $ 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>
 $ 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>.)</para>
-
-<para>So what does <varname>buildPerlPackage</varname> do?  It does
-the following:
-
-<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></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.</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.</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>:
-
+  (Of course you can also install using the attribute name: <literal>nix-env -i
+  -A perlPackages.ClassC3</literal>.)
+ </para>
+
+ <para>
+  So what does <varname>buildPerlPackage</varname> do? It does the following:
+  <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>
+    </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.
+    </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.
+    </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>:
 <programlisting>
 { buildPerlPackage, fetchurl, db }:
 
@@ -113,18 +114,15 @@ buildPerlPackage rec {
   '';
 }
 </programlisting>
-
-</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:
-
+ </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:
 <programlisting>
 ClassC3Componentised = buildPerlPackage rec {
   name = "Class-C3-Componentised-1.0004";
@@ -137,24 +135,26 @@ ClassC3Componentised = buildPerlPackage rec {
   ];
 };
 </programlisting>
+ </para>
 
-</para>
-
-<section xml:id="ssec-generation-from-CPAN"><title>Generation from CPAN</title>
+ <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:</para>
+  <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:
+  </para>
 
 <screen>
 $ nix-env -i nix-generate-from-cpan
 </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:
-
+  <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:
 <screen>
 $ nix-generate-from-cpan XML::Simple
   XMLSimple = buildPerlPackage rec {
@@ -170,26 +170,23 @@ $ nix-generate-from-cpan XML::Simple
     };
   };
 </screen>
-
-The output can be pasted into
-<filename>pkgs/top-level/perl-packages.nix</filename> or wherever else
-you need it.</para>
-
-</section>
-
-<section xml:id="ssec-perl-cross-compilation"><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.</para>
-
-</section>
-
+   The output can be pasted into
+   <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you
+   need it.
+  </para>
+ </section>
+
+ <section xml:id="ssec-perl-cross-compilation">
+  <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.
+  </para>
+ </section>
 </section>
-
diff --git a/doc/languages-frameworks/qt.xml b/doc/languages-frameworks/qt.xml
index 1dbbb5341ba3..b9b605b81da1 100644
--- a/doc/languages-frameworks/qt.xml
+++ b/doc/languages-frameworks/qt.xml
@@ -1,58 +1,74 @@
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="sec-language-qt">
+ <title>Qt</title>
 
-<title>Qt</title>
-
-<para>
-Qt is a comprehensive desktop and mobile application development toolkit for C++.
-Legacy support is available for Qt 3 and Qt 4, but all current development uses Qt 5.
-The Qt 5 packages in Nixpkgs are updated frequently to take advantage of new features,
-but older versions are typically retained until their support window ends.
-The most important consideration in packaging Qt-based software is ensuring that each package and all its dependencies use the same version of Qt 5;
-this consideration motivates most of the tools described below.
-</para>
-
-<section xml:id="ssec-qt-libraries"><title>Packaging Libraries for Nixpkgs</title>
-
-<para>
-Whenever possible, libraries that use Qt 5 should be built with each available version.
-Packages providing libraries should be added to the top-level function <varname>mkLibsForQt5</varname>,
-which is used to build a set of libraries for every Qt 5 version.
-A special <varname>callPackage</varname> function is used in this scope to ensure that the entire dependency tree uses the same Qt 5 version.
-Import dependencies unqualified, i.e., <literal>qtbase</literal> not <literal>qt5.qtbase</literal>.
-<emphasis>Do not</emphasis> import a package set such as <literal>qt5</literal> or <literal>libsForQt5</literal>.
-</para>
-
-<para>
-If a library does not support a particular version of Qt 5, it is best to mark it as broken by setting its <literal>meta.broken</literal> attribute.
-A package may be marked broken for certain versions by testing the <literal>qtbase.version</literal> attribute, which will always give the current Qt 5 version.
-</para>
+ <para>
+  Qt is a comprehensive desktop and mobile application development toolkit for
+  C++. Legacy support is available for Qt 3 and Qt 4, but all current
+  development uses Qt 5. The Qt 5 packages in Nixpkgs are updated frequently to
+  take advantage of new features, but older versions are typically retained
+  until their support window ends. The most important consideration in
+  packaging Qt-based software is ensuring that each package and all its
+  dependencies use the same version of Qt 5; this consideration motivates most
+  of the tools described below.
+ </para>
 
-</section>
+ <section xml:id="ssec-qt-libraries">
+  <title>Packaging Libraries for Nixpkgs</title>
 
-<section xml:id="ssec-qt-applications"><title>Packaging Applications for Nixpkgs</title>
+  <para>
+   Whenever possible, libraries that use Qt 5 should be built with each
+   available version. Packages providing libraries should be added to the
+   top-level function <varname>mkLibsForQt5</varname>, which is used to build a
+   set of libraries for every Qt 5 version. A special
+   <varname>callPackage</varname> function is used in this scope to ensure that
+   the entire dependency tree uses the same Qt 5 version. Import dependencies
+   unqualified, i.e., <literal>qtbase</literal> not
+   <literal>qt5.qtbase</literal>. <emphasis>Do not</emphasis> import a package
+   set such as <literal>qt5</literal> or <literal>libsForQt5</literal>.
+  </para>
 
-<para>
-Call your application expression using <literal>libsForQt5.callPackage</literal> instead of <literal>callPackage</literal>.
-Import dependencies unqualified, i.e., <literal>qtbase</literal> not <literal>qt5.qtbase</literal>.
-<emphasis>Do not</emphasis> import a package set such as <literal>qt5</literal> or <literal>libsForQt5</literal>.
-</para>
+  <para>
+   If a library does not support a particular version of Qt 5, it is best to
+   mark it as broken by setting its <literal>meta.broken</literal> attribute. A
+   package may be marked broken for certain versions by testing the
+   <literal>qtbase.version</literal> attribute, which will always give the
+   current Qt 5 version.
+  </para>
+ </section>
 
-<para>
-Qt 5 maintains strict backward compatibility, so it is generally best to build an application package against the latest version using the <varname>libsForQt5</varname> library set.
-In case a package does not build with the latest Qt version, it is possible to pick a set pinned to a particular version, e.g. <varname>libsForQt55</varname> for Qt 5.5, if that is the latest version the package supports.
-If a package must be pinned to an older Qt version, be sure to file a bug upstream;
-because Qt is strictly backwards-compatible, any incompatibility is by definition a bug in the application.
-</para>
+ <section xml:id="ssec-qt-applications">
+  <title>Packaging Applications for Nixpkgs</title>
 
-<para>
-When testing applications in Nixpkgs, it is a common practice to build the package with <literal>nix-build</literal> and run it using the created symbolic link.
-This will not work with Qt applications, however, because they have many hard runtime requirements that can only be guaranteed if the package is actually installed.
-To test a Qt application, install it with <literal>nix-env</literal> or run it inside <literal>nix-shell</literal>.
-</para>
+  <para>
+   Call your application expression using
+   <literal>libsForQt5.callPackage</literal> instead of
+   <literal>callPackage</literal>. Import dependencies unqualified, i.e.,
+   <literal>qtbase</literal> not <literal>qt5.qtbase</literal>. <emphasis>Do
+   not</emphasis> import a package set such as <literal>qt5</literal> or
+   <literal>libsForQt5</literal>.
+  </para>
 
-</section>
+  <para>
+   Qt 5 maintains strict backward compatibility, so it is generally best to
+   build an application package against the latest version using the
+   <varname>libsForQt5</varname> library set. In case a package does not build
+   with the latest Qt version, it is possible to pick a set pinned to a
+   particular version, e.g. <varname>libsForQt55</varname> for Qt 5.5, if that
+   is the latest version the package supports. If a package must be pinned to
+   an older Qt version, be sure to file a bug upstream; because Qt is strictly
+   backwards-compatible, any incompatibility is by definition a bug in the
+   application.
+  </para>
 
+  <para>
+   When testing applications in Nixpkgs, it is a common practice to build the
+   package with <literal>nix-build</literal> and run it using the created
+   symbolic link. This will not work with Qt applications, however, because
+   they have many hard runtime requirements that can only be guaranteed if the
+   package is actually installed. To test a Qt application, install it with
+   <literal>nix-env</literal> or run it inside <literal>nix-shell</literal>.
+  </para>
+ </section>
 </section>
-
diff --git a/doc/languages-frameworks/ruby.xml b/doc/languages-frameworks/ruby.xml
index 6bb809192f89..c52a72a3df4a 100644
--- a/doc/languages-frameworks/ruby.xml
+++ b/doc/languages-frameworks/ruby.xml
@@ -1,17 +1,19 @@
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="sec-language-ruby">
+ <title>Ruby</title>
 
-<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.
+ </para>
 
-<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.
-</para>
-
-<para>For example, to package sensu, we did:</para>
+ <para>
+  For example, to package sensu, we did:
+ </para>
 
 <screen>
 <![CDATA[$ cd pkgs/servers/monitoring
@@ -42,17 +44,18 @@ 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.
-</para>
+ <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.
+ </para>
 
-<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:
-</para>
+ <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:
+ </para>
 
 <screen>
 <![CDATA[{ lib, bundlerApp }:
@@ -72,31 +75,31 @@ 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.
-</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:
-</para>
+ <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.
+ </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:
+ </para>
 
 <programlisting>
 <![CDATA[let env = bundlerEnv {
@@ -118,5 +121,4 @@ in stdenv.mkDerivation {
   '';
 }]]>
 </programlisting>
-
 </section>
diff --git a/doc/languages-frameworks/texlive.xml b/doc/languages-frameworks/texlive.xml
index 4515e17ec09e..af0b07166e3e 100644
--- a/doc/languages-frameworks/texlive.xml
+++ b/doc/languages-frameworks/texlive.xml
@@ -1,27 +1,42 @@
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="sec-language-texlive">
+ <title>TeX Live</title>
 
-<title>TeX Live</title>
+ <para>
+  Since release 15.09 there is a new TeX Live packaging that lives entirely
+  under attribute <varname>texlive</varname>.
+ </para>
+
+ <section>
+  <title>User's guide</title>
 
-<para>Since release 15.09 there is a new TeX Live packaging that lives entirely under attribute <varname>texlive</varname>.</para>
-<section><title>User's guide</title>
   <itemizedlist>
-    <listitem><para>
-      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:
-      <programlisting>
+   <listitem>
+    <para>
+     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:
+<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).
-    </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>.
-      <programlisting>
+     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>.
+<programlisting>
 texlive.combine {
   # inherit (texlive) whatever-you-want;
   pkgFilter = pkg:
@@ -30,34 +45,55 @@ texlive.combine {
   # there are also other attributes: version, name
 }
       </programlisting>
-    </para></listitem>
-    <listitem><para>
-      You can list packages e.g. by <command>nix-repl</command>.
-      <programlisting>
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     You can list packages e.g. by <command>nix-repl</command>.
+<programlisting>
 $ nix-repl
 nix-repl> :l &lt;nixpkgs>
 nix-repl> texlive.collection-&lt;TAB>
       </programlisting>
-    </para></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.
-    </para></listitem>
+    </para>
+   </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.
+    </para>
+   </listitem>
   </itemizedlist>
-</section>
+ </section>
+
+ <section>
+  <title>Known problems</title>
 
-<section><title>Known problems</title>
   <itemizedlist>
-    <listitem><para>
-      Some tools are still missing, e.g. luajittex;</para></listitem>
-    <listitem><para>
-      some apps aren't packaged/tested yet (asymptote, biber, etc.);</para></listitem>
-    <listitem><para>
-      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.</para></listitem>
+   <listitem>
+    <para>
+     Some tools are still missing, e.g. luajittex;
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     some apps aren't packaged/tested yet (asymptote, biber, etc.);
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     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.
+    </para>
+   </listitem>
   </itemizedlist>
+ </section>
 </section>
-
-
-</section>
-