NixOS · May 1, 2018 · May 1, 2018
diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml
diff --git a/doc/configuration.xml b/doc/configuration.xml
diff --git a/doc/contributing.xml b/doc/contributing.xml
@@ -1,35 +1,35 @@
 <chapter xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="chap-contributing">
-
-<title>Contributing to this documentation</title>
-
-<para>The DocBook sources of the Nixpkgs manual are in the <filename
+ <title>Contributing to this documentation</title>
+ <para>
+  The DocBook sources of the Nixpkgs manual are in the
+  <filename
 xlink:href="https://github.com/NixOS/nixpkgs/tree/master/doc">doc</filename>
-subdirectory of the Nixpkgs repository.</para>
-
-<para>You can quickly check your edits with <command>make</command>:</para>
-
+  subdirectory of the Nixpkgs repository.
+ </para>
+ <para>
+  You can quickly check your edits with <command>make</command>:
+ </para>
 <screen>
   $ cd /path/to/nixpkgs/doc
   $ nix-shell
   [nix-shell]$ make
 </screen>
-
-<para>If you experience problems, run <command>make debug</command>
-to help understand the docbook errors.</para>
-
-<para>After making modifications to the manual, it's important to
-build it before committing. You can do that as follows:
-
+ <para>
+  If you experience problems, run <command>make debug</command> to help
+  understand the docbook errors.
+ </para>
+ <para>
+  After making modifications to the manual, it's important to build it before
+  committing. You can do that as follows:
 <screen>
   $ cd /path/to/nixpkgs/doc
   $ nix-shell
   [nix-shell]$ make clean
   [nix-shell]$ nix-build .
 </screen>
-
-If the build succeeds, the manual will be in
-<filename>./result/share/doc/nixpkgs/manual.html</filename>.</para>
-
+  If the build succeeds, the manual will be in
+  <filename>./result/share/doc/nixpkgs/manual.html</filename>.
+ </para>
 </chapter>
diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml
diff --git a/doc/functions.xml b/doc/functions.xml
diff --git a/doc/languages-frameworks/beam.xml b/doc/languages-frameworks/beam.xml
diff --git 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,74 +55,74 @@ 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";
   generated = ./bower-packages.nix; <co xml:id="ex-buildBowerComponents-1" />
   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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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>
-
diff --git a/doc/manual.xml b/doc/manual.xml
@@ -1,29 +1,24 @@
 <book xmlns="http://docbook.org/ns/docbook"
       xmlns:xi="http://www.w3.org/2001/XInclude">
-
-  <info>
-
-    <title>Nixpkgs Contributors Guide</title>
-
-    <subtitle>Version <xi:include href=".version" parse="text" /></subtitle>
-
-  </info>
-
-  <xi:include href="introduction.chapter.xml" />
-  <xi:include href="quick-start.xml" />
-  <xi:include href="stdenv.xml" />
-  <xi:include href="multiple-output.xml" />
-  <xi:include href="cross-compilation.xml" />
-  <xi:include href="configuration.xml" />
-  <xi:include href="functions.xml" />
-  <xi:include href="meta.xml" />
-  <xi:include href="languages-frameworks/index.xml" />
-  <xi:include href="platform-notes.xml" />
-  <xi:include href="package-notes.xml" />
-  <xi:include href="overlays.xml" />
-  <xi:include href="coding-conventions.xml" />
-  <xi:include href="submitting-changes.xml" />
-  <xi:include href="reviewing-contributions.xml" />
-  <xi:include href="contributing.xml" />
-
+ <info>
+  <title>Nixpkgs Contributors Guide</title>
+  <subtitle>Version <xi:include href=".version" parse="text" />
+  </subtitle>
+ </info>
+ <xi:include href="introduction.chapter.xml" />
+ <xi:include href="quick-start.xml" />
+ <xi:include href="stdenv.xml" />
+ <xi:include href="multiple-output.xml" />
+ <xi:include href="cross-compilation.xml" />
+ <xi:include href="configuration.xml" />
+ <xi:include href="functions.xml" />
+ <xi:include href="meta.xml" />
+ <xi:include href="languages-frameworks/index.xml" />
+ <xi:include href="platform-notes.xml" />
+ <xi:include href="package-notes.xml" />
+ <xi:include href="overlays.xml" />
+ <xi:include href="coding-conventions.xml" />
+ <xi:include href="submitting-changes.xml" />
+ <xi:include href="reviewing-contributions.xml" />
+ <xi:include href="contributing.xml" />
 </book>
diff --git a/doc/meta.xml b/doc/meta.xml
diff --git a/doc/multiple-output.xml b/doc/multiple-output.xml
diff --git a/doc/overlays.xml b/doc/overlays.xml
@@ -1,95 +1,117 @@
 <chapter xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="chap-overlays">
-
-<title>Overlays</title>
-
-<para>This chapter describes how to extend and change Nixpkgs packages using
-overlays. Overlays are used to add layers in the fix-point used by Nixpkgs
-to compose the set of all packages.</para>
-
-<para>Nixpkgs can be configured with a list of overlays, which are
-applied in order. This means that the order of the overlays can be significant
-if multiple layers override the same package.</para>
-
+ <title>Overlays</title>
+ <para>
+  This chapter describes how to extend and change Nixpkgs packages using
+  overlays. Overlays are used to add layers in the fix-point used by Nixpkgs to
+  compose the set of all packages.
+ </para>
+ <para>
+  Nixpkgs can be configured with a list of overlays, which are applied in
+  order. This means that the order of the overlays can be significant if
+  multiple layers override the same package.
+ </para>
 <!--============================================================-->
