nixos/emacs: convert manual chapter to MD

3 files changed, 785 insertions, 440 deletions

diff --git a/nixos/modules/services/editors/emacs.md b/nixos/modules/services/editors/emacs.md
new file mode 100644
index 00000000000..c072b3664ad
--- /dev/null
+++ b/nixos/modules/services/editors/emacs.md
@@ -0,0 +1,399 @@
+# Emacs {#module-services-emacs}
+
+<!--
+    Documentation contributors:
+      Damien Cassou @DamienCassou
+      Thomas Tuegel @ttuegel
+      Rodney Lorrimar @rvl
+      Adam Hoese @adisbladis
+  -->
+
+[Emacs](https://www.gnu.org/software/emacs/) is an
+extensible, customizable, self-documenting real-time display editor — and
+more. At its core is an interpreter for Emacs Lisp, a dialect of the Lisp
+programming language with extensions to support text editing.
+
+Emacs runs within a graphical desktop environment using the X Window System,
+but works equally well on a text terminal. Under
+macOS, a "Mac port" edition is available, which
+uses Apple's native GUI frameworks.
+
+Nixpkgs provides a superior environment for
+running Emacs. It's simple to create custom builds
+by overriding the default packages. Chaotic collections of Emacs Lisp code
+and extensions can be brought under control using declarative package
+management. NixOS even provides a
+{command}`systemd` user service for automatically starting the Emacs
+daemon.
+
+## Installing Emacs {#module-services-emacs-installing}
+
+Emacs can be installed in the normal way for Nix (see
+[](#sec-package-management)). In addition, a NixOS
+*service* can be enabled.
+
+### The Different Releases of Emacs {#module-services-emacs-releases}
+
+Nixpkgs defines several basic Emacs packages.
+The following are attributes belonging to the {var}`pkgs` set:
+
+  {var}`emacs`
+  : The latest stable version of Emacs using the [GTK 2](http://www.gtk.org)
+    widget toolkit.
+
+  {var}`emacs-nox`
+  : Emacs built without any dependency on X11 libraries.
+
+  {var}`emacsMacport`
+  : Emacs with the "Mac port" patches, providing a more native look and
+    feel under macOS.
+
+If those aren't suitable, then the following imitation Emacs editors are
+also available in Nixpkgs:
+[Zile](https://www.gnu.org/software/zile/),
+[mg](http://homepage.boetes.org/software/mg/),
+[Yi](http://yi-editor.github.io/),
+[jmacs](https://joe-editor.sourceforge.io/).
+
+### Adding Packages to Emacs {#module-services-emacs-adding-packages}
+
+Emacs includes an entire ecosystem of functionality beyond text editing,
+including a project planner, mail and news reader, debugger interface,
+calendar, and more.
+
+Most extensions are gotten with the Emacs packaging system
+({file}`package.el`) from
+[Emacs Lisp Package Archive (ELPA)](https://elpa.gnu.org/),
+[MELPA](https://melpa.org/),
+[MELPA Stable](https://stable.melpa.org/), and
+[Org ELPA](http://orgmode.org/elpa.html). Nixpkgs is
+regularly updated to mirror all these archives.
+
+Under NixOS, you can continue to use
+`package-list-packages` and
+`package-install` to install packages. You can also
+declare the set of Emacs packages you need using the derivations from
+Nixpkgs. The rest of this section discusses declarative installation of
+Emacs packages through nixpkgs.
+
+The first step to declare the list of packages you want in your Emacs
+installation is to create a dedicated derivation. This can be done in a
+dedicated {file}`emacs.nix` file such as:
+
+[]{#ex-emacsNix}
+
+```nix
+/*
+This is a nix expression to build Emacs and some Emacs packages I like
+from source on any distribution where Nix is installed. This will install
+all the dependencies from the nixpkgs repository and build the binary files
+without interfering with the host distribution.
+
+To build the project, type the following from the current directory:
+
+$ nix-build emacs.nix
+
+To run the newly compiled executable:
+
+$ ./result/bin/emacs
+*/
+
+# The first non-comment line in this file indicates that
+# the whole file represents a function.
+{ pkgs ? import <nixpkgs> {} }:
+
+let
+  # The let expression below defines a myEmacs binding pointing to the
+  # current stable version of Emacs. This binding is here to separate
+  # the choice of the Emacs binary from the specification of the
+  # required packages.
+  myEmacs = pkgs.emacs;
+  # This generates an emacsWithPackages function. It takes a single
+  # argument: a function from a package set to a list of packages
+  # (the packages that will be available in Emacs).
+  emacsWithPackages = (pkgs.emacsPackagesFor myEmacs).emacsWithPackages;
+in
+  # The rest of the file specifies the list of packages to install. In the
+  # example, two packages (magit and zerodark-theme) are taken from
+  # MELPA stable.
+  emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
+    magit          # ; Integrate git <C-x g>
+    zerodark-theme # ; Nicolas' theme
+  ])
+  # Two packages (undo-tree and zoom-frm) are taken from MELPA.
+  ++ (with epkgs.melpaPackages; [
+    undo-tree      # ; <C-x u> to show the undo tree
+    zoom-frm       # ; increase/decrease font size for all buffers %lt;C-x C-+>
+  ])
+  # Three packages are taken from GNU ELPA.
+  ++ (with epkgs.elpaPackages; [
+    auctex         # ; LaTeX mode
+    beacon         # ; highlight my cursor when scrolling
+    nameless       # ; hide current package name everywhere in elisp code
+  ])
+  # notmuch is taken from a nixpkgs derivation which contains an Emacs mode.
+  ++ [
+    pkgs.notmuch   # From main packages set
+  ])
+```
+
+The result of this configuration will be an {command}`emacs`
+command which launches Emacs with all of your chosen packages in the
+{var}`load-path`.
+
+You can check that it works by executing this in a terminal:
+```ShellSession
+$ nix-build emacs.nix
+$ ./result/bin/emacs -q
+```
+and then typing `M-x package-initialize`. Check that you
+can use all the packages you want in this Emacs instance. For example, try
+switching to the zerodark theme through `M-x load-theme <RET> zerodark <RET> y`.
+
+::: {.tip}
+A few popular extensions worth checking out are: auctex, company,
+edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile,
+and yasnippet.
+:::
+
+The list of available packages in the various ELPA repositories can be seen
+with the following commands:
+[]{#module-services-emacs-querying-packages}
+```
+nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.elpaPackages
+nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaPackages
+nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaStablePackages
+nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.orgPackages
+```
+
+If you are on NixOS, you can install this particular Emacs for all users by
+adding it to the list of system packages (see
+[](#sec-declarative-package-mgmt)). Simply modify your file
+{file}`configuration.nix` to make it contain:
+[]{#module-services-emacs-configuration-nix}
+```
+{
+ environment.systemPackages = [
+   # [...]
+   (import /path/to/emacs.nix { inherit pkgs; })
+  ];
+}
+```
+
+In this case, the next {command}`nixos-rebuild switch` will take
+care of adding your {command}`emacs` to the {var}`PATH`
+environment variable (see [](#sec-changing-config)).
+
+<!-- fixme: i think the following is better done with config.nix
+https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides
+-->
+
+If you are not on NixOS or want to install this particular Emacs only for
+yourself, you can do so by adding it to your
+{file}`~/.config/nixpkgs/config.nix` (see
+[Nixpkgs manual](https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides)):
+[]{#module-services-emacs-config-nix}
+```
+{
+  packageOverrides = super: let self = super.pkgs; in {
+    myemacs = import /path/to/emacs.nix { pkgs = self; };
+  };
+}
+```
+
+In this case, the next `nix-env -f '<nixpkgs>' -iA
+myemacs` will take care of adding your emacs to the
+{var}`PATH` environment variable.
+
+### Advanced Emacs Configuration {#module-services-emacs-advanced}
+
+If you want, you can tweak the Emacs package itself from your
+{file}`emacs.nix`. For example, if you want to have a
+GTK 3-based Emacs instead of the default GTK 2-based binary and remove the
+automatically generated {file}`emacs.desktop` (useful if you
+only use {command}`emacsclient`), you can change your file
+{file}`emacs.nix` in this way:
+
+[]{#ex-emacsGtk3Nix}
+```
+{ pkgs ? import <nixpkgs> {} }:
+let
+  myEmacs = (pkgs.emacs.override {
+    # Use gtk3 instead of the default gtk2
+    withGTK3 = true;
+    withGTK2 = false;
+  }).overrideAttrs (attrs: {
+    # I don't want emacs.desktop file because I only use
+    # emacsclient.
+    postInstall = (attrs.postInstall or "") + ''
+      rm $out/share/applications/emacs.desktop
+    '';
+  });
+in [...]
+```
+
+After building this file as shown in [the example above](#ex-emacsNix), you
+will get an GTK 3-based Emacs binary pre-loaded with your favorite packages.
+
+## Running Emacs as a Service {#module-services-emacs-running}
+
+NixOS provides an optional
+{command}`systemd` service which launches
+[Emacs daemon](https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html)
+with the user's login session.
+
+*Source:* {file}`modules/services/editors/emacs.nix`
+
+### Enabling the Service {#module-services-emacs-enabling}
+
+To install and enable the {command}`systemd` user service for Emacs
+daemon, add the following to your {file}`configuration.nix`:
+```
+services.emacs.enable = true;
+services.emacs.package = import /home/cassou/.emacs.d { pkgs = pkgs; };
+```
+
+The {var}`services.emacs.package` option allows a custom
+derivation to be used, for example, one created by
+`emacsWithPackages`.
+
+Ensure that the Emacs server is enabled for your user's Emacs
+configuration, either by customizing the {var}`server-mode`
+variable, or by adding `(server-start)` to
+{file}`~/.emacs.d/init.el`.
+
+To start the daemon, execute the following:
+```ShellSession
+$ nixos-rebuild switch  # to activate the new configuration.nix
+$ systemctl --user daemon-reload        # to force systemd reload
+$ systemctl --user start emacs.service  # to start the Emacs daemon
+```
+The server should now be ready to serve Emacs clients.
+
+### Starting the client {#module-services-emacs-starting-client}
+
+Ensure that the emacs server is enabled, either by customizing the
+{var}`server-mode` variable, or by adding
+`(server-start)` to {file}`~/.emacs`.
+
+To connect to the emacs daemon, run one of the following:
+```
+emacsclient FILENAME
+emacsclient --create-frame  # opens a new frame (window)
+emacsclient --create-frame --tty  # opens a new frame on the current terminal
+```
+
+### Configuring the {var}`EDITOR` variable {#module-services-emacs-editor-variable}
+
+<!--<title>{command}`emacsclient` as the Default Editor</title>-->
+
+If [](#opt-services.emacs.defaultEditor) is
+`true`, the {var}`EDITOR` variable will be set
+to a wrapper script which launches {command}`emacsclient`.
+
+Any setting of {var}`EDITOR` in the shell config files will
+override {var}`services.emacs.defaultEditor`. To make sure
+{var}`EDITOR` refers to the Emacs wrapper script, remove any
+existing {var}`EDITOR` assignment from
+{file}`.profile`, {file}`.bashrc`,
+{file}`.zshenv` or any other shell config file.
+
+If you have formed certain bad habits when editing files, these can be
+corrected with a shell alias to the wrapper script:
+```
+alias vi=$EDITOR
+```
+
+### Per-User Enabling of the Service {#module-services-emacs-per-user}
+
+In general, {command}`systemd` user services are globally enabled
+by symlinks in {file}`/etc/systemd/user`. In the case where
+Emacs daemon is not wanted for all users, it is possible to install the
+service but not globally enable it:
+```
+services.emacs.enable = false;
+services.emacs.install = true;
+```
+
+To enable the {command}`systemd` user service for just the
+currently logged in user, run:
+```
+systemctl --user enable emacs
+```
+This will add the symlink
+{file}`~/.config/systemd/user/emacs.service`.
+
+## Configuring Emacs {#module-services-emacs-configuring}
+
+The Emacs init file should be changed to load the extension packages at
+startup:
+[]{#module-services-emacs-package-initialisation}
+```
+(require 'package)
+
+;; optional. makes unpure packages archives unavailable
+(setq package-archives nil)
+
+(setq package-enable-at-startup nil)
+(package-initialize)
+```
+
+After the declarative emacs package configuration has been tested,
+previously downloaded packages can be cleaned up by removing
+{file}`~/.emacs.d/elpa` (do make a backup first, in case you
+forgot a package).
+
+<!--
+      todo: is it worth documenting customizations for
+      server-switch-hook, server-done-hook?
+  -->
+
+### A Major Mode for Nix Expressions {#module-services-emacs-major-mode}
+
+Of interest may be {var}`melpaPackages.nix-mode`, which
+provides syntax highlighting for the Nix language. This is particularly
+convenient if you regularly edit Nix files.
+
+### Accessing man pages {#module-services-emacs-man-pages}
+
+You can use `woman` to get completion of all available
+man pages. For example, type `M-x woman <RET> nixos-rebuild <RET>.`
+
+### Editing DocBook 5 XML Documents {#sec-emacs-docbook-xml}
+
+Emacs includes
+[nXML](https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html),
+a major-mode for validating and editing XML documents. When editing DocBook
+5.0 documents, such as [this one](#book-nixos-manual),
+nXML needs to be configured with the relevant schema, which is not
+included.
+
+To install the DocBook 5.0 schemas, either add
+{var}`pkgs.docbook5` to [](#opt-environment.systemPackages)
+([NixOS](#sec-declarative-package-mgmt)), or run
+`nix-env -f '<nixpkgs>' -iA docbook5`
+([Nix](#sec-ad-hoc-packages)).
+
+Then customize the variable {var}`rng-schema-locating-files` to
+include {file}`~/.emacs.d/schemas.xml` and put the following
+text into that file:
+[]{#ex-emacs-docbook-xml}
+```xml
+<?xml version="1.0"?>
+<!--
+  To let emacs find this file, evaluate:
+  (add-to-list 'rng-schema-locating-files "~/.emacs.d/schemas.xml")
+-->
+<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
+  <!--
+    Use this variation if pkgs.docbook5 is added to environment.systemPackages
+  -->
+  <namespace ns="http://docbook.org/ns/docbook"
+             uri="/run/current-system/sw/share/xml/docbook-5.0/rng/docbookxi.rnc"/>
+  <!--
+    Use this variation if installing schema with "nix-env -iA pkgs.docbook5".
+  <namespace ns="http://docbook.org/ns/docbook"
+             uri="../.nix-profile/share/xml/docbook-5.0/rng/docbookxi.rnc"/>
+  -->
+</locatingRules>
+```
diff --git a/nixos/modules/services/editors/emacs.nix b/nixos/modules/services/editors/emacs.nix
index 5ae28cd9bbb..b4f447757e7 100644
--- a/nixos/modules/services/editors/emacs.nix
+++ b/nixos/modules/services/editors/emacs.nix
@@ -99,5 +99,7 @@ in
     environment.variables.EDITOR = mkIf cfg.defaultEditor (mkOverride 900 "${editorScript}/bin/emacseditor");
   };
 
+  # Don't edit the docbook xml directly, edit the md and generate it:
+  # `pandoc emacs.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > emacs.xml`
   meta.doc = ./emacs.xml;
 }
diff --git a/nixos/modules/services/editors/emacs.xml b/nixos/modules/services/editors/emacs.xml
index 7b847f1f798..5e4f3e67427 100644
--- a/nixos/modules/services/editors/emacs.xml
+++ b/nixos/modules/services/editors/emacs.xml
@@ -1,143 +1,119 @@
-<chapter 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="module-services-emacs">
- <title>Emacs</title>
-<!--
-    Documentation contributors:
-      Damien Cassou @DamienCassou
-      Thomas Tuegel @ttuegel
-      Rodney Lorrimar @rvl
-      Adam Hoese @adisbladis
-  -->
- <para>
-  <link xlink:href="https://www.gnu.org/software/emacs/">Emacs</link> is an
-  extensible, customizable, self-documenting real-time display editor — and
-  more. At its core is an interpreter for Emacs Lisp, a dialect of the Lisp
-  programming language with extensions to support text editing.
- </para>
- <para>
-  Emacs runs within a graphical desktop environment using the X Window System,
-  but works equally well on a text terminal. Under
-  macOS, a "Mac port" edition is available, which
-  uses Apple's native GUI frameworks.
- </para>
- <para>
-  Nixpkgs provides a superior environment for
-  running Emacs. It's simple to create custom builds
-  by overriding the default packages. Chaotic collections of Emacs Lisp code
-  and extensions can be brought under control using declarative package
-  management. NixOS even provides a
-  <command>systemd</command> user service for automatically starting the Emacs
-  daemon.
- </para>
- <section xml:id="module-services-emacs-installing">
-  <title>Installing Emacs</title>
-
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-emacs">
+  <title>Emacs</title>
   <para>
-   Emacs can be installed in the normal way for Nix (see
-   <xref linkend="sec-package-management" />). In addition, a NixOS
-   <emphasis>service</emphasis> can be enabled.
+    <link xlink:href="https://www.gnu.org/software/emacs/">Emacs</link>
+    is an extensible, customizable, self-documenting real-time display
+    editor — and more. At its core is an interpreter for Emacs Lisp, a
+    dialect of the Lisp programming language with extensions to support
+    text editing.
   </para>
-
-  <section xml:id="module-services-emacs-releases">
-   <title>The Different Releases of Emacs</title>
-
-   <para>
-    Nixpkgs defines several basic Emacs packages.
-    The following are attributes belonging to the <varname>pkgs</varname> set:
-    <variablelist>
-     <varlistentry>
-      <term>
-       <varname>emacs</varname>
-      </term>
-      <term>
-       <varname>emacs</varname>
-      </term>
-      <listitem>
-       <para>
-        The latest stable version of Emacs using the
-        <link
-                xlink:href="http://www.gtk.org">GTK 2</link>
-        widget toolkit.
-       </para>
-      </listitem>
-     </varlistentry>
-     <varlistentry>
-      <term>
-       <varname>emacs-nox</varname>
-      </term>
-      <listitem>
-       <para>
-        Emacs built without any dependency on X11 libraries.
-       </para>
-      </listitem>
-     </varlistentry>
-     <varlistentry>
-      <term>
-       <varname>emacsMacport</varname>
-      </term>
-      <term>
-       <varname>emacsMacport</varname>
-      </term>
-      <listitem>
-       <para>
-        Emacs with the "Mac port" patches, providing a more native look and
-        feel under macOS.
-       </para>
-      </listitem>
-     </varlistentry>
-    </variablelist>
-   </para>
-
-   <para>
-    If those aren't suitable, then the following imitation Emacs editors are
-    also available in Nixpkgs:
-    <link xlink:href="https://www.gnu.org/software/zile/">Zile</link>,
-    <link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>,
-    <link xlink:href="http://yi-editor.github.io/">Yi</link>,
-    <link xlink:href="https://joe-editor.sourceforge.io/">jmacs</link>.
-   </para>
-  </section>
-
-  <section xml:id="module-services-emacs-adding-packages">
-   <title>Adding Packages to Emacs</title>
-
-   <para>
-    Emacs includes an entire ecosystem of functionality beyond text editing,
-    including a project planner, mail and news reader, debugger interface,
-    calendar, and more.
-   </para>
-
-   <para>
-    Most extensions are gotten with the Emacs packaging system
-    (<filename>package.el</filename>) from
-    <link
-        xlink:href="https://elpa.gnu.org/">Emacs Lisp Package Archive
-    (ELPA)</link>,
-    <link xlink:href="https://melpa.org/">MELPA</link>,
-    <link xlink:href="https://stable.melpa.org/">MELPA Stable</link>, and
-    <link xlink:href="http://orgmode.org/elpa.html">Org ELPA</link>. Nixpkgs is
-    regularly updated to mirror all these archives.
-   </para>
-
-   <para>
-    Under NixOS, you can continue to use
-    <literal>package-list-packages</literal> and
-    <literal>package-install</literal> to install packages. You can also
-    declare the set of Emacs packages you need using the derivations from
-    Nixpkgs. The rest of this section discusses declarative installation of
-    Emacs packages through nixpkgs.
-   </para>
-
-   <para>
-    The first step to declare the list of packages you want in your Emacs
-    installation is to create a dedicated derivation. This can be done in a
-    dedicated <filename>emacs.nix</filename> file such as:
-    <example xml:id="ex-emacsNix">
-     <title>Nix expression to build Emacs with packages (<filename>emacs.nix</filename>)</title>
-<programlisting language="nix">
+  <para>
+    Emacs runs within a graphical desktop environment using the X Window
+    System, but works equally well on a text terminal. Under macOS, a
+    &quot;Mac port&quot; edition is available, which uses Apple's native
+    GUI frameworks.
+  </para>
+  <para>
+    Nixpkgs provides a superior environment for running Emacs. It's
+    simple to create custom builds by overriding the default packages.
+    Chaotic collections of Emacs Lisp code and extensions can be brought
+    under control using declarative package management. NixOS even
+    provides a <command>systemd</command> user service for automatically
+    starting the Emacs daemon.
+  </para>
+  <section xml:id="module-services-emacs-installing">
+    <title>Installing Emacs</title>
+    <para>
+      Emacs can be installed in the normal way for Nix (see
+      <xref linkend="sec-package-management"></xref>). In addition, a
+      NixOS <emphasis>service</emphasis> can be enabled.
+    </para>
+    <section xml:id="module-services-emacs-releases">
+      <title>The Different Releases of Emacs</title>
+      <para>
+        Nixpkgs defines several basic Emacs packages. The following are
+        attributes belonging to the <varname>pkgs</varname> set:
+      </para>
+      <variablelist spacing="compact">
+        <varlistentry>
+          <term>
+            <varname>emacs</varname>
+          </term>
+          <listitem>
+            <para>
+              The latest stable version of Emacs using the
+              <link xlink:href="http://www.gtk.org">GTK 2</link> widget
+              toolkit.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>
+            <varname>emacs-nox</varname>
+          </term>
+          <listitem>
+            <para>
+              Emacs built without any dependency on X11 libraries.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>
+            <varname>emacsMacport</varname>
+          </term>
+          <listitem>
+            <para>
+              Emacs with the &quot;Mac port&quot; patches, providing a
+              more native look and feel under macOS.
+            </para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+      <para>
+        If those aren't suitable, then the following imitation Emacs
+        editors are also available in Nixpkgs:
+        <link xlink:href="https://www.gnu.org/software/zile/">Zile</link>,
+        <link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>,
+        <link xlink:href="http://yi-editor.github.io/">Yi</link>,
+        <link xlink:href="https://joe-editor.sourceforge.io/">jmacs</link>.
+      </para>
+    </section>
+    <section xml:id="module-services-emacs-adding-packages">
+      <title>Adding Packages to Emacs</title>
+      <para>
+        Emacs includes an entire ecosystem of functionality beyond text
+        editing, including a project planner, mail and news reader,
+        debugger interface, calendar, and more.
+      </para>
+      <para>
+        Most extensions are gotten with the Emacs packaging system
+        (<filename>package.el</filename>) from
+        <link xlink:href="https://elpa.gnu.org/">Emacs Lisp Package
+        Archive (ELPA)</link>,
+        <link xlink:href="https://melpa.org/">MELPA</link>,
+        <link xlink:href="https://stable.melpa.org/">MELPA
+        Stable</link>, and
+        <link xlink:href="http://orgmode.org/elpa.html">Org ELPA</link>.
+        Nixpkgs is regularly updated to mirror all these archives.
+      </para>
+      <para>
+        Under NixOS, you can continue to use
+        <literal>package-list-packages</literal> and
+        <literal>package-install</literal> to install packages. You can
+        also declare the set of Emacs packages you need using the
+        derivations from Nixpkgs. The rest of this section discusses
+        declarative installation of Emacs packages through nixpkgs.
+      </para>
+      <para>
+        The first step to declare the list of packages you want in your
+        Emacs installation is to create a dedicated derivation. This can
+        be done in a dedicated <filename>emacs.nix</filename> file such
+        as:
+      </para>
+      <para>
+        <anchor xml:id="ex-emacsNix" />
+      </para>
+      <programlisting language="nix">
 /*
 This is a nix expression to build Emacs and some Emacs packages I like
 from source on any distribution where Nix is installed. This will install
@@ -191,111 +167,103 @@ in
     pkgs.notmuch   # From main packages set
   ])
 </programlisting>
-    </example>
-   </para>
-
-   <para>
-    The result of this configuration will be an <command>emacs</command>
-    command which launches Emacs with all of your chosen packages in the
-    <varname>load-path</varname>.
-   </para>
-
-   <para>
-    You can check that it works by executing this in a terminal:
-<screen>
-<prompt>$ </prompt>nix-build emacs.nix
-<prompt>$ </prompt>./result/bin/emacs -q
-</screen>
-    and then typing <literal>M-x package-initialize</literal>. Check that you
-    can use all the packages you want in this Emacs instance. For example, try
-    switching to the zerodark theme through <literal>M-x load-theme &lt;RET&gt;
-    zerodark &lt;RET&gt; y</literal>.
-   </para>
-
-   <tip>
-    <para>
-     A few popular extensions worth checking out are: auctex, company,
-     edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile,
-     and yasnippet.
-    </para>
-   </tip>
-
-   <para>
-    The list of available packages in the various ELPA repositories can be seen
-    with the following commands:
-    <anchor xml:id="module-services-emacs-querying-packages" />
-<programlisting><![CDATA[
-nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.elpaPackages
-nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaPackages
-nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaStablePackages
-nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.orgPackages
-]]></programlisting>
-   </para>
-
-   <para>
-    If you are on NixOS, you can install this particular Emacs for all users by
-    adding it to the list of system packages (see
-    <xref linkend="sec-declarative-package-mgmt" />). Simply modify your file
-    <filename>configuration.nix</filename> to make it contain:
-    <anchor xml:id="module-services-emacs-configuration-nix" />
-<programlisting><![CDATA[
+      <para>
+        The result of this configuration will be an
+        <command>emacs</command> command which launches Emacs with all
+        of your chosen packages in the <varname>load-path</varname>.
+      </para>
+      <para>
+        You can check that it works by executing this in a terminal:
+      </para>
+      <programlisting>
+$ nix-build emacs.nix
+$ ./result/bin/emacs -q
+</programlisting>
+      <para>
+        and then typing <literal>M-x package-initialize</literal>. Check
+        that you can use all the packages you want in this Emacs
+        instance. For example, try switching to the zerodark theme
+        through
+        <literal>M-x load-theme &lt;RET&gt; zerodark &lt;RET&gt; y</literal>.
+      </para>
+      <tip>
+        <para>
+          A few popular extensions worth checking out are: auctex,
+          company, edit-server, flycheck, helm, iedit, magit,
+          multiple-cursors, projectile, and yasnippet.
+        </para>
+      </tip>
+      <para>
+        The list of available packages in the various ELPA repositories
+        can be seen with the following commands:
+        <anchor xml:id="module-services-emacs-querying-packages" />
+      </para>
+      <programlisting>
+nix-env -f &quot;&lt;nixpkgs&gt;&quot; -qaP -A emacs.pkgs.elpaPackages
+nix-env -f &quot;&lt;nixpkgs&gt;&quot; -qaP -A emacs.pkgs.melpaPackages
+nix-env -f &quot;&lt;nixpkgs&gt;&quot; -qaP -A emacs.pkgs.melpaStablePackages
+nix-env -f &quot;&lt;nixpkgs&gt;&quot; -qaP -A emacs.pkgs.orgPackages
+</programlisting>
+      <para>
+        If you are on NixOS, you can install this particular Emacs for
+        all users by adding it to the list of system packages (see
+        <xref linkend="sec-declarative-package-mgmt"></xref>). Simply
+        modify your file <filename>configuration.nix</filename> to make
+        it contain:
+        <anchor xml:id="module-services-emacs-configuration-nix" />
+      </para>
+      <programlisting>
 {
  environment.systemPackages = [
    # [...]
    (import /path/to/emacs.nix { inherit pkgs; })
   ];
 }
-]]></programlisting>
-   </para>
-
-   <para>
-    In this case, the next <command>nixos-rebuild switch</command> will take
-    care of adding your <command>emacs</command> to the <varname>PATH</varname>
-    environment variable (see <xref linkend="sec-changing-config" />).
-   </para>
-
-<!-- fixme: i think the following is better done with config.nix
-https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides
--->
-
-   <para>
-    If you are not on NixOS or want to install this particular Emacs only for
-    yourself, you can do so by adding it to your
-    <filename>~/.config/nixpkgs/config.nix</filename> (see
-    <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs
-    manual</link>):
-    <anchor xml:id="module-services-emacs-config-nix" />
-<programlisting><![CDATA[
+</programlisting>
+      <para>
+        In this case, the next <command>nixos-rebuild switch</command>
+        will take care of adding your <command>emacs</command> to the
+        <varname>PATH</varname> environment variable (see
+        <xref linkend="sec-changing-config"></xref>).
+      </para>
+      <para>
+        If you are not on NixOS or want to install this particular Emacs
+        only for yourself, you can do so by adding it to your
+        <filename>~/.config/nixpkgs/config.nix</filename> (see
+        <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs
+        manual</link>):
+        <anchor xml:id="module-services-emacs-config-nix" />
+      </para>
+      <programlisting>
 {
   packageOverrides = super: let self = super.pkgs; in {
     myemacs = import /path/to/emacs.nix { pkgs = self; };
   };
 }
-]]></programlisting>
-   </para>
-
-   <para>
-    In this case, the next <literal>nix-env -f '&lt;nixpkgs&gt;' -iA
-    myemacs</literal> will take care of adding your emacs to the
-    <varname>PATH</varname> environment variable.
-   </para>
-  </section>
-
-  <section xml:id="module-services-emacs-advanced">
-   <title>Advanced Emacs Configuration</title>
-
-   <para>
-    If you want, you can tweak the Emacs package itself from your
-    <filename>emacs.nix</filename>. For example, if you want to have a
-    GTK 3-based Emacs instead of the default GTK 2-based binary and remove the
-    automatically generated <filename>emacs.desktop</filename> (useful if you
-    only use <command>emacsclient</command>), you can change your file
-    <filename>emacs.nix</filename> in this way:
-   </para>
-
-   <anchor xml:id="ex-emacsGtk3Nix" />
-<programlisting><![CDATA[
-{ pkgs ? import <nixpkgs> {} }:
+</programlisting>
+      <para>
+        In this case, the next
+        <literal>nix-env -f '&lt;nixpkgs&gt;' -iA myemacs</literal> will
+        take care of adding your emacs to the <varname>PATH</varname>
+        environment variable.
+      </para>
+    </section>
+    <section xml:id="module-services-emacs-advanced">
+      <title>Advanced Emacs Configuration</title>
+      <para>
+        If you want, you can tweak the Emacs package itself from your
+        <filename>emacs.nix</filename>. For example, if you want to have
+        a GTK 3-based Emacs instead of the default GTK 2-based binary
+        and remove the automatically generated
+        <filename>emacs.desktop</filename> (useful if you only use
+        <command>emacsclient</command>), you can change your file
+        <filename>emacs.nix</filename> in this way:
+      </para>
+      <para>
+        <anchor xml:id="ex-emacsGtk3Nix" />
+      </para>
+      <programlisting>
+{ pkgs ? import &lt;nixpkgs&gt; {} }:
 let
   myEmacs = (pkgs.emacs.override {
     # Use gtk3 instead of the default gtk2
@@ -304,151 +272,143 @@ let
   }).overrideAttrs (attrs: {
     # I don't want emacs.desktop file because I only use
     # emacsclient.
-    postInstall = (attrs.postInstall or "") + ''
+    postInstall = (attrs.postInstall or &quot;&quot;) + ''
       rm $out/share/applications/emacs.desktop
     '';
   });
 in [...]
-]]></programlisting>
-
-   <para>
-    After building this file as shown in <xref linkend="ex-emacsNix" />, you
-    will get an GTK 3-based Emacs binary pre-loaded with your favorite packages.
-   </para>
+</programlisting>
+      <para>
+        After building this file as shown in
+        <link linkend="ex-emacsNix">the example above</link>, you will
+        get an GTK 3-based Emacs binary pre-loaded with your favorite
+        packages.
+      </para>
+    </section>
   </section>
- </section>
- <section xml:id="module-services-emacs-running">
-  <title>Running Emacs as a Service</title>
-
-  <para>
-   NixOS provides an optional
-   <command>systemd</command> service which launches
-   <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html">
-   Emacs daemon </link> with the user's login session.
-  </para>
-
-  <para>
-   <emphasis>Source:</emphasis>
-   <filename>modules/services/editors/emacs.nix</filename>
-  </para>
-
-  <section xml:id="module-services-emacs-enabling">
-   <title>Enabling the Service</title>
-
-   <para>
-    To install and enable the <command>systemd</command> user service for Emacs
-    daemon, add the following to your <filename>configuration.nix</filename>:
-<programlisting>
+  <section xml:id="module-services-emacs-running">
+    <title>Running Emacs as a Service</title>
+    <para>
+      NixOS provides an optional <command>systemd</command> service
+      which launches
+      <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html">Emacs
+      daemon</link> with the user's login session.
+    </para>
+    <para>
+      <emphasis>Source:</emphasis>
+      <filename>modules/services/editors/emacs.nix</filename>
+    </para>
+    <section xml:id="module-services-emacs-enabling">
+      <title>Enabling the Service</title>
+      <para>
+        To install and enable the <command>systemd</command> user
+        service for Emacs daemon, add the following to your
+        <filename>configuration.nix</filename>:
+      </para>
+      <programlisting>
 services.emacs.enable = true;
 services.emacs.package = import /home/cassou/.emacs.d { pkgs = pkgs; };
 </programlisting>
-   </para>
-
-   <para>
-    The <varname>services.emacs.package</varname> option allows a custom
-    derivation to be used, for example, one created by
-    <literal>emacsWithPackages</literal>.
-   </para>
-
-   <para>
-    Ensure that the Emacs server is enabled for your user's Emacs
-    configuration, either by customizing the <varname>server-mode</varname>
-    variable, or by adding <literal>(server-start)</literal> to
-    <filename>~/.emacs.d/init.el</filename>.
-   </para>
-
-   <para>
-    To start the daemon, execute the following:
-<screen>
-<prompt>$ </prompt>nixos-rebuild switch  # to activate the new configuration.nix
-<prompt>$ </prompt>systemctl --user daemon-reload        # to force systemd reload
-<prompt>$ </prompt>systemctl --user start emacs.service  # to start the Emacs daemon
-</screen>
-    The server should now be ready to serve Emacs clients.
-   </para>
-  </section>
-
-  <section xml:id="module-services-emacs-starting-client">
-   <title>Starting the client</title>
-
-   <para>
-    Ensure that the emacs server is enabled, either by customizing the
-    <varname>server-mode</varname> variable, or by adding
-    <literal>(server-start)</literal> to <filename>~/.emacs</filename>.
-   </para>
-
-   <para>
-    To connect to the emacs daemon, run one of the following:
-<programlisting><![CDATA[
+      <para>
+        The <varname>services.emacs.package</varname> option allows a
+        custom derivation to be used, for example, one created by
+        <literal>emacsWithPackages</literal>.
+      </para>
+      <para>
+        Ensure that the Emacs server is enabled for your user's Emacs
+        configuration, either by customizing the
+        <varname>server-mode</varname> variable, or by adding
+        <literal>(server-start)</literal> to
+        <filename>~/.emacs.d/init.el</filename>.
+      </para>
+      <para>
+        To start the daemon, execute the following:
+      </para>
+      <programlisting>
+$ nixos-rebuild switch  # to activate the new configuration.nix
+$ systemctl --user daemon-reload        # to force systemd reload
+$ systemctl --user start emacs.service  # to start the Emacs daemon
+</programlisting>
+      <para>
+        The server should now be ready to serve Emacs clients.
+      </para>
+    </section>
+    <section xml:id="module-services-emacs-starting-client">
+      <title>Starting the client</title>
+      <para>
+        Ensure that the emacs server is enabled, either by customizing
+        the <varname>server-mode</varname> variable, or by adding
+        <literal>(server-start)</literal> to
+        <filename>~/.emacs</filename>.
+      </para>
+      <para>
+        To connect to the emacs daemon, run one of the following:
+      </para>
+      <programlisting>
 emacsclient FILENAME
 emacsclient --create-frame  # opens a new frame (window)
 emacsclient --create-frame --tty  # opens a new frame on the current terminal
-]]></programlisting>
-   </para>
-  </section>
-
-  <section xml:id="module-services-emacs-editor-variable">
-   <title>Configuring the <varname>EDITOR</varname> variable</title>
-
-<!--<title><command>emacsclient</command> as the Default Editor</title>-->
-
-   <para>
-    If <xref linkend="opt-services.emacs.defaultEditor"/> is
-    <literal>true</literal>, the <varname>EDITOR</varname> variable will be set
-    to a wrapper script which launches <command>emacsclient</command>.
-   </para>
-
-   <para>
-    Any setting of <varname>EDITOR</varname> in the shell config files will
-    override <varname>services.emacs.defaultEditor</varname>. To make sure
-    <varname>EDITOR</varname> refers to the Emacs wrapper script, remove any
-    existing <varname>EDITOR</varname> assignment from
-    <filename>.profile</filename>, <filename>.bashrc</filename>,
-    <filename>.zshenv</filename> or any other shell config file.
-   </para>
-
-   <para>
-    If you have formed certain bad habits when editing files, these can be
-    corrected with a shell alias to the wrapper script:
-    <programlisting>
+</programlisting>
+    </section>
+    <section xml:id="module-services-emacs-editor-variable">
+      <title>Configuring the <varname>EDITOR</varname> variable</title>
+      <para>
+        If <xref linkend="opt-services.emacs.defaultEditor"></xref> is
+        <literal>true</literal>, the <varname>EDITOR</varname> variable
+        will be set to a wrapper script which launches
+        <command>emacsclient</command>.
+      </para>
+      <para>
+        Any setting of <varname>EDITOR</varname> in the shell config
+        files will override
+        <varname>services.emacs.defaultEditor</varname>. To make sure
+        <varname>EDITOR</varname> refers to the Emacs wrapper script,
+        remove any existing <varname>EDITOR</varname> assignment from
+        <filename>.profile</filename>, <filename>.bashrc</filename>,
+        <filename>.zshenv</filename> or any other shell config file.
+      </para>
+      <para>
+        If you have formed certain bad habits when editing files, these
+        can be corrected with a shell alias to the wrapper script:
+      </para>
+      <programlisting>
 alias vi=$EDITOR
 </programlisting>
-   </para>
-  </section>
-
-  <section xml:id="module-services-emacs-per-user">
-   <title>Per-User Enabling of the Service</title>
-
-   <para>
-    In general, <command>systemd</command> user services are globally enabled
-    by symlinks in <filename>/etc/systemd/user</filename>. In the case where
-    Emacs daemon is not wanted for all users, it is possible to install the
-    service but not globally enable it:
-<programlisting>
+    </section>
+    <section xml:id="module-services-emacs-per-user">
+      <title>Per-User Enabling of the Service</title>
+      <para>
+        In general, <command>systemd</command> user services are
+        globally enabled by symlinks in
+        <filename>/etc/systemd/user</filename>. In the case where Emacs
+        daemon is not wanted for all users, it is possible to install
+        the service but not globally enable it:
+      </para>
+      <programlisting>
 services.emacs.enable = false;
 services.emacs.install = true;
 </programlisting>
-   </para>
-
-   <para>
-    To enable the <command>systemd</command> user service for just the
-    currently logged in user, run:
-    <programlisting>
+      <para>
+        To enable the <command>systemd</command> user service for just
+        the currently logged in user, run:
+      </para>
+      <programlisting>
 systemctl --user enable emacs
 </programlisting>
-    This will add the symlink
-    <filename>~/.config/systemd/user/emacs.service</filename>.
-   </para>
+      <para>
+        This will add the symlink
+        <filename>~/.config/systemd/user/emacs.service</filename>.
+      </para>
+    </section>
   </section>
- </section>
- <section xml:id="module-services-emacs-configuring">
-  <title>Configuring Emacs</title>
-
-  <para>
-   The Emacs init file should be changed to load the extension packages at
-   startup:
-   <anchor xml:id="module-services-emacs-package-initialisation" />
-<programlisting><![CDATA[
+  <section xml:id="module-services-emacs-configuring">
+    <title>Configuring Emacs</title>
+    <para>
+      The Emacs init file should be changed to load the extension
+      packages at startup:
+      <anchor xml:id="module-services-emacs-package-initialisation" />
+    </para>
+    <programlisting>
 (require 'package)
 
 ;; optional. makes unpure packages archives unavailable
@@ -456,89 +416,73 @@ systemctl --user enable emacs
 
 (setq package-enable-at-startup nil)
 (package-initialize)
-]]></programlisting>
-  </para>
-
-  <para>
-   After the declarative emacs package configuration has been tested,
-   previously downloaded packages can be cleaned up by removing
-   <filename>~/.emacs.d/elpa</filename> (do make a backup first, in case you
-   forgot a package).
-  </para>
-
-<!--
-      todo: is it worth documenting customizations for
-      server-switch-hook, server-done-hook?
-  -->
-
-  <section xml:id="module-services-emacs-major-mode">
-   <title>A Major Mode for Nix Expressions</title>
-
-   <para>
-    Of interest may be <varname>melpaPackages.nix-mode</varname>, which
-    provides syntax highlighting for the Nix language. This is particularly
-    convenient if you regularly edit Nix files.
-   </para>
-  </section>
-
-  <section xml:id="module-services-emacs-man-pages">
-   <title>Accessing man pages</title>
-
-   <para>
-    You can use <literal>woman</literal> to get completion of all available
-    man pages. For example, type <literal>M-x woman &lt;RET&gt; nixos-rebuild
-    &lt;RET&gt;.</literal>
-   </para>
-  </section>
-
-  <section xml:id="sec-emacs-docbook-xml">
-   <title>Editing DocBook 5 XML Documents</title>
-
-   <para>
-    Emacs includes
-    <link
-      xlink:href="https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html">nXML</link>,
-    a major-mode for validating and editing XML documents. When editing DocBook
-    5.0 documents, such as <link linkend="book-nixos-manual">this one</link>,
-    nXML needs to be configured with the relevant schema, which is not
-    included.
-   </para>
-
-   <para>
-    To install the DocBook 5.0 schemas, either add
-    <varname>pkgs.docbook5</varname> to
-    <xref linkend="opt-environment.systemPackages"/>
-    (<link
-      linkend="sec-declarative-package-mgmt">NixOS</link>), or run
-    <literal>nix-env -f '&lt;nixpkgs&gt;' -iA docbook5</literal>
-    (<link linkend="sec-ad-hoc-packages">Nix</link>).
-   </para>
-
-   <para>
-    Then customize the variable <varname>rng-schema-locating-files</varname> to
-    include <filename>~/.emacs.d/schemas.xml</filename> and put the following
-    text into that file:
-    <anchor xml:id="ex-emacs-docbook-xml" />
-<programlisting language="xml"><![CDATA[
-<?xml version="1.0"?>
-<!--
+</programlisting>
+    <para>
+      After the declarative emacs package configuration has been tested,
+      previously downloaded packages can be cleaned up by removing
+      <filename>~/.emacs.d/elpa</filename> (do make a backup first, in
+      case you forgot a package).
+    </para>
+    <section xml:id="module-services-emacs-major-mode">
+      <title>A Major Mode for Nix Expressions</title>
+      <para>
+        Of interest may be <varname>melpaPackages.nix-mode</varname>,
+        which provides syntax highlighting for the Nix language. This is
+        particularly convenient if you regularly edit Nix files.
+      </para>
+    </section>
+    <section xml:id="module-services-emacs-man-pages">
+      <title>Accessing man pages</title>
+      <para>
+        You can use <literal>woman</literal> to get completion of all
+        available man pages. For example, type
+        <literal>M-x woman &lt;RET&gt; nixos-rebuild &lt;RET&gt;.</literal>
+      </para>
+    </section>
+    <section xml:id="sec-emacs-docbook-xml">
+      <title>Editing DocBook 5 XML Documents</title>
+      <para>
+        Emacs includes
+        <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html">nXML</link>,
+        a major-mode for validating and editing XML documents. When
+        editing DocBook 5.0 documents, such as
+        <link linkend="book-nixos-manual">this one</link>, nXML needs to
+        be configured with the relevant schema, which is not included.
+      </para>
+      <para>
+        To install the DocBook 5.0 schemas, either add
+        <varname>pkgs.docbook5</varname> to
+        <xref linkend="opt-environment.systemPackages"></xref>
+        (<link linkend="sec-declarative-package-mgmt">NixOS</link>), or
+        run <literal>nix-env -f '&lt;nixpkgs&gt;' -iA docbook5</literal>
+        (<link linkend="sec-ad-hoc-packages">Nix</link>).
+      </para>
+      <para>
+        Then customize the variable
+        <varname>rng-schema-locating-files</varname> to include
+        <filename>~/.emacs.d/schemas.xml</filename> and put the
+        following text into that file:
+        <anchor xml:id="ex-emacs-docbook-xml" />
+      </para>
+      <programlisting language="xml">
+&lt;?xml version=&quot;1.0&quot;?&gt;
+&lt;!--
   To let emacs find this file, evaluate:
-  (add-to-list 'rng-schema-locating-files "~/.emacs.d/schemas.xml")
--->
-<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
-  <!--
+  (add-to-list 'rng-schema-locating-files &quot;~/.emacs.d/schemas.xml&quot;)
+--&gt;
+&lt;locatingRules xmlns=&quot;http://thaiopensource.com/ns/locating-rules/1.0&quot;&gt;
+  &lt;!--
     Use this variation if pkgs.docbook5 is added to environment.systemPackages
-  -->
-  <namespace ns="http://docbook.org/ns/docbook"
-             uri="/run/current-system/sw/share/xml/docbook-5.0/rng/docbookxi.rnc"/>
-  <!--
-    Use this variation if installing schema with "nix-env -iA pkgs.docbook5".
-  <namespace ns="http://docbook.org/ns/docbook"
-             uri="../.nix-profile/share/xml/docbook-5.0/rng/docbookxi.rnc"/>
-  -->
-</locatingRules>
-]]></programlisting>
-   </para>
+  --&gt;
+  &lt;namespace ns=&quot;http://docbook.org/ns/docbook&quot;
+             uri=&quot;/run/current-system/sw/share/xml/docbook-5.0/rng/docbookxi.rnc&quot;/&gt;
+  &lt;!--
+    Use this variation if installing schema with &quot;nix-env -iA pkgs.docbook5&quot;.
+  &lt;namespace ns=&quot;http://docbook.org/ns/docbook&quot;
+             uri=&quot;../.nix-profile/share/xml/docbook-5.0/rng/docbookxi.rnc&quot;/&gt;
+  --&gt;
+&lt;/locatingRules&gt;
+</programlisting>
+    </section>
   </section>
- </section>
 </chapter>