nixpkgs docs: format =)

1 files changed, 277 insertions, 223 deletions

diff --git a/doc/languages-frameworks/beam.xml b/doc/languages-frameworks/beam.xml
index 1a18ed27237..ac7a83ed426 100644
--- a/doc/languages-frameworks/beam.xml
+++ b/doc/languages-frameworks/beam.xml
@@ -1,124 +1,137 @@
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="sec-beam">
+ <title>BEAM Languages (Erlang, Elixir &amp; LFE)</title>
 
-  <title>BEAM Languages (Erlang, Elixir &amp; LFE)</title>
-  <section xml:id="beam-introduction">
-    <title>Introduction</title>
-    <para>
-      In this document and related Nix expressions, we use the term,
-      <emphasis>BEAM</emphasis>, to describe the environment. BEAM is the name
-      of the Erlang Virtual Machine and, as far as we're concerned, from a
-      packaging perspective, all languages that run on the BEAM are
-      interchangeable. That which varies, like the build system, is transparent
-      to users of any given BEAM package, so we make no distinction.
-    </para>
-  </section>
-  <section xml:id="beam-structure">
-    <title>Structure</title>
-    <para>
-      All BEAM-related expressions are available via the top-level
-      <literal>beam</literal> attribute, which includes:
-    </para>
-    <itemizedlist>
-      <listitem>
-        <para>
-          <literal>interpreters</literal>: a set of compilers running on the
-          BEAM, including multiple Erlang/OTP versions
-          (<literal>beam.interpreters.erlangR19</literal>, etc), Elixir
-          (<literal>beam.interpreters.elixir</literal>) and LFE
-          (<literal>beam.interpreters.lfe</literal>).
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          <literal>packages</literal>: a set of package sets, each compiled with
-          a specific Erlang/OTP version, e.g.
-          <literal>beam.packages.erlangR19</literal>.
-        </para>
-      </listitem>
-    </itemizedlist>
-    <para>
-      The default Erlang compiler, defined by
-      <literal>beam.interpreters.erlang</literal>, is aliased as
-      <literal>erlang</literal>. The default BEAM package set is defined by
-      <literal>beam.packages.erlang</literal> and aliased at the top level as
-      <literal>beamPackages</literal>.
-    </para>
+ <section xml:id="beam-introduction">
+  <title>Introduction</title>
+
+  <para>
+   In this document and related Nix expressions, we use the term,
+   <emphasis>BEAM</emphasis>, to describe the environment. BEAM is the name of
+   the Erlang Virtual Machine and, as far as we're concerned, from a packaging
+   perspective, all languages that run on the BEAM are interchangeable. That
+   which varies, like the build system, is transparent to users of any given
+   BEAM package, so we make no distinction.
+  </para>
+ </section>
+
+ <section xml:id="beam-structure">
+  <title>Structure</title>
+
+  <para>
+   All BEAM-related expressions are available via the top-level
+   <literal>beam</literal> attribute, which includes:
+  </para>
+
+  <itemizedlist>
+   <listitem>
     <para>
-      To create a package set built with a custom Erlang version, use the
-      lambda, <literal>beam.packagesWith</literal>, which accepts an Erlang/OTP
-      derivation and produces a package set similar to
-      <literal>beam.packages.erlang</literal>.
+     <literal>interpreters</literal>: a set of compilers running on the BEAM,
+     including multiple Erlang/OTP versions
+     (<literal>beam.interpreters.erlangR19</literal>, etc), Elixir
+     (<literal>beam.interpreters.elixir</literal>) and LFE
+     (<literal>beam.interpreters.lfe</literal>).
     </para>
+   </listitem>
+   <listitem>
     <para>
-      Many Erlang/OTP distributions available in
-      <literal>beam.interpreters</literal> have versions with ODBC and/or Java
-      enabled. For example, there's
-      <literal>beam.interpreters.erlangR19_odbc_javac</literal>, which
-      corresponds to <literal>beam.interpreters.erlangR19</literal>.
+     <literal>packages</literal>: a set of package sets, each compiled with a
+     specific Erlang/OTP version, e.g.
+     <literal>beam.packages.erlangR19</literal>.
     </para>