-
-<section xml:id="sec-overlays-install">
-<title>Installing overlays</title>
-
-<para>The list of overlays is determined as follows.</para>
-
-<para>If the <varname>overlays</varname> argument is not provided explicitly, we look for overlays in a path. The path
-is determined as follows:
-
-<orderedlist>
-
-  <listitem>
-    <para>First, if an <varname>overlays</varname> argument to the nixpkgs function itself is given,
-    then that is used.</para>
-
-    <para>This can be passed explicitly when importing nipxkgs, for example 
-    <literal>import &lt;nixpkgs> { overlays = [ overlay1 overlay2 ]; }</literal>.</para>
-  </listitem>
-
-  <listitem>
-    <para>Otherwise, if the Nix path entry <literal>&lt;nixpkgs-overlays></literal> exists, we look for overlays
-    at that path, as described below.</para>
-
-    <para>See the section on <literal>NIX_PATH</literal> in the Nix manual for more details on how to 
-    set a value for <literal>&lt;nixpkgs-overlays>.</literal></para>
-  </listitem>
-
-  <listitem>
-    <para>If one of <filename>~/.config/nixpkgs/overlays.nix</filename> and
-    <filename>~/.config/nixpkgs/overlays/</filename> exists, then we look for overlays at that path, as
-    described below. It is an error if both exist.</para>
-  </listitem>
-
-</orderedlist>
-</para>
-
-<para>If we are looking for overlays at a path, then there are two cases:
-<itemizedlist>
-  <listitem>
-    <para>If the path is a file, then the file is imported as a Nix expression and used as the list of
-    overlays.</para>
-  </listitem>
-
-  <listitem>
-    <para>If the path is a directory, then we take the content of the directory, order it
-    lexicographically, and attempt to interpret each as an overlay by:
-    <itemizedlist>
-      <listitem>
-        <para>Importing the file, if it is a <literal>.nix</literal> file.</para>
-      </listitem>
-      <listitem>
-        <para>Importing a top-level <filename>default.nix</filename> file, if it is a directory.</para>
-      </listitem>
-    </itemizedlist>
-    </para>
-  </listitem>
-</itemizedlist>
-</para>
-
-<para>On a NixOS system the value of the <literal>nixpkgs.overlays</literal> option, if present, 
-is passed to the system Nixpkgs directly as an argument. Note that this does not affect the overlays for
-non-NixOS operations (e.g. <literal>nix-env</literal>), which are looked up independently.</para>
-
-<para>The <filename>overlays.nix</filename> option therefore provides a convenient way to use the same
-overlays for a NixOS system configuration and user configuration: the same file can be used
-as <filename>overlays.nix</filename> and imported as the value of <literal>nixpkgs.overlays</literal>.</para>
-
-</section>
-
+ <section xml:id="sec-overlays-install">
+  <title>Installing overlays</title>
+
+  <para>
+   The list of overlays is determined as follows.
+  </para>
+
+  <para>
+   If the <varname>overlays</varname> argument is not provided explicitly, we
+   look for overlays in a path. The path is determined as follows:
+   <orderedlist>
+    <listitem>
+     <para>
+      First, if an <varname>overlays</varname> argument to the nixpkgs function
+      itself is given, then that is used.
+     </para>
+     <para>
+      This can be passed explicitly when importing nipxkgs, for example
+      <literal>import &lt;nixpkgs> { overlays = [ overlay1 overlay2 ];
+      }</literal>.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      Otherwise, if the Nix path entry <literal>&lt;nixpkgs-overlays></literal>
+      exists, we look for overlays at that path, as described below.
+     </para>
+     <para>
+      See the section on <literal>NIX_PATH</literal> in the Nix manual for more
+      details on how to set a value for
+      <literal>&lt;nixpkgs-overlays>.</literal>
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      If one of <filename>~/.config/nixpkgs/overlays.nix</filename> and
+      <filename>~/.config/nixpkgs/overlays/</filename> exists, then we look for
+      overlays at that path, as described below. It is an error if both exist.
+     </para>
+    </listitem>
+   </orderedlist>
+  </para>
+
+  <para>
+   If we are looking for overlays at a path, then there are two cases:
+   <itemizedlist>
+    <listitem>
+     <para>
+      If the path is a file, then the file is imported as a Nix expression and
+      used as the list of overlays.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      If the path is a directory, then we take the content of the directory,
+      order it lexicographically, and attempt to interpret each as an overlay
+      by:
+      <itemizedlist>
+       <listitem>
+        <para>
+         Importing the file, if it is a <literal>.nix</literal> file.
+        </para>
+       </listitem>
+       <listitem>
+        <para>
+         Importing a top-level <filename>default.nix</filename> file, if it is
+         a directory.
+        </para>
+       </listitem>
+      </itemizedlist>
+     </para>
+    </listitem>
+   </itemizedlist>
+  </para>
+
+  <para>
+   On a NixOS system the value of the <literal>nixpkgs.overlays</literal>
+   option, if present, is passed to the system Nixpkgs directly as an argument.
+   Note that this does not affect the overlays for non-NixOS operations (e.g.
+   <literal>nix-env</literal>), which are looked up independently.
+  </para>
+
+  <para>
+   The <filename>overlays.nix</filename> option therefore provides a convenient
+   way to use the same overlays for a NixOS system configuration and user
+   configuration: the same file can be used as
+   <filename>overlays.nix</filename> and imported as the value of
+   <literal>nixpkgs.overlays</literal>.
+  </para>
+ </section>
 <!--============================================================-->
