nixos/manual: inline callout lists

we only have three uses at the moment, all of them in code blocks where
they could just as well (or maybe better) be comments. markdown can't do
callouts without another pandoc filter, so we'll turn them into comments
instead.

synapse would've benefited from inline links, but referencing an
external numbered list as plain text (instead of clickable links, like
callout lists had) seems even worse than putting urls into comments as
plain text.

1 files changed, 27 insertions, 55 deletions

diff --git a/nixos/modules/services/editors/emacs.xml b/nixos/modules/services/editors/emacs.xml
index d0e781e67865a..7b847f1f798e2 100644
--- a/nixos/modules/services/editors/emacs.xml
+++ b/nixos/modules/services/editors/emacs.xml
@@ -152,74 +152,46 @@ To run the newly compiled executable:
 
 $ ./result/bin/emacs
 */
-{ pkgs ? import &lt;nixpkgs&gt; {} }: <co xml:id="ex-emacsNix-1" />
+
+# The first non-comment line in this file indicates that
+# the whole file represents a function.
+{ pkgs ? import &lt;nixpkgs&gt; {} }:
 
 let
-  myEmacs = pkgs.emacs; <co xml:id="ex-emacsNix-2" />
-  emacsWithPackages = (pkgs.emacsPackagesFor myEmacs).emacsWithPackages; <co xml:id="ex-emacsNix-3" />
+  # 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
-  emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [ <co xml:id="ex-emacsNix-4" />
+  # 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 &lt;C-x g&gt;
     zerodark-theme # ; Nicolas' theme
-  ]) ++ (with epkgs.melpaPackages; [ <co xml:id="ex-emacsNix-5" />
+  ])
+  # Two packages (undo-tree and zoom-frm) are taken from MELPA.
+  ++ (with epkgs.melpaPackages; [
     undo-tree      # ; &lt;C-x u&gt; to show the undo tree
     zoom-frm       # ; increase/decrease font size for all buffers %lt;C-x C-+&gt;
-  ]) ++ (with epkgs.elpaPackages; [ <co xml:id="ex-emacsNix-6" />
+  ])
+  # 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
-  ]) ++ [
-    pkgs.notmuch   # From main packages set <co xml:id="ex-emacsNix-7" />
+  ])
+  # notmuch is taken from a nixpkgs derivation which contains an Emacs mode.
+  ++ [
+    pkgs.notmuch   # From main packages set
   ])
 </programlisting>
     </example>
-    <calloutlist>
-     <callout arearefs="ex-emacsNix-1">
-      <para>
-       The first non-comment line in this file (<literal>{ pkgs ? ...
-       }</literal>) indicates that the whole file represents a function.
-      </para>
-     </callout>
-     <callout arearefs="ex-emacsNix-2">
-      <para>
-       The <varname>let</varname> expression below defines a
-       <varname>myEmacs</varname> 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.
-      </para>
-     </callout>
-     <callout arearefs="ex-emacsNix-3">
-      <para>
-       This generates an <varname>emacsWithPackages</varname> 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).
-      </para>
-     </callout>
-     <callout arearefs="ex-emacsNix-4">
-      <para>
-       The rest of the file specifies the list of packages to install. In the
-       example, two packages (<varname>magit</varname> and
-       <varname>zerodark-theme</varname>) are taken from MELPA stable.
-      </para>
-     </callout>
-     <callout arearefs="ex-emacsNix-5">
-      <para>
-       Two packages (<varname>undo-tree</varname> and
-       <varname>zoom-frm</varname>) are taken from MELPA.
-      </para>
-     </callout>
-     <callout arearefs="ex-emacsNix-6">
-      <para>
-       Three packages are taken from GNU ELPA.
-      </para>
-     </callout>
-     <callout arearefs="ex-emacsNix-7">
-      <para>
-       <varname>notmuch</varname> is taken from a nixpkgs derivation which
-       contains an Emacs mode.
-      </para>
-     </callout>
-    </calloutlist>
    </para>
 
    <para>