-    <para xml:id="erlang-call-package">
-      We also provide the lambda,
-      <literal>beam.packages.erlang.callPackage</literal>, which simplifies
-      writing BEAM package definitions by injecting all packages from
-      <literal>beam.packages.erlang</literal> into the top-level context.
-    </para>
-  </section>
-  <section xml:id="build-tools">
+   </listitem>
+  </itemizedlist>
+
+  <para>
+   The default Erlang compiler, defined by
+   <literal>beam.interpreters.erlang</literal>, is aliased as
+   <literal>erlang</literal>. The default BEAM package set is defined by
+   <literal>beam.packages.erlang</literal> and aliased at the top level as
+   <literal>beamPackages</literal>.
+  </para>
+
+  <para>
+   To create a package set built with a custom Erlang version, use the lambda,
+   <literal>beam.packagesWith</literal>, which accepts an Erlang/OTP derivation
+   and produces a package set similar to
+   <literal>beam.packages.erlang</literal>.
+  </para>
+
+  <para>
+   Many Erlang/OTP distributions available in
+   <literal>beam.interpreters</literal> have versions with ODBC and/or Java
+   enabled. For example, there's
+   <literal>beam.interpreters.erlangR19_odbc_javac</literal>, which corresponds
+   to <literal>beam.interpreters.erlangR19</literal>.
+  </para>
+
+  <para xml:id="erlang-call-package">
+   We also provide the lambda,
+   <literal>beam.packages.erlang.callPackage</literal>, which simplifies
+   writing BEAM package definitions by injecting all packages from
+   <literal>beam.packages.erlang</literal> into the top-level context.
+  </para>
+ </section>
+
+ <section xml:id="build-tools">
   <title>Build Tools</title>
+
   <section xml:id="build-tools-rebar3">
-    <title>Rebar3</title>
-    <para>
-      By default, Rebar3 wants to manage its own dependencies. This is perfectly
-      acceptable in the normal, non-Nix setup, but in the Nix world, it is not.
-      To rectify this, we provide two versions of Rebar3:
-      <itemizedlist>
-        <listitem>
-          <para>
-            <literal>rebar3</literal>: patched to remove the ability to download
-            anything. When not running it via <literal>nix-shell</literal> or
-            <literal>nix-build</literal>, it's probably not going to work as
-            desired.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            <literal>rebar3-open</literal>: the normal, unmodified Rebar3. It
-            should work exactly as would any other version of Rebar3. Any Erlang
-            package should rely on <literal>rebar3</literal> instead. See <xref
+   <title>Rebar3</title>
+
+   <para>
+    By default, Rebar3 wants to manage its own dependencies. This is perfectly
+    acceptable in the normal, non-Nix setup, but in the Nix world, it is not.
+    To rectify this, we provide two versions of Rebar3:
+    <itemizedlist>
+     <listitem>
+      <para>
+       <literal>rebar3</literal>: patched to remove the ability to download
+       anything. When not running it via <literal>nix-shell</literal> or
+       <literal>nix-build</literal>, it's probably not going to work as
+       desired.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       <literal>rebar3-open</literal>: the normal, unmodified Rebar3. It should
+       work exactly as would any other version of Rebar3. Any Erlang package
+       should rely on <literal>rebar3</literal> instead. See
+       <xref
             linkend="rebar3-packages"/>.
-          </para>
-        </listitem>
-      </itemizedlist>
-    </para>
+      </para>
+     </listitem>
+    </itemizedlist>
+   </para>
   </section>
+
   <section xml:id="build-tools-other">
-    <title>Mix &amp; Erlang.mk</title>
-    <para>
-      Both Mix and Erlang.mk work exactly as expected. There is a bootstrap
-      process that needs to be run for both, however, which is supported by the
-      <literal>buildMix</literal> and <literal>buildErlangMk</literal>
-      derivations, respectively.
-    </para>
+   <title>Mix &amp; Erlang.mk</title>
+
+   <para>
+    Both Mix and Erlang.mk work exactly as expected. There is a bootstrap
+    process that needs to be run for both, however, which is supported by the
+    <literal>buildMix</literal> and <literal>buildErlangMk</literal>
+    derivations, respectively.
+   </para>
   </section>
-</section>
+ </section>
 
-<section xml:id="how-to-install-beam-packages">
+ <section xml:id="how-to-install-beam-packages">
   <title>How to Install BEAM Packages</title>
+
   <para>