+ <section xml:id="sec-overlays-definition">
+  <title>Defining overlays</title>
 
-<section xml:id="sec-overlays-definition">
-<title>Defining overlays</title>
-
-<para>Overlays are Nix functions which accept two arguments, 
-conventionally called <varname>self</varname> and <varname>super</varname>, 
-and return a set of packages. For example, the following is a valid overlay.</para>
+  <para>
+   Overlays are Nix functions which accept two arguments, conventionally called
+   <varname>self</varname> and <varname>super</varname>, and return a set of
+   packages. For example, the following is a valid overlay.
+  </para>
 
 <programlisting>
 self: super:
@@ -104,31 +126,39 @@ self: super:
 }
 </programlisting>
 
-<para>The first argument (<varname>self</varname>) corresponds to the final package
-set. You should use this set for the dependencies of all packages specified in your
-overlay. For example, all the dependencies of <varname>rr</varname> in the example above come
-from <varname>self</varname>, as well as the overridden dependencies used in the
-<varname>boost</varname> override.</para>
-
-<para>The second argument (<varname>super</varname>)
-corresponds to the result of the evaluation of the previous stages of
-Nixpkgs. It does not contain any of the packages added by the current
-overlay, nor any of the following overlays. This set should be used either
-to refer to packages you wish to override, or to access functions defined
-in Nixpkgs. For example, the original recipe of <varname>boost</varname>
-in the above example, comes from <varname>super</varname>, as well as the
-<varname>callPackage</varname> function.</para>
-
-<para>The value returned by this function should be a set similar to
-<filename>pkgs/top-level/all-packages.nix</filename>, containing
-overridden and/or new packages.</para>
-
-<para>Overlays are similar to other methods for customizing Nixpkgs, in particular
-the <literal>packageOverrides</literal> attribute described in <xref linkend="sec-modify-via-packageOverrides"/>.
-Indeed, <literal>packageOverrides</literal> acts as an overlay with only the 
-<varname>super</varname> argument. It is therefore appropriate for basic use, 
-but overlays are more powerful and easier to distribute.</para>
-
-</section>
-
+  <para>
+   The first argument (<varname>self</varname>) corresponds to the final
+   package set. You should use this set for the dependencies of all packages
+   specified in your overlay. For example, all the dependencies of
+   <varname>rr</varname> in the example above come from
+   <varname>self</varname>, as well as the overridden dependencies used in the
+   <varname>boost</varname> override.
+  </para>
+
+  <para>
+   The second argument (<varname>super</varname>) corresponds to the result of
+   the evaluation of the previous stages of Nixpkgs. It does not contain any of
+   the packages added by the current overlay, nor any of the following
+   overlays. This set should be used either to refer to packages you wish to
+   override, or to access functions defined in Nixpkgs. For example, the
+   original recipe of <varname>boost</varname> in the above example, comes from
+   <varname>super</varname>, as well as the <varname>callPackage</varname>
+   function.
+  </para>
+
+  <para>
+   The value returned by this function should be a set similar to
+   <filename>pkgs/top-level/all-packages.nix</filename>, containing overridden
+   and/or new packages.
+  </para>
+
+  <para>
+   Overlays are similar to other methods for customizing Nixpkgs, in particular
+   the <literal>packageOverrides</literal> attribute described in
+   <xref linkend="sec-modify-via-packageOverrides"/>. Indeed,
+   <literal>packageOverrides</literal> acts as an overlay with only the
+   <varname>super</varname> argument. It is therefore appropriate for basic
+   use, but overlays are more powerful and easier to distribute.
+  </para>
+ </section>
 </chapter>
diff --git a/doc/package-notes.xml b/doc/package-notes.xml
diff --git a/doc/platform-notes.xml b/doc/platform-notes.xml
@@ -1,27 +1,25 @@
 <chapter xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="chap-platform-nodes">
+ <title>Platform Notes</title>
+ <section xml:id="sec-darwin">
+  <title>Darwin (macOS)</title>
 
-<title>Platform Notes</title>
+  <para>
+   Some common issues when packaging software for darwin:
+  </para>
 
-<section xml:id="sec-darwin">
-
-<title>Darwin (macOS)</title>
-<para>Some common issues when packaging software for darwin:</para>
-
-<itemizedlist>
-
-  <listitem>
+  <itemizedlist>
+   <listitem>
     <para>
