doc: re-format

45 files changed, 1105 insertions, 4349 deletions

diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml
index 48356247a49e..799f1479467a 100644
--- a/doc/coding-conventions.xml
+++ b/doc/coding-conventions.xml
@@ -8,24 +8,17 @@
   <itemizedlist>
    <listitem>
     <para>
-     Use 2 spaces of indentation per indentation level in Nix expressions, 4
-     spaces in shell scripts.
+     Use 2 spaces of indentation per indentation level in Nix expressions, 4 spaces in shell scripts.
     </para>
    </listitem>
    <listitem>
     <para>
-     Do not use tab characters, i.e. configure your editor to use soft tabs.
-     For instance, use <literal>(setq-default indent-tabs-mode nil)</literal>
-     in Emacs. Everybody has different tab settings so it’s asking for
-     trouble.
+     Do not use tab characters, i.e. configure your editor to use soft tabs. For instance, use <literal>(setq-default indent-tabs-mode nil)</literal> in Emacs. Everybody has different tab settings so it’s asking for trouble.
     </para>
    </listitem>
    <listitem>
     <para>
-     Use <literal>lowerCamelCase</literal> for variable names, not
-     <literal>UpperCamelCase</literal>. Note, this rule does not apply to
-     package attribute names, which instead follow the rules in
-     <xref linkend="sec-package-naming"/>.
+     Use <literal>lowerCamelCase</literal> for variable names, not <literal>UpperCamelCase</literal>. Note, this rule does not apply to package attribute names, which instead follow the rules in <xref linkend="sec-package-naming"/>.
     </para>
    </listitem>
    <listitem>
@@ -52,8 +45,7 @@ foo { arg = ...; }
    </listitem>
    <listitem>
     <para>
