lib/generators: add manual documentation

  The nixpkgs repository has several utility functions to manipulate Nix expressions.

</para>

<section xml:id="sec-overrides">

  <title>Overriding</title>

  <para>

    Sometimes one wants to override parts of

    <literal>nixpkgs</literal>, e.g. derivation attributes, the results of

    derivations or even the whole package set.

  </para>

  <section xml:id="sec-pkgs-overridePackages">

    <title>pkgs.overridePackages</title>

  </section>

</section>

<section xml:id="sec-generators">

  <title>Generators</title>

  <para>

    Generators are functions that create file formats from nix

    data structures, e. g. for configuration files.

    There are generators available for: <literal>INI</literal>,

    <literal>JSON</literal> and <literal>YAML</literal>

  </para>

  <para>

    All generators follow a similar call interface: <code>generatorName

    configFunctions data</code>, where <literal>configFunctions</literal> is a

    set of user-defined functions that format variable parts of the content.

    They each have common defaults, so often they do not need to be set

    manually. An example is <code>mkSectionName ? (name: libStr.escape [ "[" "]"

    ] name)</code> from the <literal>INI</literal> generator. It gets the name

    of a section and returns a sanitized name. The default

    <literal>mkSectionName</literal> escapes <literal>[</literal> and

    <literal>]</literal> with a backslash. 

  </para>

  <note><para>Nix store paths can be converted to strings by enclosing a

  derivation attribute like so: <code>"${drv}"</code>.</para></note>

  <para>

    Detailed documentation for each generator can be found in

    <literal>lib/generators.nix</literal>.

  </para>

</section>

<section xml:id="sec-fhs-environments">

  <title>buildFHSUserEnv</title>

/* Functions that generate widespread config file

/* Functions that generate widespread file

 * formats from nix data structures.

 *

 * They all follow a similar interface:

 * generator { config-attrs } data

 *

 * Tests can be found in ./tests.nix

 * Documentation in the manual, #sec-generators

 */

with import ./trivial.nix;

let