-    BEAM packages are not registered at the top level, simply because they are
-    not relevant to the vast majority of Nix users. They are installable using
-    the <literal>beam.packages.erlang</literal> attribute set (aliased as
-    <literal>beamPackages</literal>), which points to packages built by the
-    default Erlang/OTP version in Nixpkgs, as defined by
-    <literal>beam.interpreters.erlang</literal>.
-
-    To list the available packages in
-    <literal>beamPackages</literal>, use the following command:
+   BEAM packages are not registered at the top level, simply because they are
+   not relevant to the vast majority of Nix users. They are installable using
+   the <literal>beam.packages.erlang</literal> attribute set (aliased as
+   <literal>beamPackages</literal>), which points to packages built by the
+   default Erlang/OTP version in Nixpkgs, as defined by
+   <literal>beam.interpreters.erlang</literal>. To list the available packages
+   in <literal>beamPackages</literal>, use the following command:
   </para>
 
-  <programlisting>
+<programlisting>
 $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -qaP -A beamPackages
 beamPackages.esqlite    esqlite-0.2.1
 beamPackages.goldrush   goldrush-0.1.7
@@ -128,34 +141,43 @@ beamPackages.lager      lager-3.0.2
 beamPackages.meck       meck-0.8.3
 beamPackages.rebar3-pc  pc-1.1.0
   </programlisting>
+
   <para>
-    To install any of those packages into your profile, refer to them by their
-    attribute path (first column):
+   To install any of those packages into your profile, refer to them by their
+   attribute path (first column):
   </para>
-  <programlisting>
+
+<programlisting>
 $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
   </programlisting>
+
   <para>
-    The attribute path of any BEAM package corresponds to the name of that
-    particular package in <link xlink:href="https://hex.pm">Hex</link> or its
-    OTP Application/Release name.
+   The attribute path of any BEAM package corresponds to the name of that
+   particular package in <link xlink:href="https://hex.pm">Hex</link> or its
+   OTP Application/Release name.
   </para>
-</section>
-<section xml:id="packaging-beam-applications">
+ </section>
+
+ <section xml:id="packaging-beam-applications">
   <title>Packaging BEAM Applications</title>
+
   <section  xml:id="packaging-erlang-applications">
-    <title>Erlang Applications</title>
-    <section xml:id="rebar3-packages">
-      <title>Rebar3 Packages</title>
-      <para>
-        The Nix function, <literal>buildRebar3</literal>, defined in
-        <literal>beam.packages.erlang.buildRebar3</literal> and aliased at the
-        top level, can be used to build a derivation that understands how to
-        build a Rebar3 project. For example, we can build <link
-        xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link> as
-        follows:
-      </para>
-      <programlisting>
+   <title>Erlang Applications</title>
+
+   <section xml:id="rebar3-packages">
+    <title>Rebar3 Packages</title>
+
+    <para>
+     The Nix function, <literal>buildRebar3</literal>, defined in
+     <literal>beam.packages.erlang.buildRebar3</literal> and aliased at the top
+     level, can be used to build a derivation that understands how to build a
+     Rebar3 project. For example, we can build
+     <link
+        xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link>
+     as follows:
+    </para>
+
+<programlisting>
         { stdenv, fetchFromGitHub, buildRebar3, ibrowse, jsx, erlware_commons }:
 
         buildRebar3 rec {
@@ -172,33 +194,40 @@ $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
           beamDeps = [ ibrowse jsx erlware_commons ];
         }
       </programlisting>
