nixos: nixos/doc/manual/configuration/summary.xml to CommonMark

4 files changed, 379 insertions, 227 deletions

diff --git a/nixos/doc/manual/configuration/config-syntax.xml b/nixos/doc/manual/configuration/config-syntax.xml
index 430ecb4d791..d1351ff934e 100644
--- a/nixos/doc/manual/configuration/config-syntax.xml
+++ b/nixos/doc/manual/configuration/config-syntax.xml
@@ -21,4 +21,5 @@ xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix
  <xi:include href="../from_md/configuration/config-file.section.xml" />
  <xi:include href="../from_md/configuration/abstractions.section.xml" />
  <xi:include href="../from_md/configuration/modularity.section.xml" />
+ <xi:include href="../from_md/configuration/summary.section.xml" />
 </chapter>
diff --git a/nixos/doc/manual/configuration/summary.section.md b/nixos/doc/manual/configuration/summary.section.md
new file mode 100644
index 00000000000..8abbbe257fd
--- /dev/null
+++ b/nixos/doc/manual/configuration/summary.section.md
@@ -0,0 +1,46 @@
+# Syntax Summary {#sec-nix-syntax-summary}
+
+Below is a summary of the most important syntactic constructs in the Nix
+expression language. It's not complete. In particular, there are many
+other built-in functions. See the [Nix
+manual](https://nixos.org/nix/manual/#chap-writing-nix-expressions) for
+the rest.
+
+| Example                                       | Description                                                                                                        |
+|-----------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
+| *Basic values*                                |                                                                                                                    |
+| `"Hello world"`                               | A string                                                                                                           |
+| `"${pkgs.bash}/bin/sh"`                       | A string containing an expression (expands to `"/nix/store/hash-bash-version/bin/sh"`)                             |
+| `true`, `false`                               | Booleans                                                                                                           |
+| `123`                                         | An integer                                                                                                         |
+| `./foo.png`                                   | A path (relative to the containing Nix expression)                                                                 |
+| *Compound values*                             |                                                                                                                    |
+| `{ x = 1; y = 2; }`                           | A set with attributes named `x` and `y`                                                                            |
+| `{ foo.bar = 1; }`                            | A nested set, equivalent to `{ foo = { bar = 1; }; }`                                                              |
+| `rec { x = "foo"; y = x + "bar"; }`           | A recursive set, equivalent to `{ x = "foo"; y = "foobar"; }`                                                      |
+| `[ "foo" "bar" ]`                             | A list with two elements                                                                                           |
+| *Operators*                                   |                                                                                                                    |
+| `"foo" + "bar"`                               | String concatenation                                                                                               |
+| `1 + 2`                                       | Integer addition                                                                                                   |
+| `"foo" == "f" + "oo"`                         | Equality test (evaluates to `true`)                                                                                |
+| `"foo" != "bar"`                              | Inequality test (evaluates to `true`)                                                                              |
+| `!true`                                       | Boolean negation                                                                                                   |
+| `{ x = 1; y = 2; }.x`                         | Attribute selection (evaluates to `1`)                                                                             |
+| `{ x = 1; y = 2; }.z or 3`                    | Attribute selection with default (evaluates to `3`)                                                                |
+| `{ x = 1; y = 2; } // { z = 3; }`             | Merge two sets (attributes in the right-hand set taking precedence)                                                |
+| *Control structures*                          |                                                                                                                    |
+| `if 1 + 1 == 2 then "yes!" else "no!"`        | Conditional expression                                                                                             |
+| `assert 1 + 1 == 2; "yes!"`                   | Assertion check (evaluates to `"yes!"`). See [](#sec-assertions) for using assertions in modules                   |
+| `let x = "foo"; y = "bar"; in x + y`          | Variable definition                                                                                                |
+| `with pkgs.lib; head [ 1 2 3 ]`               | Add all attributes from the given set to the scope (evaluates to `1`)                                              |
+| *Functions (lambdas)*                         |                                                                                                                    |
+| `x: x + 1`                                    | A function that expects an integer and returns it increased by 1                                                   |
+| `(x: x + 1) 100`                              | A function call (evaluates to 101)                                                                                 |
+| `let inc = x: x + 1; in inc (inc (inc 100))`  | A function bound to a variable and subsequently called by name (evaluates to 103)                                  |
+| `{ x, y }: x + y`                             | A function that expects a set with required attributes `x` and `y` and concatenates them                           |
+| `{ x, y ? "bar" }: x + y`                     | A function that expects a set with required attribute `x` and optional `y`, using `"bar"` as default value for `y` |
+| `{ x, y, ... }: x + y`                        | A function that expects a set with required attributes `x` and `y` and ignores any other attributes                |
+| `{ x, y } @ args: x + y`                      | A function that expects a set with required attributes `x` and `y`, and binds the whole set to `args`              |
+| *Built-in functions*                          |                                                                                                                    |
+| `import ./foo.nix`                            | Load and return Nix expression in given file                                                                       |
+| `map (x: x + x) [ 1 2 3 ]`                    | Apply a function to every element of a list (evaluates to `[ 2 4 6 ]`)                                             |
diff --git a/nixos/doc/manual/configuration/summary.xml b/nixos/doc/manual/configuration/summary.xml
deleted file mode 100644
index 289face16de..00000000000
--- a/nixos/doc/manual/configuration/summary.xml
+++ /dev/null
@@ -1,227 +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"
-    version="5.0"
-    xml:id="sec-nix-syntax-summary">
- <title>Syntax Summary</title>
-
- <para>
-  Below is a summary of the most important syntactic constructs in the Nix
-  expression language. It’s not complete. In particular, there are many other
-  built-in functions. See the
-  <link
-xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix
-  manual</link> for the rest.
- </para>
-
- <informaltable frame='none'>
-  <tgroup cols='2'>
-   <colspec colname='c1' rowsep='1' colsep='1' />
-   <colspec colname='c2' rowsep='1' />
-   <thead>
-    <row>
-     <entry>Example</entry>
-     <entry>Description</entry>
-    </row>
-   </thead>
-   <tbody>
-    <row>
-     <entry namest="c1" nameend="c2"><emphasis>Basic values</emphasis>
-     </entry>
-    </row>
-    <row>
-     <entry><literal>"Hello world"</literal>
-     </entry>
-     <entry>A string</entry>
-    </row>
-    <row>
-     <entry><literal>"${pkgs.bash}/bin/sh"</literal>
-     </entry>
-     <entry>A string containing an expression (expands to <literal>"/nix/store/<replaceable>hash</replaceable>-bash-<replaceable>version</replaceable>/bin/sh"</literal>)</entry>
-    </row>
-    <row>
-     <entry><literal>true</literal>, <literal>false</literal>
-     </entry>
-     <entry>Booleans</entry>
-    </row>
-    <row>
-     <entry><literal>123</literal>
-     </entry>
-     <entry>An integer</entry>
-    </row>
-    <row>
-     <entry><literal>./foo.png</literal>
-     </entry>
-     <entry>A path (relative to the containing Nix expression)</entry>
-    </row>
-    <row>
-     <entry namest="c1" nameend="c2"><emphasis>Compound values</emphasis>
-     </entry>
-    </row>
-    <row>
-     <entry><literal>{ x = 1; y = 2; }</literal>
-     </entry>
-     <entry>A set with attributes named <literal>x</literal> and <literal>y</literal>
-     </entry>
-    </row>
-    <row>
-     <entry><literal>{ foo.bar = 1; }</literal>
-     </entry>
-     <entry>A nested set, equivalent to <literal>{ foo = { bar = 1; }; }</literal>
-     </entry>
-    </row>
-    <row>
-     <entry><literal>rec { x = "foo"; y = x + "bar"; }</literal>
-     </entry>
-     <entry>A recursive set, equivalent to <literal>{ x = "foo"; y = "foobar"; }</literal>
-     </entry>
-    </row>
-    <row>
-     <entry><literal>[ "foo" "bar" ]</literal>
-     </entry>
-     <entry>A list with two elements</entry>
-    </row>
-    <row>
-     <entry namest="c1" nameend="c2"><emphasis>Operators</emphasis>
-     </entry>
-    </row>
-    <row>
-     <entry><literal>"foo" + "bar"</literal>
-     </entry>
-     <entry>String concatenation</entry>
-    </row>
-    <row>
-     <entry><literal>1 + 2</literal>
-     </entry>
-     <entry>Integer addition</entry>
-    </row>
-    <row>
-     <entry><literal>"foo" == "f" + "oo"</literal>
-     </entry>
-     <entry>Equality test (evaluates to <literal>true</literal>)</entry>
-    </row>
-    <row>
-     <entry><literal>"foo" != "bar"</literal>
-     </entry>
-     <entry>Inequality test (evaluates to <literal>true</literal>)</entry>
-    </row>
-    <row>
-     <entry><literal>!true</literal>
-     </entry>
-     <entry>Boolean negation</entry>
-    </row>
-    <row>
-     <entry><literal>{ x = 1; y = 2; }.x</literal>
-     </entry>
-     <entry>Attribute selection (evaluates to <literal>1</literal>)</entry>
-    </row>
-    <row>
-     <entry><literal>{ x = 1; y = 2; }.z or 3</literal>
-     </entry>
-     <entry>Attribute selection with default (evaluates to <literal>3</literal>)</entry>
-    </row>
-    <row>
-     <entry><literal>{ x = 1; y = 2; } // { z = 3; }</literal>
-     </entry>
-     <entry>Merge two sets (attributes in the right-hand set taking precedence)</entry>
-    </row>
-    <row>
-     <entry namest="c1" nameend="c2"><emphasis>Control structures</emphasis>
-     </entry>
-    </row>
-    <row>
-     <entry><literal>if 1 + 1 == 2 then "yes!" else "no!"</literal>
-     </entry>
-     <entry>Conditional expression</entry>
-    </row>
-    <row>
-     <entry><literal>assert 1 + 1 == 2; "yes!"</literal>
-     </entry>
-     <entry>Assertion check (evaluates to <literal>"yes!"</literal>). See <xref
-    linkend="sec-assertions"/> for using assertions in modules</entry>
-    </row>
-    <row>
-     <entry><literal>let x = "foo"; y = "bar"; in x + y</literal>
-     </entry>
-     <entry>Variable definition</entry>
-    </row>
-    <row>
-     <entry><literal>with pkgs.lib; head [ 1 2 3 ]</literal>
-     </entry>
-     <entry>Add all attributes from the given set to the scope
-        (evaluates to <literal>1</literal>)</entry>
-    </row>
-    <row>
-     <entry namest="c1" nameend="c2"><emphasis>Functions (lambdas)</emphasis>
-     </entry>
-    </row>
-    <row>
-     <entry><literal>x: x + 1</literal>
-     </entry>
-     <entry>A function that expects an integer and returns it increased by 1</entry>
-    </row>
-    <row>
-     <entry><literal>(x: x + 1) 100</literal>
-     </entry>
-     <entry>A function call (evaluates to 101)</entry>
-    </row>
-    <row>
-     <entry><literal>let inc = x: x + 1; in inc (inc (inc 100))</literal>
-     </entry>
-     <entry>A function bound to a variable and subsequently called by name (evaluates to 103)</entry>
-    </row>
-    <row>
-     <entry><literal>{ x, y }: x + y</literal>
-     </entry>
-     <entry>A function that expects a set with required attributes
-        <literal>x</literal> and <literal>y</literal> and concatenates
-        them</entry>
-    </row>
-    <row>
-     <entry><literal>{ x, y ? "bar" }: x + y</literal>
-     </entry>
-     <entry>A function that expects a set with required attribute
-        <literal>x</literal> and optional <literal>y</literal>, using
-        <literal>"bar"</literal> as default value for
-        <literal>y</literal>
-     </entry>
-    </row>
-    <row>
-     <entry><literal>{ x, y, ... }: x + y</literal>
-     </entry>
-     <entry>A function that expects a set with required attributes
-        <literal>x</literal> and <literal>y</literal> and ignores any
-        other attributes</entry>
-    </row>
-    <row>
-     <entry><literal>{ x, y } @ args: x + y</literal>
-     </entry>
-     <entry>A function that expects a set with required attributes
-        <literal>x</literal> and <literal>y</literal>, and binds the
-        whole set to <literal>args</literal>
-     </entry>
-    </row>
-    <row>
-     <entry namest="c1" nameend="c2"><emphasis>Built-in functions</emphasis>
-     </entry>
-    </row>
-    <row>
-     <entry><literal>import ./foo.nix</literal>
-     </entry>
-     <entry>Load and return Nix expression in given file</entry>
-    </row>
-    <row>
-     <entry><literal>map (x: x + x) [ 1 2 3 ]</literal>
-     </entry>
-     <entry>Apply a function to every element of a list (evaluates to <literal>[ 2 4 6 ]</literal>)</entry>
-    </row>
-<!--
-      <row>
-        <entry><literal>throw "Urgh"</literal></entry>
-        <entry>Raise an error condition</entry>
-      </row>
-      -->
-   </tbody>
-  </tgroup>
- </informaltable>
-</section>
diff --git a/nixos/doc/manual/from_md/configuration/summary.section.xml b/nixos/doc/manual/from_md/configuration/summary.section.xml
new file mode 100644
index 00000000000..96a178c4930
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/summary.section.xml
@@ -0,0 +1,332 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-nix-syntax-summary">
+  <title>Syntax Summary</title>
+  <para>
+    Below is a summary of the most important syntactic constructs in the
+    Nix expression language. It’s not complete. In particular, there are
+    many other built-in functions. See the
+    <link xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix
+    manual</link> for the rest.
+  </para>
+  <informaltable>
+    <tgroup cols="2">
+      <colspec align="left" />
+      <colspec align="left" />
+      <thead>
+        <row>
+          <entry>
+            Example
+          </entry>
+          <entry>
+            Description
+          </entry>
+        </row>
+      </thead>
+      <tbody>
+        <row>
+          <entry>
+            <emphasis>Basic values</emphasis>
+          </entry>
+          <entry>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>&quot;Hello world&quot;</literal>
+          </entry>
+          <entry>
+            A string
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>&quot;${pkgs.bash}/bin/sh&quot;</literal>
+          </entry>
+          <entry>
+            A string containing an expression (expands to
+            <literal>&quot;/nix/store/hash-bash-version/bin/sh&quot;</literal>)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>true</literal>, <literal>false</literal>
+          </entry>
+          <entry>
+            Booleans
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>123</literal>
+          </entry>
+          <entry>
+            An integer
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>./foo.png</literal>
+          </entry>
+          <entry>
+            A path (relative to the containing Nix expression)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <emphasis>Compound values</emphasis>
+          </entry>
+          <entry>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x = 1; y = 2; }</literal>
+          </entry>
+          <entry>
+            A set with attributes named <literal>x</literal> and
+            <literal>y</literal>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ foo.bar = 1; }</literal>
+          </entry>
+          <entry>
+            A nested set, equivalent to
+            <literal>{ foo = { bar = 1; }; }</literal>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>rec { x = &quot;foo&quot;; y = x + &quot;bar&quot;; }</literal>
+          </entry>
+          <entry>
+            A recursive set, equivalent to
+            <literal>{ x = &quot;foo&quot;; y = &quot;foobar&quot;; }</literal>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>[ &quot;foo&quot; &quot;bar&quot; ]</literal>
+          </entry>
+          <entry>
+            A list with two elements
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <emphasis>Operators</emphasis>
+          </entry>
+          <entry>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>&quot;foo&quot; + &quot;bar&quot;</literal>
+          </entry>
+          <entry>
+            String concatenation
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>1 + 2</literal>
+          </entry>
+          <entry>
+            Integer addition
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>&quot;foo&quot; == &quot;f&quot; + &quot;oo&quot;</literal>
+          </entry>
+          <entry>
+            Equality test (evaluates to <literal>true</literal>)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>&quot;foo&quot; != &quot;bar&quot;</literal>
+          </entry>
+          <entry>
+            Inequality test (evaluates to <literal>true</literal>)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>!true</literal>
+          </entry>
+          <entry>
+            Boolean negation
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x = 1; y = 2; }.x</literal>
+          </entry>
+          <entry>
+            Attribute selection (evaluates to <literal>1</literal>)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x = 1; y = 2; }.z or 3</literal>
+          </entry>
+          <entry>
+            Attribute selection with default (evaluates to
+            <literal>3</literal>)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x = 1; y = 2; } // { z = 3; }</literal>
+          </entry>
+          <entry>
+            Merge two sets (attributes in the right-hand set taking
+            precedence)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <emphasis>Control structures</emphasis>
+          </entry>
+          <entry>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>if 1 + 1 == 2 then &quot;yes!&quot; else &quot;no!&quot;</literal>
+          </entry>
+          <entry>
+            Conditional expression
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>assert 1 + 1 == 2; &quot;yes!&quot;</literal>
+          </entry>
+          <entry>
+            Assertion check (evaluates to
+            <literal>&quot;yes!&quot;</literal>). See
+            <xref linkend="sec-assertions" /> for using assertions in
+            modules
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>let x = &quot;foo&quot;; y = &quot;bar&quot;; in x + y</literal>
+          </entry>
+          <entry>
+            Variable definition
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>with pkgs.lib; head [ 1 2 3 ]</literal>
+          </entry>
+          <entry>
+            Add all attributes from the given set to the scope
+            (evaluates to <literal>1</literal>)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <emphasis>Functions (lambdas)</emphasis>
+          </entry>
+          <entry>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>x: x + 1</literal>
+          </entry>
+          <entry>
+            A function that expects an integer and returns it increased
+            by 1
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>(x: x + 1) 100</literal>
+          </entry>
+          <entry>
+            A function call (evaluates to 101)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>let inc = x: x + 1; in inc (inc (inc 100))</literal>
+          </entry>
+          <entry>
+            A function bound to a variable and subsequently called by
+            name (evaluates to 103)
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x, y }: x + y</literal>
+          </entry>
+          <entry>
+            A function that expects a set with required attributes
+            <literal>x</literal> and <literal>y</literal> and
+            concatenates them
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x, y ? &quot;bar&quot; }: x + y</literal>
+          </entry>
+          <entry>
+            A function that expects a set with required attribute
+            <literal>x</literal> and optional <literal>y</literal>,
+            using <literal>&quot;bar&quot;</literal> as default value
+            for <literal>y</literal>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x, y, ... }: x + y</literal>
+          </entry>
+          <entry>
+            A function that expects a set with required attributes
+            <literal>x</literal> and <literal>y</literal> and ignores
+            any other attributes
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>{ x, y } @ args: x + y</literal>
+          </entry>
+          <entry>
+            A function that expects a set with required attributes
+            <literal>x</literal> and <literal>y</literal>, and binds the
+            whole set to <literal>args</literal>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <emphasis>Built-in functions</emphasis>
+          </entry>
+          <entry>
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>import ./foo.nix</literal>
+          </entry>
+          <entry>
+            Load and return Nix expression in given file
+          </entry>
+        </row>
+        <row>
+          <entry>
+            <literal>map (x: x + x) [ 1 2 3 ]</literal>
+          </entry>
+          <entry>
+            Apply a function to every element of a list (evaluates to
+            <literal>[ 2 4 6 ]</literal>)
+          </entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </informaltable>
+</section>