-      The darwin <literal>stdenv</literal> uses clang instead of gcc.
-      When referring to the compiler <varname>$CC</varname> or <command>cc</command>
-      will work in both cases.  Some builds hardcode gcc/g++ in their
-      build scripts, that can usually be fixed with using something
-      like <literal>makeFlags = [ "CC=cc" ];</literal> or by patching
-      the build scripts.
+     The darwin <literal>stdenv</literal> uses clang instead of gcc. When
+     referring to the compiler <varname>$CC</varname> or <command>cc</command>
+     will work in both cases. Some builds hardcode gcc/g++ in their build
+     scripts, that can usually be fixed with using something like
+     <literal>makeFlags = [ "CC=cc" ];</literal> or by patching the build
+     scripts.
     </para>
-
-    <programlisting>
+<programlisting>
       stdenv.mkDerivation {
         name = "libfoo-1.2.3";
         # ...
@@ -30,36 +28,33 @@
         '';
       }
     </programlisting>
-  </listitem>
-
-  <listitem>
+   </listitem>
+   <listitem>
     <para>
-      On darwin libraries are linked using absolute paths, libraries
-      are resolved by their <literal>install_name</literal> at link
-      time.  Sometimes packages won't set this correctly causing the
-      library lookups to fail at runtime.  This can be fixed by adding
-      extra linker flags or by running <command>install_name_tool -id</command>
-      during the <function>fixupPhase</function>.
+     On darwin libraries are linked using absolute paths, libraries are
+     resolved by their <literal>install_name</literal> at link time. Sometimes
+     packages won't set this correctly causing the library lookups to fail at
+     runtime. This can be fixed by adding extra linker flags or by running
+     <command>install_name_tool -id</command> during the
+     <function>fixupPhase</function>.
     </para>
-
-    <programlisting>
+<programlisting>
       stdenv.mkDerivation {
         name = "libfoo-1.2.3";
         # ...
         makeFlags = stdenv.lib.optional stdenv.isDarwin "LDFLAGS=-Wl,-install_name,$(out)/lib/libfoo.dylib";
       }
     </programlisting>
-  </listitem>
-
-  <listitem>
+   </listitem>
+   <listitem>
     <para>
-      Some packages assume xcode is available and use <command>xcrun</command>
-      to resolve build tools like <command>clang</command>, etc.
-      This causes errors like <code>xcode-select: error: no developer tools were found at '/Applications/Xcode.app'</code>
-      while the build doesn't actually depend on xcode.
+     Some packages assume xcode is available and use <command>xcrun</command>
+     to resolve build tools like <command>clang</command>, etc. This causes
+     errors like <code>xcode-select: error: no developer tools were found at
+     '/Applications/Xcode.app'</code> while the build doesn't actually depend
+     on xcode.
     </para>
-
-    <programlisting>
+<programlisting>
       stdenv.mkDerivation {
         name = "libfoo-1.2.3";
         # ...
@@ -69,15 +64,12 @@
         '';
       }
     </programlisting>
-
     <para>
-      The package <literal>xcbuild</literal> can be used to build projects
-      that really depend on Xcode, however projects that build some kind of
-      graphical interface won't work without using Xcode in an impure way.
+     The package <literal>xcbuild</literal> can be used to build projects that
+     really depend on Xcode, however projects that build some kind of graphical
+     interface won't work without using Xcode in an impure way.
     </para>
-  </listitem>
-
-</itemizedlist>
-</section>
-
+   </listitem>
+  </itemizedlist>
+ </section>
 </chapter>
diff --git a/doc/quick-start.xml b/doc/quick-start.xml
diff --git a/doc/release-notes.xml b/doc/release-notes.xml
diff --git a/doc/reviewing-contributions.xml b/doc/reviewing-contributions.xml
diff --git a/doc/stdenv.xml b/doc/stdenv.xml
diff --git a/doc/submitting-changes.xml b/doc/submitting-changes.xml
diff --git a/nixos/doc/manual/administration/boot-problems.xml b/nixos/doc/manual/administration/boot-problems.xml
@@ -3,63 +3,83 @@
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0"
         xml:id="sec-boot-problems">
+ <title>Boot Problems</title>
 
-<title>Boot Problems</title>
+ <para>
+  If NixOS fails to boot, there are a number of kernel command line parameters
+  that may help you to identify or fix the issue. You can add these parameters
+  in the GRUB boot menu by pressing “e” to modify the selected boot entry
+  and editing the line starting with <literal>linux</literal>. The following
+  are some useful kernel command line parameters that are recognised by the
+  NixOS boot scripts or by systemd:
+  <variablelist>
+   <varlistentry>
+    <term><literal>boot.shell_on_fail</literal>
+    </term>
+    <listitem>
+     <para>
+      Start a root shell if something goes wrong in stage 1 of the boot process
+      (the initial ramdisk). This is disabled by default because there is no
+      authentication for the root shell.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><literal>boot.debug1</literal>
+    </term>
+    <listitem>
+     <para>
+      Start an interactive shell in stage 1 before anything useful has been
+      done. That is, no modules have been loaded and no file systems have been
+      mounted, except for <filename>/proc</filename> and
+      <filename>/sys</filename>.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><literal>boot.trace</literal>
+    </term>
+    <listitem>
+     <para>
+      Print every shell command executed by the stage 1 and 2 boot scripts.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><literal>single</literal>
+    </term>
+    <listitem>
+     <para>
+      Boot into rescue mode (a.k.a. single user mode). This will cause systemd
+      to start nothing but the unit <literal>rescue.target</literal>, which
+      runs <command>sulogin</command> to prompt for the root password and start
+      a root login shell. Exiting the shell causes the system to continue with
+      the normal boot process.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><literal>systemd.log_level=debug systemd.log_target=console</literal>
+    </term>
+    <listitem>
+     <para>
+      Make systemd very verbose and send log messages to the console instead of
+      the journal.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+  For more parameters recognised by systemd, see <citerefentry>
+  <refentrytitle>systemd</refentrytitle>
+  <manvolnum>1</manvolnum></citerefentry>.
+ </para>
 
