lib/generators: add manual documentation

Restructures the functions reference a bit.

doc/functions.xml

@@ -8,6 +8,15 @@
   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>
 
@@ -258,6 +267,40 @@ c = lib.makeOverridable f { a = 1; b = 2; }</programlisting>
 
   </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>

lib/generators.nix

@@ -1,6 +1,11 @@
-/* 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