nixos: nixos/doc/manual/configuration/config-file.xml to CommonMark

4 files changed, 407 insertions, 217 deletions

diff --git a/nixos/doc/manual/configuration/config-file.section.md b/nixos/doc/manual/configuration/config-file.section.md
new file mode 100644
index 00000000000..9254544177c
--- /dev/null
+++ b/nixos/doc/manual/configuration/config-file.section.md
@@ -0,0 +1,175 @@
+# NixOS Configuration File {#sec-configuration-file}
+
+The NixOS configuration file generally looks like this:
+
+```nix
+{ config, pkgs, ... }:
+
+{ option definitions
+}
+```
+
+The first line (`{ config, pkgs, ... }:`) denotes that this is actually
+a function that takes at least the two arguments `config` and `pkgs`.
+(These are explained later, in chapter [](#sec-writing-modules)) The
+function returns a *set* of option definitions (`{ ... }`).
+These definitions have the form `name = value`, where `name` is the
+name of an option and `value` is its value. For example,
+
+```nix
+{ config, pkgs, ... }:
+
+{ services.httpd.enable = true;
+  services.httpd.adminAddr = "alice@example.org";
+  services.httpd.virtualHosts.localhost.documentRoot = "/webroot";
+}
+```
+
+defines a configuration with three option definitions that together
+enable the Apache HTTP Server with `/webroot` as the document root.
+
+Sets can be nested, and in fact dots in option names are shorthand for
+defining a set containing another set. For instance,
+[`services.httpd.enable`](options.html#opt-services.httpd.enable) defines a set named
+`services` that contains a set named `httpd`, which in turn contains an
+option definition named `enable` with value `true`. This means that the
+example above can also be written as:
+
+```nix
+{ config, pkgs, ... }:
+
+{ services = {
+    httpd = {
+      enable = true;
+      adminAddr = "alice@example.org";
+      virtualHosts = {
+        localhost = {
+          documentRoot = "/webroot";
+        };
+      };
+    };
+  };
+}
+```
+
+which may be more convenient if you have lots of option definitions that
+share the same prefix (such as `services.httpd`).
+
+NixOS checks your option definitions for correctness. For instance, if
+you try to define an option that doesn't exist (that is, doesn't have a
+corresponding *option declaration*), `nixos-rebuild` will give an error
+like:
+
+```plain
+The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
+```
+
+Likewise, values in option definitions must have a correct type. For
+instance, `services.httpd.enable` must be a Boolean (`true` or `false`).
+Trying to give it a value of another type, such as a string, will cause
+an error:
+
+```plain
+The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
+```
+
+Options have various types of values. The most important are:
+
+Strings
+
+:   Strings are enclosed in double quotes, e.g.
+
+    ```nix
+    networking.hostName = "dexter";
+    ```
+
+    Special characters can be escaped by prefixing them with a backslash
+    (e.g. `\"`).
+
+    Multi-line strings can be enclosed in *double single quotes*, e.g.
+
+    ```nix
+    networking.extraHosts =
+      ''
+        127.0.0.2 other-localhost
+        10.0.0.1 server
+      '';
+    ```
+
+    The main difference is that it strips from each line a number of
+    spaces equal to the minimal indentation of the string as a whole
+    (disregarding the indentation of empty lines), and that characters
+    like `"` and `\` are not special (making it more convenient for
+    including things like shell code). See more info about this in the
+    Nix manual [here](https://nixos.org/nix/manual/#ssec-values).
+
+Booleans
+
+:   These can be `true` or `false`, e.g.
+
+    ```nix
+    networking.firewall.enable = true;
+    networking.firewall.allowPing = false;
+    ```
+
+Integers
+
+:   For example,
+
+    ```nix
+    boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60;
+    ```
+
+    (Note that here the attribute name `net.ipv4.tcp_keepalive_time` is
+    enclosed in quotes to prevent it from being interpreted as a set
+    named `net` containing a set named `ipv4`, and so on. This is
+    because it's not a NixOS option but the literal name of a Linux
+    kernel setting.)
+
+Sets
+
+:   Sets were introduced above. They are name/value pairs enclosed in
+    braces, as in the option definition
+
+    ```nix
+    fileSystems."/boot" =
+      { device = "/dev/sda1";
+        fsType = "ext4";
+        options = [ "rw" "data=ordered" "relatime" ];
+      };
+    ```
+
+Lists
+
+:   The important thing to note about lists is that list elements are
+    separated by whitespace, like this:
+
+    ```nix
+    boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
+    ```
+
+    List elements can be any other type, e.g. sets:
+
+    ```nix
+    swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
+    ```
+
+Packages
+
+:   Usually, the packages you need are already part of the Nix Packages
+    collection, which is a set that can be accessed through the function
+    argument `pkgs`. Typical uses:
+
+    ```nix
+    environment.systemPackages =
+      [ pkgs.thunderbird
+        pkgs.emacs
+      ];
+
+    services.postgresql.package = pkgs.postgresql_10;
+    ```
+
+    The latter option definition changes the default PostgreSQL package
+    used by NixOS's PostgreSQL service to 10.x. For more information on
+    packages, including how to add new ones, see
+    [](#sec-custom-packages).
diff --git a/nixos/doc/manual/configuration/config-file.xml b/nixos/doc/manual/configuration/config-file.xml
deleted file mode 100644
index 19cfb57920d..00000000000
--- a/nixos/doc/manual/configuration/config-file.xml
+++ /dev/null
@@ -1,216 +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-configuration-file">
- <title>NixOS Configuration File</title>
-
- <para>
-  The NixOS configuration file generally looks like this:
-<programlisting>
-{ config, pkgs, ... }:
-
-{ <replaceable>option definitions</replaceable>
-}
-</programlisting>
-  The first line (<literal>{ config, pkgs, ... }:</literal>) denotes that this
-  is actually a function that takes at least the two arguments
-  <varname>config</varname> and <varname>pkgs</varname>. (These are explained
-  later, in chapter <xref linkend="sec-writing-modules" />) The function returns
-  a <emphasis>set</emphasis> of option definitions (<literal>{
-  <replaceable>...</replaceable> }</literal>). These definitions have the form
-  <literal><replaceable>name</replaceable> =
-  <replaceable>value</replaceable></literal>, where
-  <replaceable>name</replaceable> is the name of an option and
-  <replaceable>value</replaceable> is its value. For example,
-<programlisting>
-{ config, pkgs, ... }:
-
-{ <xref linkend="opt-services.httpd.enable"/> = true;
-  <xref linkend="opt-services.httpd.adminAddr"/> = "alice@example.org";
-  <link linkend="opt-services.httpd.virtualHosts">services.httpd.virtualHosts.localhost.documentRoot</link> = "/webroot";
-}
-</programlisting>
-  defines a configuration with three option definitions that together enable
-  the Apache HTTP Server with <filename>/webroot</filename> as the document
-  root.
- </para>
-
- <para>
-  Sets can be nested, and in fact dots in option names are shorthand for
-  defining a set containing another set. For instance,
-  <xref linkend="opt-services.httpd.enable"/> defines a set named
-  <varname>services</varname> that contains a set named
-  <varname>httpd</varname>, which in turn contains an option definition named
-  <varname>enable</varname> with value <literal>true</literal>. This means that
-  the example above can also be written as:
-<programlisting>
-{ config, pkgs, ... }:
-
-{ services = {
-    httpd = {
-      enable = true;
-      adminAddr = "alice@example.org";
-      virtualHosts = {
-        localhost = {
-          documentRoot = "/webroot";
-        };
-      };
-    };
-  };
-}
-</programlisting>
-  which may be more convenient if you have lots of option definitions that
-  share the same prefix (such as <literal>services.httpd</literal>).
- </para>
-
- <para>
-  NixOS checks your option definitions for correctness. For instance, if you
-  try to define an option that doesn’t exist (that is, doesn’t have a
-  corresponding <emphasis>option declaration</emphasis>),
-  <command>nixos-rebuild</command> will give an error like:
-<screen>
-The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
-</screen>
-  Likewise, values in option definitions must have a correct type. For
-  instance, <option>services.httpd.enable</option> must be a Boolean
-  (<literal>true</literal> or <literal>false</literal>). Trying to give it a
-  value of another type, such as a string, will cause an error:
-<screen>
-The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
-</screen>
- </para>
-
- <para>
-  Options have various types of values. The most important are:
-  <variablelist>
-   <varlistentry>
-    <term>
-     Strings
-    </term>
-    <listitem>
-     <para>
-      Strings are enclosed in double quotes, e.g.
-<programlisting>
-<xref linkend="opt-networking.hostName"/> = "dexter";
-</programlisting>
-      Special characters can be escaped by prefixing them with a backslash
-      (e.g. <literal>\"</literal>).
-     </para>
-     <para>
-      Multi-line strings can be enclosed in <emphasis>double single
-      quotes</emphasis>, e.g.
-<programlisting>
-<xref linkend="opt-networking.extraHosts"/> =
-  ''
-    127.0.0.2 other-localhost
-    10.0.0.1 server
-  '';
-</programlisting>
-      The main difference is that it strips from each line a number of spaces
-      equal to the minimal indentation of the string as a whole (disregarding
-      the indentation of empty lines), and that characters like
-      <literal>"</literal> and <literal>\</literal> are not special (making it
-      more convenient for including things like shell code). See more info
-      about this in the Nix manual
-      <link
-      xlink:href="https://nixos.org/nix/manual/#ssec-values">here</link>.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     Booleans
-    </term>
-    <listitem>
-     <para>
-      These can be <literal>true</literal> or <literal>false</literal>, e.g.
-<programlisting>
-<xref linkend="opt-networking.firewall.enable"/> = true;
-<xref linkend="opt-networking.firewall.allowPing"/> = false;
-</programlisting>
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     Integers
-    </term>
-    <listitem>
-     <para>
-      For example,
-<programlisting>
-<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 60;
-</programlisting>
-      (Note that here the attribute name
-      <literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in quotes to
-      prevent it from being interpreted as a set named <literal>net</literal>
-      containing a set named <literal>ipv4</literal>, and so on. This is
-      because it’s not a NixOS option but the literal name of a Linux kernel
-      setting.)
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     Sets
-    </term>
-    <listitem>
-     <para>
-      Sets were introduced above. They are name/value pairs enclosed in braces,
-      as in the option definition
-<programlisting>
-<xref linkend="opt-fileSystems"/>."/boot" =
-  { device = "/dev/sda1";
-    fsType = "ext4";
-    options = [ "rw" "data=ordered" "relatime" ];
-  };
-</programlisting>
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     Lists
-    </term>
-    <listitem>
-     <para>
-      The important thing to note about lists is that list elements are
-      separated by whitespace, like this:
-<programlisting>
-<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];
-</programlisting>
-      List elements can be any other type, e.g. sets:
-<programlisting>
-swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
-</programlisting>
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     Packages
-    </term>
-    <listitem>
-     <para>
-      Usually, the packages you need are already part of the Nix Packages
-      collection, which is a set that can be accessed through the function
-      argument <varname>pkgs</varname>. Typical uses:
-<programlisting>
-<xref linkend="opt-environment.systemPackages"/> =
-  [ pkgs.thunderbird
-    pkgs.emacs
-  ];
-
-<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_10;
-</programlisting>
-      The latter option definition changes the default PostgreSQL package used
-      by NixOS’s PostgreSQL service to 10.x. For more information on
-      packages, including how to add new ones, see
-      <xref linkend="sec-custom-packages"/>.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
- </para>
-</section>
diff --git a/nixos/doc/manual/configuration/config-syntax.xml b/nixos/doc/manual/configuration/config-syntax.xml
index a374c6a8707..518d8eb627f 100644
--- a/nixos/doc/manual/configuration/config-syntax.xml
+++ b/nixos/doc/manual/configuration/config-syntax.xml
@@ -18,7 +18,7 @@ xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix
   manual</link>, but here we give a short overview of the most important
   constructs useful in NixOS configuration files.
  </para>
- <xi:include href="config-file.xml" />
+ <xi:include href="../from_md/configuration/config-file.section.xml" />
  <xi:include href="../from_md/configuration/abstractions.section.xml" />
  <xi:include href="modularity.xml" />
  <xi:include href="summary.xml" />
diff --git a/nixos/doc/manual/from_md/configuration/config-file.section.xml b/nixos/doc/manual/from_md/configuration/config-file.section.xml
new file mode 100644
index 00000000000..b7ba17b8cee
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/config-file.section.xml
@@ -0,0 +1,231 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-configuration-file">
+  <title>NixOS Configuration File</title>
+  <para>
+    The NixOS configuration file generally looks like this:
+  </para>
+  <programlisting language="bash">
+{ config, pkgs, ... }:
+
+{ option definitions
+}
+</programlisting>
+  <para>
+    The first line (<literal>{ config, pkgs, ... }:</literal>) denotes
+    that this is actually a function that takes at least the two
+    arguments <literal>config</literal> and <literal>pkgs</literal>.
+    (These are explained later, in chapter
+    <xref linkend="sec-writing-modules" />) The function returns a
+    <emphasis>set</emphasis> of option definitions
+    (<literal>{ ... }</literal>). These definitions have the form
+    <literal>name = value</literal>, where <literal>name</literal> is
+    the name of an option and <literal>value</literal> is its value. For
+    example,
+  </para>
+  <programlisting language="bash">
+{ config, pkgs, ... }:
+
+{ services.httpd.enable = true;
+  services.httpd.adminAddr = &quot;alice@example.org&quot;;
+  services.httpd.virtualHosts.localhost.documentRoot = &quot;/webroot&quot;;
+}
+</programlisting>
+  <para>
+    defines a configuration with three option definitions that together
+    enable the Apache HTTP Server with <literal>/webroot</literal> as
+    the document root.
+  </para>
+  <para>
+    Sets can be nested, and in fact dots in option names are shorthand
+    for defining a set containing another set. For instance,
+    <link xlink:href="options.html#opt-services.httpd.enable"><literal>services.httpd.enable</literal></link>
+    defines a set named <literal>services</literal> that contains a set
+    named <literal>httpd</literal>, which in turn contains an option
+    definition named <literal>enable</literal> with value
+    <literal>true</literal>. This means that the example above can also
+    be written as:
+  </para>
+  <programlisting language="bash">
+{ config, pkgs, ... }:
+
+{ services = {
+    httpd = {
+      enable = true;
+      adminAddr = &quot;alice@example.org&quot;;
+      virtualHosts = {
+        localhost = {
+          documentRoot = &quot;/webroot&quot;;
+        };
+      };
+    };
+  };
+}
+</programlisting>
+  <para>
+    which may be more convenient if you have lots of option definitions
+    that share the same prefix (such as
+    <literal>services.httpd</literal>).
+  </para>
+  <para>
+    NixOS checks your option definitions for correctness. For instance,
+    if you try to define an option that doesn’t exist (that is, doesn’t
+    have a corresponding <emphasis>option declaration</emphasis>),
+    <literal>nixos-rebuild</literal> will give an error like:
+  </para>
+  <programlisting>
+The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
+</programlisting>
+  <para>
+    Likewise, values in option definitions must have a correct type. For
+    instance, <literal>services.httpd.enable</literal> must be a Boolean
+    (<literal>true</literal> or <literal>false</literal>). Trying to
+    give it a value of another type, such as a string, will cause an
+    error:
+  </para>
+  <programlisting>
+The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
+</programlisting>
+  <para>
+    Options have various types of values. The most important are:
+  </para>
+  <variablelist>
+    <varlistentry>
+      <term>
+        Strings
+      </term>
+      <listitem>
+        <para>
+          Strings are enclosed in double quotes, e.g.
+        </para>
+        <programlisting language="bash">
+networking.hostName = &quot;dexter&quot;;
+</programlisting>
+        <para>
+          Special characters can be escaped by prefixing them with a
+          backslash (e.g. <literal>\&quot;</literal>).
+        </para>
+        <para>
+          Multi-line strings can be enclosed in <emphasis>double single
+          quotes</emphasis>, e.g.
+        </para>
+        <programlisting language="bash">
+networking.extraHosts =
+  ''
+    127.0.0.2 other-localhost
+    10.0.0.1 server
+  '';
+</programlisting>
+        <para>
+          The main difference is that it strips from each line a number
+          of spaces equal to the minimal indentation of the string as a
+          whole (disregarding the indentation of empty lines), and that
+          characters like <literal>&quot;</literal> and
+          <literal>\</literal> are not special (making it more
+          convenient for including things like shell code). See more
+          info about this in the Nix manual
+          <link xlink:href="https://nixos.org/nix/manual/#ssec-values">here</link>.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        Booleans
+      </term>
+      <listitem>
+        <para>
+          These can be <literal>true</literal> or
+          <literal>false</literal>, e.g.
+        </para>
+        <programlisting language="bash">
+networking.firewall.enable = true;
+networking.firewall.allowPing = false;
+</programlisting>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        Integers
+      </term>
+      <listitem>
+        <para>
+          For example,
+        </para>
+        <programlisting language="bash">
+boot.kernel.sysctl.&quot;net.ipv4.tcp_keepalive_time&quot; = 60;
+</programlisting>
+        <para>
+          (Note that here the attribute name
+          <literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in
+          quotes to prevent it from being interpreted as a set named
+          <literal>net</literal> containing a set named
+          <literal>ipv4</literal>, and so on. This is because it’s not a
+          NixOS option but the literal name of a Linux kernel setting.)
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        Sets
+      </term>
+      <listitem>
+        <para>
+          Sets were introduced above. They are name/value pairs enclosed
+          in braces, as in the option definition
+        </para>
+        <programlisting language="bash">
+fileSystems.&quot;/boot&quot; =
+  { device = &quot;/dev/sda1&quot;;
+    fsType = &quot;ext4&quot;;
+    options = [ &quot;rw&quot; &quot;data=ordered&quot; &quot;relatime&quot; ];
+  };
+</programlisting>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        Lists
+      </term>
+      <listitem>
+        <para>
+          The important thing to note about lists is that list elements
+          are separated by whitespace, like this:
+        </para>
+        <programlisting language="bash">
+boot.kernelModules = [ &quot;fuse&quot; &quot;kvm-intel&quot; &quot;coretemp&quot; ];
+</programlisting>
+        <para>
+          List elements can be any other type, e.g. sets:
+        </para>
+        <programlisting language="bash">
+swapDevices = [ { device = &quot;/dev/disk/by-label/swap&quot;; } ];
+</programlisting>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
+        Packages
+      </term>
+      <listitem>
+        <para>
+          Usually, the packages you need are already part of the Nix
+          Packages collection, which is a set that can be accessed
+          through the function argument <literal>pkgs</literal>. Typical
+          uses:
+        </para>
+        <programlisting language="bash">
+environment.systemPackages =
+  [ pkgs.thunderbird
+    pkgs.emacs
+  ];
+
+services.postgresql.package = pkgs.postgresql_10;
+</programlisting>
+        <para>
+          The latter option definition changes the default PostgreSQL
+          package used by NixOS’s PostgreSQL service to 10.x. For more
+          information on packages, including how to add new ones, see
+          <xref linkend="sec-custom-packages" />.
+        </para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+</section>