-<para>If NixOS fails to boot, there are a number of kernel command
-line parameters that may help you to identify or fix the issue.  You
-can add these parameters in the GRUB boot menu by pressing “e” to
-modify the selected boot entry and editing the line starting with
-<literal>linux</literal>.  The following are some useful kernel command
-line parameters that are recognised by the NixOS boot scripts or by
-systemd:
-
-<variablelist>
-
-  <varlistentry><term><literal>boot.shell_on_fail</literal></term>
-    <listitem><para>Start a root shell if something goes wrong in
-    stage 1 of the boot process (the initial ramdisk).  This is
-    disabled by default because there is no authentication for the
-    root shell.</para></listitem>
-  </varlistentry>
-
-  <varlistentry><term><literal>boot.debug1</literal></term>
-    <listitem><para>Start an interactive shell in stage 1 before
-    anything useful has been done.  That is, no modules have been
-    loaded and no file systems have been mounted, except for
-    <filename>/proc</filename> and
-    <filename>/sys</filename>.</para></listitem>
-  </varlistentry>
-
-  <varlistentry><term><literal>boot.trace</literal></term>
-    <listitem><para>Print every shell command executed by the stage 1
-    and 2 boot scripts.</para></listitem>
-  </varlistentry>
-
-  <varlistentry><term><literal>single</literal></term>
-    <listitem><para>Boot into rescue mode (a.k.a. single user mode).
-    This will cause systemd to start nothing but the unit
-    <literal>rescue.target</literal>, which runs
-    <command>sulogin</command> to prompt for the root password and
-    start a root login shell.  Exiting the shell causes the system to
-    continue with the normal boot process.</para></listitem>
-  </varlistentry>
-
-  <varlistentry><term><literal>systemd.log_level=debug systemd.log_target=console</literal></term>
-    <listitem><para>Make systemd very verbose and send log messages to
-    the console instead of the journal.</para></listitem>
-  </varlistentry>
-
-</variablelist>
-
-For more parameters recognised by systemd, see
-<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
-
-<para>If no login prompts or X11 login screens appear (e.g. due to
-hanging dependencies), you can press Alt+ArrowUp.  If you’re lucky,
-this will start rescue mode (described above).  (Also note that since
-most units have a 90-second timeout before systemd gives up on them,
-the <command>agetty</command> login prompts should appear eventually
-unless something is very wrong.)</para>
-
-</section>
+ <para>
+  If no login prompts or X11 login screens appear (e.g. due to hanging
+  dependencies), you can press Alt+ArrowUp. If you’re lucky, this will start
+  rescue mode (described above). (Also note that since most units have a
+  90-second timeout before systemd gives up on them, the
+  <command>agetty</command> login prompts should appear eventually unless
+  something is very wrong.)
+ </para>
+</section>
diff --git a/nixos/doc/manual/administration/cleaning-store.xml b/nixos/doc/manual/administration/cleaning-store.xml
@@ -3,60 +3,51 @@
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0"
         xml:id="sec-nix-gc">
-
-<title>Cleaning the Nix Store</title>
-
-<para>Nix has a purely functional model, meaning that packages are
-never upgraded in place.  Instead new versions of packages end up in a
-different location in the Nix store (<filename>/nix/store</filename>).
-You should periodically run Nix’s <emphasis>garbage
-collector</emphasis> to remove old, unreferenced packages.  This is
-easy:
-
+ <title>Cleaning the Nix Store</title>
+ <para>
+  Nix has a purely functional model, meaning that packages are never upgraded
+  in place. Instead new versions of packages end up in a different location in
+  the Nix store (<filename>/nix/store</filename>). You should periodically run
+  Nix’s <emphasis>garbage collector</emphasis> to remove old, unreferenced
+  packages. This is easy:
 <screen>
 $ nix-collect-garbage
 </screen>
-
-Alternatively, you can use a systemd unit that does the same in the
-background:
-
+  Alternatively, you can use a systemd unit that does the same in the
+  background:
 <screen>
 # systemctl start nix-gc.service
 </screen>
-
-You can tell NixOS in <filename>configuration.nix</filename> to run
-this unit automatically at certain points in time, for instance, every
-night at 03:15:
-
+  You can tell NixOS in <filename>configuration.nix</filename> to run this unit
+  automatically at certain points in time, for instance, every night at 03:15:
 <programlisting>
 <xref linkend="opt-nix.gc.automatic"/> = true;
 <xref linkend="opt-nix.gc.dates"/> = "03:15";
 </programlisting>