-      <para>
-        Such derivations are callable with
-        <literal>beam.packages.erlang.callPackage</literal> (see <xref
-        linkend="erlang-call-package"/>). To call this package using the normal
-        <literal>callPackage</literal>, refer to dependency packages via
-        <literal>beamPackages</literal>, e.g.
-        <literal>beamPackages.ibrowse</literal>.
-      </para>
-      <para>
-        Notably, <literal>buildRebar3</literal> includes
-        <literal>beamDeps</literal>, while
-        <literal>stdenv.mkDerivation</literal> does not. BEAM dependencies added
-        there will be correctly handled by the system.
-      </para>
-      <para>
-        If a package needs to compile native code via Rebar3's port compilation
-        mechanism, add <literal>compilePort = true;</literal> to the derivation.
-      </para>
-    </section>
-    <section xml:id="erlang-mk-packages">
-      <title>Erlang.mk Packages</title>
-      <para>
-        Erlang.mk functions similarly to Rebar3, except we use
-        <literal>buildErlangMk</literal> instead of
-        <literal>buildRebar3</literal>.
-      </para>
-      <programlisting>
+
+    <para>
+     Such derivations are callable with
+     <literal>beam.packages.erlang.callPackage</literal> (see
+     <xref
+        linkend="erlang-call-package"/>). To call this package using
+     the normal <literal>callPackage</literal>, refer to dependency packages
+     via <literal>beamPackages</literal>, e.g.
+     <literal>beamPackages.ibrowse</literal>.
+    </para>
+
+    <para>
+     Notably, <literal>buildRebar3</literal> includes
+     <literal>beamDeps</literal>, while <literal>stdenv.mkDerivation</literal>
+     does not. BEAM dependencies added there will be correctly handled by the
+     system.
+    </para>
+
+    <para>
+     If a package needs to compile native code via Rebar3's port compilation
+     mechanism, add <literal>compilePort = true;</literal> to the derivation.
+    </para>
+   </section>
+
+   <section xml:id="erlang-mk-packages">
+    <title>Erlang.mk Packages</title>
+
+    <para>
+     Erlang.mk functions similarly to Rebar3, except we use
+     <literal>buildErlangMk</literal> instead of
+     <literal>buildRebar3</literal>.
+    </para>
+
+<programlisting>
         { buildErlangMk, fetchHex, cowlib, ranch }:
 
         buildErlangMk {
@@ -222,14 +251,17 @@ $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
           };
         }
       </programlisting>
-    </section>
-    <section xml:id="mix-packages">
-      <title>Mix Packages</title>
-      <para>
-        Mix functions similarly to Rebar3, except we use
-        <literal>buildMix</literal> instead of <literal>buildRebar3</literal>.
-      </para>
-      <programlisting>
+   </section>
+
+   <section xml:id="mix-packages">
+    <title>Mix Packages</title>
+
+    <para>
+     Mix functions similarly to Rebar3, except we use
+     <literal>buildMix</literal> instead of <literal>buildRebar3</literal>.
+    </para>
+
+<programlisting>
         { buildMix, fetchHex, plug, absinthe }:
 
         buildMix {
@@ -253,10 +285,12 @@ $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
           };
         }
       </programlisting>
-      <para>
-        Alternatively, we can use <literal>buildHex</literal> as a shortcut:
-      </para>
-      <programlisting>
+
+    <para>
+     Alternatively, we can use <literal>buildHex</literal> as a shortcut:
+    </para>
+
+<programlisting>
         { buildHex, buildMix, plug, absinthe }:
 
         buildHex {
@@ -278,21 +312,25 @@ $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
          };
        }
       </programlisting>
-    </section>
+   </section>
   </section>
-</section>
-<section xml:id="how-to-develop">
+ </section>
+
+ <section xml:id="how-to-develop">
   <title>How to Develop</title>
+
   <section xml:id="accessing-an-environment">
-    <title>Accessing an Environment</title>
-    <para>
-      Often, we simply want to access a valid environment that contains a
-      specific package and its dependencies. We can accomplish that with the
-      <literal>env</literal> attribute of a derivation. For example, let's say
-      we want to access an Erlang REPL with <literal>ibrowse</literal> loaded
-      up. We could do the following:
-    </para>
-    <programlisting>
+   <title>Accessing an Environment</title>
+
+   <para>
+    Often, we simply want to access a valid environment that contains a
+    specific package and its dependencies. We can accomplish that with the
+    <literal>env</literal> attribute of a derivation. For example, let's say we
+    want to access an Erlang REPL with <literal>ibrowse</literal> loaded up. We
+    could do the following:
+   </para>
+
+<programlisting>
       $ nix-shell -A beamPackages.ibrowse.env --run "erl"
       Erlang/OTP 18 [erts-7.0] [source] [64-bit] [smp:4:4] [async-threads:10] [hipe] [kernel-poll:false]
 
@@ -333,22 +371,25 @@ $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
       ok
       2>
     </programlisting>
-    <para>
-      Notice the <literal>-A beamPackages.ibrowse.env</literal>. That is the key
-      to this functionality.
-    </para>
+
+   <para>
+    Notice the <literal>-A beamPackages.ibrowse.env</literal>. That is the key
+    to this functionality.
+   </para>
   </section>
+
   <section xml:id="creating-a-shell">