-     In attribute sets or lists that span multiple lines, the attribute names
-     or list elements should be aligned:
+     In attribute sets or lists that span multiple lines, the attribute names or list elements should be aligned:
 <programlisting>
 # A long list.
 list = [
@@ -97,8 +89,7 @@ attrs = { x = 1280; y = 1024; };
    </listitem>
    <listitem>
     <para>
-     Breaking in the middle of a function argument can give hard-to-read code,
-     like
+     Breaking in the middle of a function argument can give hard-to-read code, like
 <programlisting>
 someFunction { x = 1280;
   y = 1024; } otherArg
@@ -123,8 +114,7 @@ in someFunction res otherArg yetAnotherArg
    </listitem>
    <listitem>
     <para>
-     The bodies of functions, asserts, and withs are not indented to prevent a
-     lot of superfluous indentation levels, i.e.
+     The bodies of functions, asserts, and withs are not indented to prevent a lot of superfluous indentation levels, i.e.
 <programlisting>
 { arg1, arg2 }:
 assert system == "i686-linux";
@@ -156,8 +146,7 @@ stdenv.mkDerivation { ...
    </listitem>
    <listitem>
     <para>
-     Functions should list their expected arguments as precisely as possible.
-     That is, write
+     Functions should list their expected arguments as precisely as possible. That is, write
 <programlisting>
 { stdenv, fetchurl, perl }: <replaceable>...</replaceable>
 </programlisting>
@@ -171,9 +160,7 @@ args: with args; <replaceable>...</replaceable>
 </programlisting>
     </para>
     <para>
-     For functions that are truly generic in the number of arguments (such as
-     wrappers around <varname>mkDerivation</varname>) that have some required
-     arguments, you should write them using an <literal>@</literal>-pattern:
+     For functions that are truly generic in the number of arguments (such as wrappers around <varname>mkDerivation</varname>) that have some required arguments, you should write them using an <literal>@</literal>-pattern:
 <programlisting>
 { stdenv, doCoverageAnalysis ? false, ... } @ args:
 
@@ -197,35 +184,20 @@ args.stdenv.mkDerivation (args // {
   <title>Package naming</title>
 
   <para>
-   The key words <emphasis>must</emphasis>, <emphasis>must not</emphasis>,
-   <emphasis>required</emphasis>, <emphasis>shall</emphasis>, <emphasis>shall
-   not</emphasis>, <emphasis>should</emphasis>, <emphasis>should
-   not</emphasis>, <emphasis>recommended</emphasis>, <emphasis>may</emphasis>,
-   and <emphasis>optional</emphasis> in this section are to be interpreted as
-   described in <link xlink:href="https://tools.ietf.org/html/rfc2119">RFC
-   2119</link>. Only <emphasis>emphasized</emphasis> words are to be
-   interpreted in this way.
+   The key words <emphasis>must</emphasis>, <emphasis>must not</emphasis>, <emphasis>required</emphasis>, <emphasis>shall</emphasis>, <emphasis>shall not</emphasis>, <emphasis>should</emphasis>, <emphasis>should not</emphasis>, <emphasis>recommended</emphasis>, <emphasis>may</emphasis>, and <emphasis>optional</emphasis> in this section are to be interpreted as described in <link xlink:href="https://tools.ietf.org/html/rfc2119">RFC 2119</link>. Only <emphasis>emphasized</emphasis> words are to be interpreted in this way.
   </para>
 
   <para>
-   In Nixpkgs, there are generally three different names associated with a
-   package:
+   In Nixpkgs, there are generally three different names associated with a package:
    <itemizedlist>
     <listitem>
      <para>
-      The <varname>name</varname> attribute of the derivation (excluding the
-      version part). This is what most users see, in particular when using
-      <command>nix-env</command>.
+      The <varname>name</varname> attribute of the derivation (excluding the version part). This is what most users see, in particular when using <command>nix-env</command>.
      </para>
     </listitem>
     <listitem>
      <para>
-      The variable name used for the instantiated package in
-      <filename>all-packages.nix</filename>, and when passing it as a
-      dependency to other functions. Typically this is called the
-      <emphasis>package attribute name</emphasis>. This is what Nix expression
-      authors see. It can also be used when installing using <command>nix-env
-      -iA</command>.
+      The variable name used for the instantiated package in <filename>all-packages.nix</filename>, and when passing it as a dependency to other functions. Typically this is called the <emphasis>package attribute name</emphasis>. This is what Nix expression authors see. It can also be used when installing using <command>nix-env -iA</command>.
      </para>
     </listitem>
     <listitem>
@@ -234,12 +206,7 @@ args.stdenv.mkDerivation (args // {
      </para>
     </listitem>
    </itemizedlist>
-   Most of the time, these are the same. For instance, the package
-   <literal>e2fsprogs</literal> has a <varname>name</varname> attribute
-   <literal>"e2fsprogs-<replaceable>version</replaceable>"</literal>, is bound
-   to the variable name <varname>e2fsprogs</varname> in
-   <filename>all-packages.nix</filename>, and the Nix expression is in
-   <filename>pkgs/os-specific/linux/e2fsprogs/default.nix</filename>.
+   Most of the time, these are the same. For instance, the package <literal>e2fsprogs</literal> has a <varname>name</varname> attribute <literal>"e2fsprogs-<replaceable>version</replaceable>"</literal>, is bound to the variable name <varname>e2fsprogs</varname> in <filename>all-packages.nix</filename>, and the Nix expression is in <filename>pkgs/os-specific/linux/e2fsprogs/default.nix</filename>.
   </para>
 
   <para>
@@ -247,51 +214,32 @@ args.stdenv.mkDerivation (args // {
    <itemizedlist>
     <listitem>
      <para>
-      The <literal>name</literal> attribute <emphasis>should</emphasis> be
-      identical to the upstream package name.
+      The <literal>name</literal> attribute <emphasis>should</emphasis> be identical to the upstream package name.
      </para>
     </listitem>
     <listitem>
      <para>
-      The <literal>name</literal> attribute <emphasis>must not</emphasis>
-      contain uppercase letters — e.g., <literal>"mplayer-1.0rc2"</literal>
-      instead of <literal>"MPlayer-1.0rc2"</literal>.
+      The <literal>name</literal> attribute <emphasis>must not</emphasis> contain uppercase letters — e.g., <literal>"mplayer-1.0rc2"</literal> instead of <literal>"MPlayer-1.0rc2"</literal>.
      </para>
     </listitem>
     <listitem>
      <para>
-      The version part of the <literal>name</literal> attribute
-      <emphasis>must</emphasis> start with a digit (following a dash) — e.g.,
-      <literal>"hello-0.3.1rc2"</literal>.
+      The version part of the <literal>name</literal> attribute <emphasis>must</emphasis> start with a digit (following a dash) — e.g., <literal>"hello-0.3.1rc2"</literal>.
      </para>
     </listitem>
     <listitem>
      <para>
-      If a package is not a release but a commit from a repository, then the
-      version part of the name <emphasis>must</emphasis> be the date of that
-      (fetched) commit. The date <emphasis>must</emphasis> be in
-      <literal>"YYYY-MM-DD"</literal> format. Also append
-      <literal>"unstable"</literal> to the name - e.g.,
-      <literal>"pkgname-unstable-2014-09-23"</literal>.
+      If a package is not a release but a commit from a repository, then the version part of the name <emphasis>must</emphasis> be the date of that (fetched) commit. The date <emphasis>must</emphasis> be in <literal>"YYYY-MM-DD"</literal> format. Also append <literal>"unstable"</literal> to the name - e.g., <literal>"pkgname-unstable-2014-09-23"</literal>.
      </para>
     </listitem>
     <listitem>
      <para>
-      Dashes in the package name <emphasis>should</emphasis> be preserved in
-      new variable names, rather than converted to underscores or camel cased
-      — e.g., <varname>http-parser</varname> instead of
-      <varname>http_parser</varname> or <varname>httpParser</varname>. The
-      hyphenated style is preferred in all three package names.
+      Dashes in the package name <emphasis>should</emphasis> be preserved in new variable names, rather than converted to underscores or camel cased — e.g., <varname>http-parser</varname> instead of <varname>http_parser</varname> or <varname>httpParser</varname>. The hyphenated style is preferred in all three package names.
      </para>
     </listitem>
     <listitem>
      <para>
-      If there are multiple versions of a package, this
-      <emphasis>should</emphasis> be reflected in the variable names in
-      <filename>all-packages.nix</filename>, e.g. <varname>json-c-0-9</varname>
-      and <varname>json-c-0-11</varname>. If there is an obvious “default”
-      version, make an attribute like <literal>json-c = json-c-0-9;</literal>.
-      See also <xref linkend="sec-versioning" />
+      If there are multiple versions of a package, this <emphasis>should</emphasis> be reflected in the variable names in <filename>all-packages.nix</filename>, e.g. <varname>json-c-0-9</varname> and <varname>json-c-0-11</varname>. If there is an obvious “default” version, make an attribute like <literal>json-c = json-c-0-9;</literal>. See also <xref linkend="sec-versioning" />
      </para>
     </listitem>
    </itemizedlist>
@@ -301,31 +249,18 @@ args.stdenv.mkDerivation (args // {
   <title>File naming and organisation</title>
 
   <para>
-   Names of files and directories should be in lowercase, with dashes between
-   words — not in camel case. For instance, it should be
-   <filename>all-packages.nix</filename>, not
-   <filename>allPackages.nix</filename> or
-   <filename>AllPackages.nix</filename>.
+   Names of files and directories should be in lowercase, with dashes between words — not in camel case. For instance, it should be <filename>all-packages.nix</filename>, not <filename>allPackages.nix</filename> or <filename>AllPackages.nix</filename>.
   </para>
 
   <section xml:id="sec-hierarchy">
    <title>Hierarchy</title>
 
    <para>
-    Each package should be stored in its own directory somewhere in the
-    <filename>pkgs/</filename> tree, i.e. in
-    <filename>pkgs/<replaceable>category</replaceable>/<replaceable>subcategory</replaceable>/<replaceable>...</replaceable>/<replaceable>pkgname</replaceable></filename>.
-    Below are some rules for picking the right category for a package. Many
-    packages fall under several categories; what matters is the
-    <emphasis>primary</emphasis> purpose of a package. For example, the
-    <literal>libxml2</literal> package builds both a library and some tools;
-    but it’s a library foremost, so it goes under
-    <filename>pkgs/development/libraries</filename>.
+    Each package should be stored in its own directory somewhere in the <filename>pkgs/</filename> tree, i.e. in <filename>pkgs/<replaceable>category</replaceable>/<replaceable>subcategory</replaceable>/<replaceable>...</replaceable>/<replaceable>pkgname</replaceable></filename>. Below are some rules for picking the right category for a package. Many packages fall under several categories; what matters is the <emphasis>primary</emphasis> purpose of a package. For example, the <literal>libxml2</literal> package builds both a library and some tools; but it’s a library foremost, so it goes under <filename>pkgs/development/libraries</filename>.
    </para>
 
    <para>
-    When in doubt, consider refactoring the <filename>pkgs/</filename> tree,
-    e.g. creating new categories or splitting up an existing category.
+    When in doubt, consider refactoring the <filename>pkgs/</filename> tree, e.g. creating new categories or splitting up an existing category.
    </para>
 
    <variablelist>
@@ -341,8 +276,7 @@ args.stdenv.mkDerivation (args // {
         </term>
         <listitem>
          <para>
-          <filename>development/libraries</filename> (e.g.
-          <filename>libxml2</filename>)
+          <filename>development/libraries</filename> (e.g. <filename>libxml2</filename>)
          </para>
         </listitem>
        </varlistentry>
@@ -352,8 +286,7 @@ args.stdenv.mkDerivation (args // {
         </term>
         <listitem>
          <para>
-          <filename>development/compilers</filename> (e.g.
-          <filename>gcc</filename>)
+          <filename>development/compilers</filename> (e.g. <filename>gcc</filename>)
          </para>
         </listitem>
        </varlistentry>
@@ -363,8 +296,7 @@ args.stdenv.mkDerivation (args // {
         </term>
         <listitem>
          <para>
-          <filename>development/interpreters</filename> (e.g.
-          <filename>guile</filename>)
+          <filename>development/interpreters</filename> (e.g. <filename>guile</filename>)
          </para>
         </listitem>
        </varlistentry>
@@ -380,8 +312,7 @@ args.stdenv.mkDerivation (args // {
            </term>
            <listitem>
             <para>
-             <filename>development/tools/parsing</filename> (e.g.
-             <filename>bison</filename>, <filename>flex</filename>)
+             <filename>development/tools/parsing</filename> (e.g. <filename>bison</filename>, <filename>flex</filename>)
             </para>
            </listitem>
           </varlistentry>
@@ -391,8 +322,7 @@ args.stdenv.mkDerivation (args // {
            </term>
            <listitem>
             <para>
-             <filename>development/tools/build-managers</filename> (e.g.
-             <filename>gnumake</filename>)
+             <filename>development/tools/build-managers</filename> (e.g. <filename>gnumake</filename>)
             </para>
            </listitem>
           </varlistentry>
@@ -402,8 +332,7 @@ args.stdenv.mkDerivation (args // {
            </term>
            <listitem>
             <para>
-             <filename>development/tools/misc</filename> (e.g.
-             <filename>binutils</filename>)
+             <filename>development/tools/misc</filename> (e.g. <filename>binutils</filename>)
             </para>
            </listitem>
           </varlistentry>
@@ -429,8 +358,7 @@ args.stdenv.mkDerivation (args // {
      </term>
      <listitem>
       <para>
-       (A tool is a relatively small program, especially one intended to be
-       used non-interactively.)
+       (A tool is a relatively small program, especially one intended to be used non-interactively.)
       </para>
       <variablelist>
        <varlistentry>
@@ -439,8 +367,7 @@ args.stdenv.mkDerivation (args // {
         </term>
         <listitem>
          <para>
-          <filename>tools/networking</filename> (e.g.
-          <filename>wget</filename>)
+          <filename>tools/networking</filename> (e.g. <filename>wget</filename>)
          </para>
         </listitem>
        </varlistentry>
@@ -470,8 +397,7 @@ args.stdenv.mkDerivation (args // {
         </term>
         <listitem>
          <para>
-          <filename>tools/archivers</filename> (e.g. <filename>zip</filename>,
-          <filename>tar</filename>)
+          <filename>tools/archivers</filename> (e.g. <filename>zip</filename>, <filename>tar</filename>)
          </para>
         </listitem>
        </varlistentry>
@@ -481,8 +407,7 @@ args.stdenv.mkDerivation (args // {
         </term>
         <listitem>
          <para>
-          <filename>tools/compression</filename> (e.g.
-          <filename>gzip</filename>, <filename>bzip2</filename>)
+          <filename>tools/compression</filename> (e.g. <filename>gzip</filename>, <filename>bzip2</filename>)
          </para>
         </listitem>
        </varlistentry>
@@ -492,8 +417,7 @@ args.stdenv.mkDerivation (args // {
         </term>
         <listitem>
          <para>
-          <filename>tools/security</filename> (e.g. <filename>nmap</filename>,
-          <filename>gnupg</filename>)
+          <filename>tools/security</filename> (e.g. <filename>nmap</filename>, <filename>gnupg</filename>)
          </para>
         </listitem>
        </varlistentry>
@@ -532,8 +456,7 @@ args.stdenv.mkDerivation (args // {
         </term>
         <listitem>
          <para>
-          <filename>servers/http</filename> (e.g.
-          <filename>apache-httpd</filename>)
+          <filename>servers/http</filename> (e.g. <filename>apache-httpd</filename>)
          </para>
         </listitem>
        </varlistentry>
@@ -543,8 +466,7 @@ args.stdenv.mkDerivation (args // {
         </term>
         <listitem>
          <para>
-          <filename>servers/x11</filename> (e.g. <filename>xorg</filename> —
-          this includes the client libraries and programs)
+          <filename>servers/x11</filename> (e.g. <filename>xorg</filename> — this includes the client libraries and programs)
          </para>
         </listitem>
        </varlistentry>
@@ -567,8 +489,7 @@ args.stdenv.mkDerivation (args // {
      </term>
      <listitem>
       <para>
-       <filename>desktops</filename> (e.g. <filename>kde</filename>,
-       <filename>gnome</filename>, <filename>enlightenment</filename>)
+       <filename>desktops</filename> (e.g. <filename>kde</filename>, <filename>gnome</filename>, <filename>enlightenment</filename>)
       </para>
      </listitem>
     </varlistentry>
@@ -578,8 +499,7 @@ args.stdenv.mkDerivation (args // {
      </term>
      <listitem>
       <para>
-       <filename>applications/window-managers</filename> (e.g.
-       <filename>awesome</filename>, <filename>stumpwm</filename>)
+       <filename>applications/window-managers</filename> (e.g. <filename>awesome</filename>, <filename>stumpwm</filename>)
       </para>
      </listitem>
     </varlistentry>
@@ -589,8 +509,7 @@ args.stdenv.mkDerivation (args // {
      </term>
      <listitem>
       <para>
-       A (typically large) program with a distinct user interface, primarily
-       used interactively.
+       A (typically large) program with a distinct user interface, primarily used interactively.
       </para>
       <variablelist>
        <varlistentry>
@@ -599,8 +518,7 @@ args.stdenv.mkDerivation (args // {
         </term>
         <listitem>
          <para>
-          <filename>applications/version-management</filename> (e.g.
-          <filename>subversion</filename>)
+          <filename>applications/version-management</filename> (e.g. <filename>subversion</filename>)
          </para>
         </listitem>
        </varlistentry>
@@ -610,8 +528,7 @@ args.stdenv.mkDerivation (args // {
         </term>
         <listitem>
          <para>
-          <filename>applications/video</filename> (e.g.
-          <filename>vlc</filename>)
+          <filename>applications/video</filename> (e.g. <filename>vlc</filename>)
          </para>
         </listitem>
        </varlistentry>
@@ -621,8 +538,7 @@ args.stdenv.mkDerivation (args // {
         </term>
         <listitem>
          <para>
-          <filename>applications/graphics</filename> (e.g.
-          <filename>gimp</filename>)
+          <filename>applications/graphics</filename> (e.g. <filename>gimp</filename>)
          </para>
         </listitem>
        </varlistentry>
@@ -638,8 +554,7 @@ args.stdenv.mkDerivation (args // {
            </term>
            <listitem>
             <para>
-             <filename>applications/networking/mailreaders</filename> (e.g.
-             <filename>thunderbird</filename>)
+             <filename>applications/networking/mailreaders</filename> (e.g. <filename>thunderbird</filename>)
             </para>
            </listitem>
           </varlistentry>
@@ -649,8 +564,7 @@ args.stdenv.mkDerivation (args // {
            </term>
            <listitem>
             <para>
-             <filename>applications/networking/newsreaders</filename> (e.g.
-             <filename>pan</filename>)
+             <filename>applications/networking/newsreaders</filename> (e.g. <filename>pan</filename>)
             </para>
            </listitem>
           </varlistentry>
@@ -660,8 +574,7 @@ args.stdenv.mkDerivation (args // {
            </term>
            <listitem>
             <para>
-             <filename>applications/networking/browsers</filename> (e.g.
-             <filename>firefox</filename>)
+             <filename>applications/networking/browsers</filename> (e.g. <filename>firefox</filename>)
             </para>
            </listitem>
           </varlistentry>
@@ -719,8 +632,7 @@ args.stdenv.mkDerivation (args // {
            </term>
            <listitem>
             <para>
-             <filename>data/sgml+xml/schemas/xml-dtd</filename> (e.g.
-             <filename>docbook</filename>)
+             <filename>data/sgml+xml/schemas/xml-dtd</filename> (e.g. <filename>docbook</filename>)
             </para>
            </listitem>
           </varlistentry>
@@ -733,8 +645,7 @@ args.stdenv.mkDerivation (args // {
              (Okay, these are executable...)
             </para>
             <para>
-             <filename>data/sgml+xml/stylesheets/xslt</filename> (e.g.
-             <filename>docbook-xsl</filename>)