-
-</para>
-
-<para>The commands above do not remove garbage collector roots, such
-as old system configurations.  Thus they do not remove the ability to
-roll back to previous configurations.  The following command deletes
-old roots, removing the ability to roll back to them:
+ </para>
+ <para>
+  The commands above do not remove garbage collector roots, such as old system
+  configurations. Thus they do not remove the ability to roll back to previous
+  configurations. The following command deletes old roots, removing the ability
+  to roll back to them:
 <screen>
 $ nix-collect-garbage -d
 </screen>
-You can also do this for specific profiles, e.g.
+  You can also do this for specific profiles, e.g.
 <screen>
 $ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old
 </screen>
-Note that NixOS system configurations are stored in the profile
-<filename>/nix/var/nix/profiles/system</filename>.</para>
-
-<para>Another way to reclaim disk space (often as much as 40% of the
-size of the Nix store) is to run Nix’s store optimiser, which seeks
-out identical files in the store and replaces them with hard links to
-a single copy.
+  Note that NixOS system configurations are stored in the profile
+  <filename>/nix/var/nix/profiles/system</filename>.
+ </para>
+ <para>
+  Another way to reclaim disk space (often as much as 40% of the size of the
+  Nix store) is to run Nix’s store optimiser, which seeks out identical files
+  in the store and replaces them with hard links to a single copy.
 <screen>
 $ nix-store --optimise
 </screen>
-Since this command needs to read the entire Nix store, it can take
-quite a while to finish.</para>
-
+  Since this command needs to read the entire Nix store, it can take quite a
+  while to finish.
+ </para>
 </chapter>
diff --git a/nixos/doc/manual/administration/container-networking.xml b/nixos/doc/manual/administration/container-networking.xml
@@ -3,56 +3,53 @@
           xmlns:xi="http://www.w3.org/2001/XInclude"
           version="5.0"
           xml:id="sec-container-networking">
+ <title>Container Networking</title>
 
-
-<title>Container Networking</title>
-
-<para>When you create a container using <literal>nixos-container
-create</literal>, it gets it own private IPv4 address in the range
-<literal>10.233.0.0/16</literal>. You can get the container’s IPv4
-address as follows:
-
+ <para>
+  When you create a container using <literal>nixos-container create</literal>,
+  it gets it own private IPv4 address in the range
+  <literal>10.233.0.0/16</literal>. You can get the container’s IPv4 address
+  as follows:
 <screen>
 # nixos-container show-ip foo
 10.233.4.2
 
 $ ping -c1 10.233.4.2
 64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms
 </screen>
-
-</para>
-
-<para>Networking is implemented using a pair of virtual Ethernet
-devices. The network interface in the container is called
-<literal>eth0</literal>, while the matching interface in the host is
-called <literal>ve-<replaceable>container-name</replaceable></literal>
-(e.g., <literal>ve-foo</literal>).  The container has its own network
-namespace and the <literal>CAP_NET_ADMIN</literal> capability, so it
-can perform arbitrary network configuration such as setting up
-firewall rules, without affecting or having access to the host’s
-network.</para>
-
-<para>By default, containers cannot talk to the outside network. If
-you want that, you should set up Network Address Translation (NAT)
-rules on the host to rewrite container traffic to use your external
-IP address. This can be accomplished using the following configuration
-on the host:
-
+ </para>
+
+ <para>
+  Networking is implemented using a pair of virtual Ethernet devices. The
+  network interface in the container is called <literal>eth0</literal>, while
+  the matching interface in the host is called
+  <literal>ve-<replaceable>container-name</replaceable></literal> (e.g.,
+  <literal>ve-foo</literal>). The container has its own network namespace and
+  the <literal>CAP_NET_ADMIN</literal> capability, so it can perform arbitrary
+  network configuration such as setting up firewall rules, without affecting or
+  having access to the host’s network.
+ </para>
+
+ <para>
+  By default, containers cannot talk to the outside network. If you want that,
+  you should set up Network Address Translation (NAT) rules on the host to
+  rewrite container traffic to use your external IP address. This can be
+  accomplished using the following configuration on the host:
 <programlisting>
 <xref linkend="opt-networking.nat.enable"/> = true;
 <xref linkend="opt-networking.nat.internalInterfaces"/> = ["ve-+"];
 <xref linkend="opt-networking.nat.externalInterface"/> = "eth0";
 </programlisting>
-where <literal>eth0</literal> should be replaced with the desired
-external interface. Note that <literal>ve-+</literal> is a wildcard
-that matches all container interfaces.</para>
-
-<para>If you are using Network Manager, you need to explicitly prevent
-it from managing container interfaces:
-
+  where <literal>eth0</literal> should be replaced with the desired external
+  interface. Note that <literal>ve-+</literal> is a wildcard that matches all
+  container interfaces.
+ </para>
+
+ <para>
+  If you are using Network Manager, you need to explicitly prevent it from
+  managing container interfaces:
 <programlisting>
 networking.networkmanager.unmanaged = [ "interface-name:ve-*" ];
 </programlisting>
-</para>
-
+ </para>
 </section>
diff --git a/nixos/doc/manual/administration/containers.xml b/nixos/doc/manual/administration/containers.xml
@@ -3,32 +3,32 @@
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0"
         xml:id="ch-containers">
