doc: convert some DocBook files to AsciiDoc

6 files changed, 82 insertions, 142 deletions

diff --git a/doc/release-notes/rl-1809.adoc b/doc/release-notes/rl-1809.adoc
new file mode 100644
index 00000000000..b363704e241
--- /dev/null
+++ b/doc/release-notes/rl-1809.adoc
@@ -0,0 +1,4 @@
+[[sec-release-18.09]]
+== Release 18.09
+
+The 18.09 release branch became the stable branch in September, 2018.
diff --git a/doc/release-notes/rl-1809.xml b/doc/release-notes/rl-1809.xml
deleted file mode 100644
index e19a4776a46..00000000000
--- a/doc/release-notes/rl-1809.xml
+++ /dev/null
@@ -1,11 +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-release-18.09">
- <title>Release 18.09</title>
-
- <para>
-  The 18.09 release branch became the stable branch in September, 2018.
- </para>
-</section>
diff --git a/doc/release-notes/rl-1903.adoc b/doc/release-notes/rl-1903.adoc
new file mode 100644
index 00000000000..6dfdc67f5bf
--- /dev/null
+++ b/doc/release-notes/rl-1903.adoc
@@ -0,0 +1,59 @@
+[[sec-release-19.03]]
+== Release 19.03
+
+The 19.03 release branch became the stable branch in April, 2019.
+
+[[sec-release-19.03-highlights]]
+=== Highlights
+:opt-home-file-source: opt-home.file._name__.source
+
+This release has the following notable changes:
+
+* The <<{opt-home-file-source}>> option now allows source files to be
+hidden, that is, having a name starting with the `.` character. It
+also allows the source file name to contain characters not typically
+allowed for Nix store paths. For example, your configuration can now
+contain things such as
++
+[source,nix]
+----
+home.file."my file".source = ./. + "/file with spaces!";
+----
+
+* The type used for the systemd unit options under
+<<opt-systemd.user.services>>, <<opt-systemd.user.sockets>>, etc. has
+been changed to offer more robust merging of configurations. If you
+don't override values within systemd units then you are not affected
+by this change. Unfortunately, if you do override unit values you may
+encounter errors.
++
+In particular, if you get an error saying that a ``unique option'' is
+``defined multiple times'' then you need to use the
+https://nixos.org/nixos/manual/#sec-option-definitions-setting-priorities[`mkForce`]
+function. For example,
++
+[source,nix]
+----
+systemd.user.services.foo.Service.ExecStart = "/foo/bar";
+----
++
+becomes
++
+[source,nix]
+----
+systemd.user.services.foo.Service.ExecStart = lib.mkForce "/foo/bar";
+----
++
+We had to make this change because the old merging was causing too
+many confusing situations for people.
+
+[[sec-release-19.03-state-version-changes]]
+=== State Version Changes
+
+The state version in this release includes the changes below. These
+changes are only active if the <<opt-home.stateVersion>> option is set
+to ``19.03'' or later.
+
+* There is now an option <<opt-programs.beets.enable>> that defaults
+to `false`. Before the module would be active if the
+<<opt-programs.beets.settings>> option was non-empty.
diff --git a/doc/release-notes/rl-1903.xml b/doc/release-notes/rl-1903.xml
deleted file mode 100644
index 2c666da7dcf..00000000000
--- a/doc/release-notes/rl-1903.xml
+++ /dev/null
@@ -1,88 +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-release-19.03">
- <title>Release 19.03</title>
-
- <para>
-  The 19.03 release branch became the stable branch in April, 2019.
- </para>
-
- <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-release-19.03-highlights">
-  <title>Highlights</title>
-
-  <para>
-   This release has the following notable changes:
-  </para>
-
-  <itemizedlist>
-   <listitem>
-    <para>
-     The <option>home.file.‹name?›.source</option> now allows source files
-     to be hidden, that is, having a name starting with the
-     <literal>.</literal> character. It also allows the source file name to
-     contain characters not typically allowed for Nix store paths. For example,
-     your configuration can now contain things such as
-<programlisting>
-home.file."my file".source = ./. + "/file with spaces!";
-</programlisting>
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     The type used for the systemd unit options under
-     <option>systemd.user.services</option>,
-     <option>systemd.user.sockets</option>, etc. has been changed to offer more
-     robust merging of configurations. If you don't override values within
-     systemd units then you are not affected by this change. Unfortunately, if
-     you do override unit values you may encounter errors.
-    </para>
-    <para>
-     In particular, if you get an error saying that a <quote>unique
-     option</quote> is <quote>defined multiple times</quote> then you need to
-     use the
-     <code xlink:href="https://nixos.org/nixos/manual/#sec-option-definitions-setting-priorities">mkForce</code>
-     function. For example,
-<programlisting language="nix">
-systemd.user.services.foo.Service.ExecStart = "/foo/bar";
-</programlisting>
-     becomes
-<programlisting language="nix">
-systemd.user.services.foo.Service.ExecStart = lib.mkForce "/foo/bar";
-</programlisting>
-     We had to make this change because the old merging was causing too many
-     confusing situations for people.
-    </para>
-   </listitem>
-  </itemizedlist>
- </section>
-
- <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-release-19.03-state-version-changes">
-  <title>State Version Changes</title>
-
-  <para>
-   The state version in this release includes the changes below. These changes
-   are only active if the <option>home.stateVersion</option> option is set to
-   "19.03" or later.
-  </para>
-
-  <itemizedlist>
-   <listitem>
-    <para>
-     There is now an option <option>programs.beets.enable</option> that
-     defaults to <literal>false</literal>. Before the module would be active if
-     the <option>programs.beets.settings</option> option was non-empty.
-    </para>
-   </listitem>
-  </itemizedlist>
- </section>
-</section>
diff --git a/doc/release-notes/rl-1909.adoc b/doc/release-notes/rl-1909.adoc
new file mode 100644
index 00000000000..a33d629767e
--- /dev/null
+++ b/doc/release-notes/rl-1909.adoc
@@ -0,0 +1,19 @@
+[[sec-release-19.09]]
+== Release 19.09 (unreleased)
+
+This is the current unstable branch and the information in this
+section is therefore not final.
+
+[[sec-release-19.09-state-version-changes]]
+=== State Version Changes
+
+The state version in this release includes the changes below. These
+changes are only active if the `home.stateVersion` option is set to
+"19.09" or later.
+
+* The <<opt-programs.firefox.package>> option now expects a wrapped
+  Firefox package and defaults to `pkgs.firefox`.
+
+* The options <<opt-home.keyboard.layout>> and
+  <<opt-home.keyboard.variant>> now default to `null`, which indicates
+  that the system value should be used.
diff --git a/doc/release-notes/rl-1909.xml b/doc/release-notes/rl-1909.xml
deleted file mode 100644
index 99a2f27c580..00000000000
--- a/doc/release-notes/rl-1909.xml
+++ /dev/null
@@ -1,43 +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-release-19.09">
- <title>Release 19.09 (unreleased)</title>
-
- <para>
-  This is the current unstable branch and the information in this section is
-  therefore not final.
- </para>
-
- <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-release-19.09-state-version-changes">
-  <title>State Version Changes</title>
-
-  <para>
-   The state version in this release includes the changes below. These changes
-   are only active if the <option>home.stateVersion</option> option is set to
-   "19.09" or later.
-  </para>
-
-  <itemizedlist>
-   <listitem>
-    <para>
-     The <option>programs.firefox.package</option> option now expects a wrapped
-     Firefox package and defaults to <code>pkgs.firefox</code>.
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     The options <option>home.keyboard.layout</option> and
-     <option>home.keyboard.variant</option> now default to
-     <literal>null</literal>, which indicates that the system value should be
-     used.
-    </para>
-   </listitem>
-  </itemizedlist>
- </section>
-</section>