-    <title>Creating a Shell</title>
-    <para>
-      Getting access to an environment often isn't enough to do real
-      development. Usually, we need to create a <literal>shell.nix</literal>
-      file and do our development inside of the environment specified therein.
-      This file looks a lot like the packaging described above, except that
-      <literal>src</literal> points to the project root and we call the package
-      directly.
-    </para>
-    <programlisting>
+   <title>Creating a Shell</title>
+
+   <para>
+    Getting access to an environment often isn't enough to do real development.
+    Usually, we need to create a <literal>shell.nix</literal> file and do our
+    development inside of the environment specified therein. This file looks a
+    lot like the packaging described above, except that <literal>src</literal>
+    points to the project root and we call the package directly.
+   </para>
+
+<programlisting>
 { pkgs ? import &quot;&lt;nixpkgs&quot;&gt; {} }:
 
 with pkgs;
@@ -368,13 +409,16 @@ in
 
   drv
     </programlisting>
-    <section xml:id="building-in-a-shell">
+
+   <section xml:id="building-in-a-shell">
     <title>Building in a Shell (for Mix Projects)</title>
+
     <para>
-      We can leverage the support of the derivation, irrespective of the build
-      derivation, by calling the commands themselves.
+     We can leverage the support of the derivation, irrespective of the build
+     derivation, by calling the commands themselves.
     </para>
-    <programlisting>
+
+<programlisting>
 # =============================================================================
 # Variables
 # =============================================================================
@@ -431,44 +475,54 @@ analyze: build plt
         $(NIX_SHELL) --run "mix dialyzer --no-compile"
 
     </programlisting>
+
     <para>
-      Using a <literal>shell.nix</literal> as described (see <xref
+     Using a <literal>shell.nix</literal> as described (see
+     <xref
       linkend="creating-a-shell"/>) should just work. Aside from
-      <literal>test</literal>, <literal>plt</literal>, and
-      <literal>analyze</literal>, the Make targets work just fine for all of the
-      build derivations.
+     <literal>test</literal>, <literal>plt</literal>, and
+     <literal>analyze</literal>, the Make targets work just fine for all of the
+     build derivations.
     </para>
+   </section>
   </section>
-</section>
-</section>
-<section xml:id="generating-packages-from-hex-with-hex2nix">
+ </section>
+
+ <section xml:id="generating-packages-from-hex-with-hex2nix">
   <title>Generating Packages from Hex with <literal>hex2nix</literal></title>
+
   <para>
-    Updating the <link xlink:href="https://hex.pm">Hex</link> package set
-    requires <link
-    xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link>. Given the
-    path to the Erlang modules (usually
-    <literal>pkgs/development/erlang-modules</literal>), it will dump a file
-    called <literal>hex-packages.nix</literal>, containing all the packages that
-    use a recognized build system in <link
-    xlink:href="https://hex.pm">Hex</link>. It can't be determined, however,
-    whether every package is buildable.
-    </para>
-    <para>
-      To make life easier for our users, try to build every <link
-      xlink:href="https://hex.pm">Hex</link> package and remove those that fail.
-      To do that, simply run the following command in the root of your
-      <literal>nixpkgs</literal> repository:
-    </para>
-    <programlisting>
+   Updating the <link xlink:href="https://hex.pm">Hex</link> package set
+   requires
+   <link
+    xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link>.
+   Given the path to the Erlang modules (usually
+   <literal>pkgs/development/erlang-modules</literal>), it will dump a file
+   called <literal>hex-packages.nix</literal>, containing all the packages that
+   use a recognized build system in
+   <link
+    xlink:href="https://hex.pm">Hex</link>. It can't be determined,
+   however, whether every package is buildable.
+  </para>
+
+  <para>
+   To make life easier for our users, try to build every
+   <link
+      xlink:href="https://hex.pm">Hex</link> package and remove those
+   that fail. To do that, simply run the following command in the root of your
+   <literal>nixpkgs</literal> repository:
+  </para>
+
+<programlisting>
 $ nix-build -A beamPackages
     </programlisting>
-    <para>
-      That will attempt to build every package in
-      <literal>beamPackages</literal>. Then manually remove those that fail.
-      Hopefully, someone will improve <link
-      xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link> in the
-      future to automate the process.
-    </para>
-</section>
+
+  <para>
+   That will attempt to build every package in <literal>beamPackages</literal>.
+   Then manually remove those that fail. Hopefully, someone will improve
+   <link
+      xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link>
+   in the future to automate the process.
+  </para>
+ </section>
 </section>