-
-<title>Container Management</title>
-
-<para>NixOS allows you to easily run other NixOS instances as
-<emphasis>containers</emphasis>. Containers are a light-weight
-approach to virtualisation that runs software in the container at the
-same speed as in the host system. NixOS containers share the Nix store
-of the host, making container creation very efficient.</para>
-
-<warning><para>Currently, NixOS containers are not perfectly isolated
-from the host system. This means that a user with root access to the
-container can do things that affect the host. So you should not give
-container root access to untrusted users.</para></warning>
-
-<para>NixOS containers can be created in two ways: imperatively, using
-the command <command>nixos-container</command>, and declaratively, by
-specifying them in your <filename>configuration.nix</filename>. The
-declarative approach implies that containers get upgraded along with
-your host system when you run <command>nixos-rebuild</command>, which
-is often not what you want. By contrast, in the imperative approach,
-containers are configured and updated independently from the host
-system.</para>
-
-<xi:include href="imperative-containers.xml" />
-<xi:include href="declarative-containers.xml" />
-<xi:include href="container-networking.xml" />
-
+ <title>Container Management</title>
+ <para>
+  NixOS allows you to easily run other NixOS instances as
+  <emphasis>containers</emphasis>. Containers are a light-weight approach to
+  virtualisation that runs software in the container at the same speed as in
+  the host system. NixOS containers share the Nix store of the host, making
+  container creation very efficient.
+ </para>
+ <warning>
+  <para>
+   Currently, NixOS containers are not perfectly isolated from the host system.
+   This means that a user with root access to the container can do things that
+   affect the host. So you should not give container root access to untrusted
+   users.
+  </para>
+ </warning>
+ <para>
+  NixOS containers can be created in two ways: imperatively, using the command
+  <command>nixos-container</command>, and declaratively, by specifying them in
+  your <filename>configuration.nix</filename>. The declarative approach implies
+  that containers get upgraded along with your host system when you run
+  <command>nixos-rebuild</command>, which is often not what you want. By
+  contrast, in the imperative approach, containers are configured and updated
+  independently from the host system.
+ </para>
+ <xi:include href="imperative-containers.xml" />
+ <xi:include href="declarative-containers.xml" />
+ <xi:include href="container-networking.xml" />
 </chapter>
-
diff --git a/nixos/doc/manual/administration/control-groups.xml b/nixos/doc/manual/administration/control-groups.xml
@@ -3,20 +3,18 @@
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0"
         xml:id="sec-cgroups">
-
-<title>Control Groups</title>
-
-<para>To keep track of the processes in a running system, systemd uses
-<emphasis>control groups</emphasis> (cgroups).  A control group is a
-set of processes used to allocate resources such as CPU, memory or I/O
-bandwidth.  There can be multiple control group hierarchies, allowing
-each kind of resource to be managed independently.</para>
-
-<para>The command <command>systemd-cgls</command> lists all control
-groups in the <literal>systemd</literal> hierarchy, which is what
-systemd uses to keep track of the processes belonging to each service
-or user session:
-
+ <title>Control Groups</title>
+ <para>
+  To keep track of the processes in a running system, systemd uses
+  <emphasis>control groups</emphasis> (cgroups). A control group is a set of
+  processes used to allocate resources such as CPU, memory or I/O bandwidth.
+  There can be multiple control group hierarchies, allowing each kind of
+  resource to be managed independently.
+ </para>
+ <para>
+  The command <command>systemd-cgls</command> lists all control groups in the
+  <literal>systemd</literal> hierarchy, which is what systemd uses to keep
+  track of the processes belonging to each service or user session:
 <screen>
 $ systemd-cgls
 ├─user
@@ -34,40 +32,34 @@ $ systemd-cgls
   │ └─2376 dhcpcd --config /nix/store/f8dif8dsi2yaa70n03xir8r653776ka6-dhcpcd.conf
   └─ <replaceable>...</replaceable>
 </screen>
-
-Similarly, <command>systemd-cgls cpu</command> shows the cgroups in
-the CPU hierarchy, which allows per-cgroup CPU scheduling priorities.
-By default, every systemd service gets its own CPU cgroup, while all
-user sessions are in the top-level CPU cgroup.  This ensures, for
-instance, that a thousand run-away processes in the
-<literal>httpd.service</literal> cgroup cannot starve the CPU for one
-process in the <literal>postgresql.service</literal> cgroup.  (By
-contrast, it they were in the same cgroup, then the PostgreSQL process
-would get 1/1001 of the cgroup’s CPU time.)  You can limit a service’s
-CPU share in <filename>configuration.nix</filename>:
-
+  Similarly, <command>systemd-cgls cpu</command> shows the cgroups in the CPU
+  hierarchy, which allows per-cgroup CPU scheduling priorities. By default,
+  every systemd service gets its own CPU cgroup, while all user sessions are in
+  the top-level CPU cgroup. This ensures, for instance, that a thousand
+  run-away processes in the <literal>httpd.service</literal> cgroup cannot
+  starve the CPU for one process in the <literal>postgresql.service</literal>
+  cgroup. (By contrast, it they were in the same cgroup, then the PostgreSQL
+  process would get 1/1001 of the cgroup’s CPU time.) You can limit a
+  service’s CPU share in <filename>configuration.nix</filename>:
 <programlisting>
 <link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.CPUShares = 512;
 </programlisting>
