doc: auto-generate asserts and attrset library docs

If all the docs are auto-generated, it should be easier to convert
them to Commonmark.

Co-Authored-By: Valentin Gagarin <valentin.gagarin@tweag.io>
Co-Authored-By: Silvan Mosberger <contact@infinisil.com>

4 files changed, 4 insertions, 1867 deletions

diff --git a/doc/functions/library.xml b/doc/functions/library.xml
index b291356c14b8..0a8bae229f26 100644
--- a/doc/functions/library.xml
+++ b/doc/functions/library.xml
@@ -8,14 +8,14 @@
   Nixpkgs provides a standard library at <varname>pkgs.lib</varname>, or through <code>import &lt;nixpkgs/lib&gt;</code>.
  </para>
 
- <xi:include href="./library/asserts.xml" />
-
- <xi:include href="./library/attrsets.xml" />
-
 <!-- These docs are generated via nixdoc. To add another generated
       library function file to this list, the file
       `lib-function-docs.nix` must also be updated. -->
 
+ <xi:include href="./library/generated/asserts.xml" />
+
+ <xi:include href="./library/generated/attrsets.xml" />
+
  <xi:include href="./library/generated/strings.xml" />
 
  <xi:include href="./library/generated/trivial.xml" />
diff --git a/doc/functions/library/.gitkeep b/doc/functions/library/.gitkeep
new file mode 100644
index 000000000000..e69de29bb2d1
--- /dev/null
+++ b/doc/functions/library/.gitkeep
diff --git a/doc/functions/library/asserts.xml b/doc/functions/library/asserts.xml
deleted file mode 100644
index 7c94222ef139..000000000000
--- a/doc/functions/library/asserts.xml
+++ /dev/null
@@ -1,112 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         xml:id="sec-functions-library-asserts">
- <title>Assert functions</title>
-
- <section xml:id="function-library-lib.asserts.assertMsg">
-  <title><function>lib.asserts.assertMsg</function></title>
-
-  <subtitle><literal>assertMsg :: Bool -> String -> Bool</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.asserts.assertMsg" />
-
-  <para>
-   Print a trace message if <literal>pred</literal> is false.
-  </para>
-
-  <para>
-   Intended to be used to augment asserts with helpful error messages.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>pred</varname>
-    </term>
-    <listitem>
-     <para>
-      Condition under which the <varname>msg</varname> should <emphasis>not</emphasis> be printed.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>msg</varname>
-    </term>
-    <listitem>
-     <para>
-      Message to print.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.asserts.assertMsg-example-false">
-   <title>Printing when the predicate is false</title>
-<programlisting><![CDATA[
-assert lib.asserts.assertMsg ("foo" == "bar") "foo is not bar, silly"
-stderr> trace: foo is not bar, silly
-stderr> assert failed
-]]></programlisting>
-  </example>
- </section>
-
- <section xml:id="function-library-lib.asserts.assertOneOf">
-  <title><function>lib.asserts.assertOneOf</function></title>
-
-  <subtitle><literal>assertOneOf :: String -> String ->
-      StringList -> Bool</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.asserts.assertOneOf" />
-
-  <para>
-   Specialized <function>asserts.assertMsg</function> for checking if <varname>val</varname> is one of the elements of <varname>xs</varname>. Useful for checking enums.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>name</varname>
-    </term>
-    <listitem>
-     <para>
-      The name of the variable the user entered <varname>val</varname> into, for inclusion in the error message.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>val</varname>
-    </term>
-    <listitem>
-     <para>
-      The value of what the user provided, to be compared against the values in <varname>xs</varname>.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>xs</varname>
-    </term>
-    <listitem>
-     <para>
-      The list of valid values.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.asserts.assertOneOf-example">
-   <title>Ensuring a user provided a possible value</title>
-<programlisting><![CDATA[
-let sslLibrary = "bearssl";
-in lib.asserts.assertOneOf "sslLibrary" sslLibrary [ "openssl" "libressl" ];
-=> false
-stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl"
-        ]]></programlisting>
-  </example>
- </section>
-</section>
diff --git a/doc/functions/library/attrsets.xml b/doc/functions/library/attrsets.xml
deleted file mode 100644
index 052bfa1f6ae3..000000000000
--- a/doc/functions/library/attrsets.xml
+++ /dev/null
@@ -1,1751 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         xml:id="sec-functions-library-attrset">
- <title>Attribute-Set Functions</title>
-
- <section xml:id="function-library-lib.attrsets.attrByPath">
-  <title><function>lib.attrset.attrByPath</function></title>
-
-  <subtitle><literal>attrByPath :: [String] -> Any -> AttrSet -> Any</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.attrsets.attrByPath" />
-
-  <para>
-   Return an attribute from within nested attribute sets.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>attrPath</varname>
-    </term>
-    <listitem>
-     <para>
-      A list of strings representing the path through the nested attribute set <varname>set</varname>.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>default</varname>
-    </term>
-    <listitem>
-     <para>
-      Default value if <varname>attrPath</varname> does not resolve to an existing value.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>set</varname>
-    </term>
-    <listitem>
-     <para>
-      The nested attributeset to select values from.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.attrset.attrByPath-example-value-exists">
-   <title>Extracting a value from a nested attribute set</title>
-<programlisting><![CDATA[
-let set = { a = { b = 3; }; };
-in lib.attrsets.attrByPath [ "a" "b" ] 0 set
-=> 3
-]]></programlisting>
-  </example>
-
-  <example xml:id="function-library-lib.attrset.attrByPath-example-default-value">
-   <title>No value at the path, instead using the default</title>
-<programlisting><![CDATA[
-lib.attrsets.attrByPath [ "a" "b" ] 0 {}
-=> 0
-]]></programlisting>
-  </example>
- </section>
-
- <section xml:id="function-library-lib.attrsets.hasAttrByPath">
-  <title><function>lib.attrsets.hasAttrByPath</function></title>
-
-  <subtitle><literal>hasAttrByPath :: [String] -> AttrSet -> Bool</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.attrsets.hasAttrByPath" />
-
-  <para>
-   Determine if an attribute exists within a nested attribute set.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>attrPath</varname>
-    </term>
-    <listitem>
-     <para>
-      A list of strings representing the path through the nested attribute set <varname>set</varname>.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>set</varname>
-    </term>
-    <listitem>
-     <para>
-      The nested attributeset to check.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.attrsets.hasAttrByPath-example">
-   <title>A nested value does exist inside a set</title>
-<programlisting><![CDATA[
-lib.attrsets.hasAttrByPath
-  [ "a" "b" "c" "d" ]
-  { a = { b = { c = { d = 123; }; }; }; }
-=> true
-]]></programlisting>
-  </example>
- </section>
-
- <section xml:id="function-library-lib.attrsets.setAttrByPath">
-  <title><function>lib.attrsets.setAttrByPath</function></title>
-
-  <subtitle><literal>setAttrByPath :: [String] -> Any -> AttrSet</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.attrsets.setAttrByPath" />
-
-  <para>
-   Create a new attribute set with <varname>value</varname> set at the nested attribute location specified in <varname>attrPath</varname>.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>attrPath</varname>
-    </term>
-    <listitem>
-     <para>
-      A list of strings representing the path through the nested attribute set.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>value</varname>
-    </term>
-    <listitem>
-     <para>
-      The value to set at the location described by <varname>attrPath</varname>.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.attrsets.setAttrByPath-example">
-   <title>Creating a new nested attribute set</title>
-<programlisting><![CDATA[
-lib.attrsets.setAttrByPath [ "a" "b" ] 3
-=> { a = { b = 3; }; }
-]]></programlisting>
-  </example>
- </section>
-
- <section xml:id="function-library-lib.attrsets.getAttrFromPath">
-  <title><function>lib.attrsets.getAttrFromPath</function></title>
-
-  <subtitle><literal>getAttrFromPath :: [String] -> AttrSet -> Value</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.attrsets.getAttrFromPath" />
-
-  <para>
-   Like <xref linkend="function-library-lib.attrsets.attrByPath" /> except without a default, and it will throw if the value doesn't exist.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>attrPath</varname>
-    </term>
-    <listitem>
-     <para>
-      A list of strings representing the path through the nested attribute set <varname>set</varname>.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>set</varname>
-    </term>
-    <listitem>
-     <para>
-      The nested attribute set to find the value in.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.attrsets.getAttrPath-example-success">
-   <title>Succesfully getting a value from an attribute set</title>
-<programlisting><![CDATA[
-lib.attrsets.getAttrFromPath [ "a" "b" ] { a = { b = 3; }; }
-=> 3
-]]></programlisting>
-  </example>
-
-  <example xml:id="function-library-lib.attrsets.getAttrPath-example-throw">
-   <title>Throwing after failing to get a value from an attribute set</title>
-<programlisting><![CDATA[
-lib.attrsets.getAttrFromPath [ "x" "y" ] { }
-=> error: cannot find attribute `x.y'
-]]></programlisting>
-  </example>
- </section>
-
- <section xml:id="function-library-lib.attrsets.attrVals">
-  <title><function>lib.attrsets.attrVals</function></title>
-
-  <subtitle><literal>attrVals :: [String] -> AttrSet -> [Any]</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.attrsets.attrVals" />
-
-  <para>
-   Return the specified attributes from a set. All values must exist.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>nameList</varname>
-    </term>
-    <listitem>
-     <para>
-      The list of attributes to fetch from <varname>set</varname>. Each attribute name must exist on the attrbitue set.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>set</varname>
-    </term>
-    <listitem>
-     <para>
-      The set to get attribute values from.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.attrsets.attrVals-example-success">
-   <title>Getting several values from an attribute set</title>
-<programlisting><![CDATA[
-lib.attrsets.attrVals [ "a" "b" "c" ] { a = 1; b = 2; c = 3; }
-=> [ 1 2 3 ]
-]]></programlisting>
-  </example>
-
-  <example xml:id="function-library-lib.attrsets.attrVals-failure">
-   <title>Getting missing values from an attribute set</title>
-<programlisting><![CDATA[
-lib.attrsets.attrVals [ "d" ] { }
-error: attribute 'd' missing
-]]></programlisting>
-  </example>
- </section>
-
- <section xml:id="function-library-lib.attrsets.attrValues">
-  <title><function>lib.attrsets.attrValues</function></title>
-
-  <subtitle><literal>attrValues :: AttrSet -> [Any]</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.attrsets.attrValues" />
-
-  <para>
-   Get all the attribute values from an attribute set.
-  </para>
-
-  <para>
-   Provides a backwards-compatible interface of <function>builtins.attrValues</function> for Nix version older than 1.8.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>attrs</varname>
-    </term>
-    <listitem>
-     <para>
-      The attribute set.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.attrsets.attrValues-example">
-   <title></title>
-<programlisting><![CDATA[
-lib.attrsets.attrValues { a = 1; b = 2; c = 3; }
-=> [ 1 2 3 ]
-]]></programlisting>
-  </example>
- </section>
-
- <section xml:id="function-library-lib.attrsets.catAttrs">
-  <title><function>lib.attrsets.catAttrs</function></title>
-
-  <subtitle><literal>catAttrs :: String -> [AttrSet] -> [Any]</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.attrsets.catAttrs" />
-
-  <para>
-   Collect each attribute named `attr' from the list of attribute sets, <varname>sets</varname>. Sets that don't contain the named attribute are ignored.
-  </para>
-
-  <para>
-   Provides a backwards-compatible interface of <function>builtins.catAttrs</function> for Nix version older than 1.9.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>attr</varname>
-    </term>
-    <listitem>
-     <para>
-      Attribute name to select from each attribute set in <varname>sets</varname>.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>sets</varname>
-    </term>
-    <listitem>
-     <para>
-      The list of attribute sets to select <varname>attr</varname> from.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.attrsets.catAttrs-example">
-   <title>Collect an attribute from a list of attribute sets.</title>
-   <para>
-    Attribute sets which don't have the attribute are ignored.
-   </para>
-<programlisting><![CDATA[
-catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}]
-=> [ 1 2 ]
-      ]]></programlisting>
-  </example>
- </section>
-
- <section xml:id="function-library-lib.attrsets.filterAttrs">
-  <title><function>lib.attrsets.filterAttrs</function></title>
-
-  <subtitle><literal>filterAttrs :: (String -> Any -> Bool) -> AttrSet -> AttrSet</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.attrsets.filterAttrs" />
-
-  <para>
-   Filter an attribute set by removing all attributes for which the given predicate return false.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>pred</varname>
-    </term>
-    <listitem>
-     <para>
-      <literal>String -> Any -> Bool</literal>
-     </para>
-     <para>
-      Predicate which returns true to include an attribute, or returns false to exclude it.
-     </para>
-     <variablelist>
-      <varlistentry>
-       <term>
-        <varname>name</varname>
-       </term>
-       <listitem>
-        <para>
-         The attribute's name
-        </para>
-       </listitem>
-      </varlistentry>
-      <varlistentry>
-       <term>
-        <varname>value</varname>
-       </term>
-       <listitem>
-        <para>
-         The attribute's value
-        </para>
-       </listitem>
-      </varlistentry>
-     </variablelist>
-     <para>
-      Returns <literal>true</literal> to include the attribute, <literal>false</literal> to exclude the attribute.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>set</varname>
-    </term>
-    <listitem>
-     <para>
-      The attribute set to filter
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.attrsets.filterAttrs-example">
-   <title>Filtering an attributeset</title>
-<programlisting><![CDATA[
-filterAttrs (n: v: n == "foo") { foo = 1; bar = 2; }
-=> { foo = 1; }
-]]></programlisting>
-  </example>
- </section>
-
- <section xml:id="function-library-lib.attrsets.filterAttrsRecursive">
-  <title><function>lib.attrsets.filterAttrsRecursive</function></title>
-
-  <subtitle><literal>filterAttrsRecursive :: (String -> Any -> Bool) -> AttrSet -> AttrSet</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.attrsets.filterAttrsRecursive" />
-
-  <para>
-   Filter an attribute set recursively by removing all attributes for which the given predicate return false.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>pred</varname>
-    </term>
-    <listitem>
-     <para>
-      <literal>String -> Any -> Bool</literal>
-     </para>
-     <para>
-      Predicate which returns true to include an attribute, or returns false to exclude it.
-     </para>
-     <variablelist>
-      <varlistentry>
-       <term>
-        <varname>name</varname>
-       </term>
-       <listitem>
-        <para>
-         The attribute's name
-        </para>
-       </listitem>
-      </varlistentry>
-      <varlistentry>
-       <term>
-        <varname>value</varname>
-       </term>
-       <listitem>
-        <para>
-         The attribute's value
-        </para>
-       </listitem>
-      </varlistentry>
-     </variablelist>
-     <para>
-      Returns <literal>true</literal> to include the attribute, <literal>false</literal> to exclude the attribute.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>set</varname>
-    </term>
-    <listitem>
-     <para>
-      The attribute set to filter
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.attrsets.filterAttrsRecursive-example">
-   <title>Recursively filtering an attribute set</title>
-<programlisting><![CDATA[
-lib.attrsets.filterAttrsRecursive
-  (n: v: v != null)
-  {
-    levelA = {
-      example = "hi";
-      levelB = {
-        hello = "there";
-        this-one-is-present = {
-          this-is-excluded = null;
-        };
-      };
-      this-one-is-also-excluded = null;
-    };
-    also-excluded = null;
-  }
-=> {
-     levelA = {
-       example = "hi";
-       levelB = {
-         hello = "there";
-         this-one-is-present = { };
-       };
-     };
-   }
-     ]]></programlisting>
-  </example>
- </section>
-
- <section xml:id="function-library-lib.attrsets.foldAttrs">
-  <title><function>lib.attrsets.foldAttrs</function></title>
-
-  <subtitle><literal>foldAttrs :: (Any -> Any -> Any) -> Any -> [AttrSets] -> Any</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.attrsets.foldAttrs" />
-
-  <para>
-   Apply fold function to values grouped by key.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>op</varname>
-    </term>
-    <listitem>
-     <para>
-      <literal>Any -> Any -> Any</literal>
-     </para>
-     <para>
-      Given a value <varname>val</varname> and a collector <varname>col</varname>, combine the two.
-     </para>
-     <variablelist>
-      <varlistentry>
-       <term>
-        <varname>val</varname>
-       </term>
-       <listitem>
-        <para>
-         An attribute's value
-        </para>
-       </listitem>
-      </varlistentry>
-      <varlistentry>
-       <term>
-        <varname>col</varname>
-       </term>
-       <listitem>
-<!-- TODO: make this not bad, use more fold-ey terms -->
-        <para>
-         The result of previous <function>op</function> calls with other values and <function>nul</function>.
-        </para>
-       </listitem>
-      </varlistentry>
-     </variablelist>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>nul</varname>
-    </term>
-    <listitem>
-     <para>
-      The null-value, the starting value.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>list_of_attrs</varname>
-    </term>
-    <listitem>
-     <para>
-      A list of attribute sets to fold together by key.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.attrsets.foldAttrs-example">
-   <title>Combining an attribute of lists in to one attribute set</title>
-<programlisting><![CDATA[
-lib.attrsets.foldAttrs
-  (n: a: [n] ++ a) []
-  [
-    { a = 2; b = 7; }
-    { a = 3; }
-    { b = 6; }
-  ]
-=> { a = [ 2 3 ]; b = [ 7 6 ]; }
-]]></programlisting>
-  </example>
- </section>
-
- <section xml:id="function-library-lib.attrsets.collect">
-  <title><function>lib.attrsets.collect</function></title>
-
-  <subtitle><literal>collect :: (Any -> Bool) -> AttrSet -> [Any]</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.attrsets.collect" />
-
-  <para>
-   Recursively collect sets that verify a given predicate named <varname>pred</varname> from the set <varname>attrs</varname>. The recursion stops when <varname>pred</varname> returns <literal>true</literal>.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>pred</varname>
-    </term>
-    <listitem>
-     <para>
-      <literal>Any -> Bool</literal>
-     </para>
-     <para>
-      Given an attribute's value, determine if recursion should stop.
-     </para>
-     <variablelist>
-      <varlistentry>
-       <term>
-        <varname>value</varname>
-       </term>
-       <listitem>
-        <para>
-         The attribute set value.
-        </para>
-       </listitem>
-      </varlistentry>
-     </variablelist>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>attrs</varname>
-    </term>
-    <listitem>
-     <para>
-      The attribute set to recursively collect.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.attrsets.collect-example-lists">
-   <title>Collecting all lists from an attribute set</title>
-<programlisting><![CDATA[
-lib.attrsets.collect isList { a = { b = ["b"]; }; c = [1]; }
-=> [["b"] [1]]
-]]></programlisting>
-  </example>
-
-  <example xml:id="function-library-lib.attrsets.collect-example-outpath">
-   <title>Collecting all attribute-sets which contain the <literal>outPath</literal> attribute name.</title>
-<programlisting><![CDATA[
-collect (x: x ? outPath)
-  { a = { outPath = "a/"; }; b = { outPath = "b/"; }; }
-=> [{ outPath = "a/"; } { outPath = "b/"; }]
-]]></programlisting>
-  </example>
- </section>
-
- <section xml:id="function-library-lib.attrsets.nameValuePair">
-  <title><function>lib.attrsets.nameValuePair</function></title>
-
-  <subtitle><literal>nameValuePair :: String -> Any -> AttrSet</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.attrsets.nameValuePair" />
-
-  <para>
-   Utility function that creates a <literal>{name, value}</literal> pair as expected by <function>builtins.listToAttrs</function>.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>name</varname>
-    </term>
-    <listitem>
-     <para>
-      The attribute name.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>value</varname>
-    </term>
-    <listitem>
-     <para>
-      The attribute value.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.attrsets.nameValuePair-example">
-   <title>Creating a name value pair</title>
-<programlisting><![CDATA[
-nameValuePair "some" 6
-=> { name = "some"; value = 6; }
-]]></programlisting>
-  </example>
- </section>
-
- <section xml:id="function-library-lib.attrsets.mapAttrs">
-  <title><function>lib.attrsets.mapAttrs</function></title>
-
-  <subtitle><literal></literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrs" />
-
-  <para>
-   Apply a function to each element in an attribute set, creating a new attribute set.
-  </para>
-
-  <para>
-   Provides a backwards-compatible interface of <function>builtins.mapAttrs</function> for Nix version older than 2.1.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>fn</varname>
-    </term>
-    <listitem>
-     <para>
-      <literal>String -> Any -> Any</literal>
-     </para>
-     <para>
-      Given an attribute's name and value, return a new value.
-     </para>
-     <variablelist>
-      <varlistentry>
-       <term>
-        <varname>name</varname>
-       </term>
-       <listitem>
-        <para>
-         The name of the attribute.
-        </para>
-       </listitem>
-      </varlistentry>
-      <varlistentry>
-       <term>
-        <varname>value</varname>
-       </term>
-       <listitem>
-        <para>
-         The attribute's value.
-        </para>
-       </listitem>
-      </varlistentry>
-     </variablelist>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <example xml:id="function-library-lib.attrsets.mapAttrs-example">
-   <title>Modifying each value of an attribute set</title>
-<programlisting><![CDATA[
-lib.attrsets.mapAttrs
-  (name: value: name + "-" + value)
-  { x = "foo"; y = "bar"; }
-=> { x = "x-foo"; y = "y-bar"; }
-]]></programlisting>
-  </example>
- </section>
-
- <section xml:id="function-library-lib.attrsets.mapAttrs-prime">
-  <title><function>lib.attrsets.mapAttrs&apos;</function></title>
-
-  <subtitle><literal>mapAttrs' :: (String -> Any -> { name = String; value = Any }) -> AttrSet -> AttrSet</literal>
-  </subtitle>
-
-  <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrs-prime" />
-
-  <para>
-   Like <function>mapAttrs</function>, but allows the name of each attribute to be changed in addition to the value. The applied function should return both the new name and value as a <function>nameValuePair</function>.
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <varname>fn</varname>
-    </term>
-    <listitem>
-     <para>
-      <literal>String -> Any -> { name = String; value = Any }</literal>
-     </para>
-     <para>
-      Given an attribute's name and value, return a new <link
-       linkend="function-library-lib.attrsets.nameValuePair">name value pair</link>.
-     </para>
-     <variablelist>
-      <varlistentry>
-       <term>
-        <varname>name</varname>
-       </term>
-       <listitem>
-        <para>
-         The name of the attribute.
-        </para>
-       </listitem>
-      </varlistentry>
-      <varlistentry>
-       <term>
-        <varname>value</varname>
-       </term>
-       <listitem>
-        <para>
-         The attribute's value.
-        </para>
-       </listitem>
-      </varlistentry>
-     </variablelist>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>set</varname>