-
-By default, every cgroup has 1024 CPU shares, so this will halve the
-CPU allocation of the <literal>httpd.service</literal> cgroup.</para>
-
-<para>There also is a <literal>memory</literal> hierarchy that
-controls memory allocation limits; by default, all processes are in
-the top-level cgroup, so any service or session can exhaust all
-available memory.  Per-cgroup memory limits can be specified in
-<filename>configuration.nix</filename>; for instance, to limit
-<literal>httpd.service</literal> to 512 MiB of RAM (excluding swap):
-
+  By default, every cgroup has 1024 CPU shares, so this will halve the CPU
+  allocation of the <literal>httpd.service</literal> cgroup.
+ </para>
+ <para>
+  There also is a <literal>memory</literal> hierarchy that controls memory
+  allocation limits; by default, all processes are in the top-level cgroup, so
+  any service or session can exhaust all available memory. Per-cgroup memory
+  limits can be specified in <filename>configuration.nix</filename>; for
+  instance, to limit <literal>httpd.service</literal> to 512 MiB of RAM
+  (excluding swap):
 <programlisting>
 <link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.MemoryLimit = "512M";
 </programlisting>
-
-</para>
-
-<para>The command <command>systemd-cgtop</command> shows a
-continuously updated list of all cgroups with their CPU and memory
-usage.</para>
-
+ </para>
+ <para>
+  The command <command>systemd-cgtop</command> shows a continuously updated
+  list of all cgroups with their CPU and memory usage.
+ </para>
 </chapter>
diff --git a/nixos/doc/manual/administration/declarative-containers.xml b/nixos/doc/manual/administration/declarative-containers.xml
@@ -3,14 +3,13 @@
           xmlns:xi="http://www.w3.org/2001/XInclude"
           version="5.0"
           xml:id="sec-declarative-containers">
+ <title>Declarative Container Specification</title>
 
-<title>Declarative Container Specification</title>
-
-<para>You can also specify containers and their configuration in the
-host’s <filename>configuration.nix</filename>.  For example, the
-following specifies that there shall be a container named
-<literal>database</literal> running PostgreSQL:
-
+ <para>
+  You can also specify containers and their configuration in the host’s
+  <filename>configuration.nix</filename>. For example, the following specifies
+  that there shall be a container named <literal>database</literal> running
+  PostgreSQL:
 <programlisting>
 containers.database =
   { config =
@@ -20,41 +19,42 @@ containers.database =
       };
   };
 </programlisting>
-
-If you run <literal>nixos-rebuild switch</literal>, the container will
-be built. If the container was already running, it will be
-updated in place, without rebooting. The container can be configured to
-start automatically by setting <literal>containers.database.autoStart = true</literal>
-in its configuration.</para>
-
-<para>By default, declarative containers share the network namespace
-of the host, meaning that they can listen on (privileged)
-ports. However, they cannot change the network configuration. You can
-give a container its own network as follows:
-
+  If you run <literal>nixos-rebuild switch</literal>, the container will be
+  built. If the container was already running, it will be updated in place,
+  without rebooting. The container can be configured to start automatically by
+  setting <literal>containers.database.autoStart = true</literal> in its
+  configuration.
+ </para>
+
+ <para>
+  By default, declarative containers share the network namespace of the host,
+  meaning that they can listen on (privileged) ports. However, they cannot
+  change the network configuration. You can give a container its own network as
+  follows:
 <programlisting>
 containers.database = {
   <link linkend="opt-containers._name_.privateNetwork">privateNetwork</link> = true;
   <link linkend="opt-containers._name_.hostAddress">hostAddress</link> = "192.168.100.10";
   <link linkend="opt-containers._name_.localAddress">localAddress</link> = "192.168.100.11";
 };
 </programlisting>
-
-This gives the container a private virtual Ethernet interface with IP
-address <literal>192.168.100.11</literal>, which is hooked up to a
-virtual Ethernet interface on the host with IP address
-<literal>192.168.100.10</literal>. (See the next section for details
-on container networking.)</para>
-
-<para>To disable the container, just remove it from
-<filename>configuration.nix</filename> and run <literal>nixos-rebuild
-switch</literal>. Note that this will not delete the root directory of
-the container in <literal>/var/lib/containers</literal>. Containers can be
-destroyed using the imperative method: <literal>nixos-container destroy
- foo</literal>.</para>
-
-<para>Declarative containers can be started and stopped using the
-corresponding systemd service, e.g. <literal>systemctl start
-container@database</literal>.</para>
-
+  This gives the container a private virtual Ethernet interface with IP address
+  <literal>192.168.100.11</literal>, which is hooked up to a virtual Ethernet
+  interface on the host with IP address <literal>192.168.100.10</literal>. (See
+  the next section for details on container networking.)
+ </para>
+
+ <para>
+  To disable the container, just remove it from
+  <filename>configuration.nix</filename> and run <literal>nixos-rebuild
+  switch</literal>. Note that this will not delete the root directory of the
+  container in <literal>/var/lib/containers</literal>. Containers can be
+  destroyed using the imperative method: <literal>nixos-container destroy
+  foo</literal>.
+ </para>
+
+ <para>
+  Declarative containers can be started and stopped using the corresponding
+  systemd service, e.g. <literal>systemctl start container@database</literal>.
+ </para>
 </section>