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.

3 files changed, 62 insertions, 129 deletions

diff --git a/nixos/modules/services/editors/emacs.xml b/nixos/modules/services/editors/emacs.xml
index d0e781e6786..7b847f1f798 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>
diff --git a/nixos/modules/services/matrix/synapse.xml b/nixos/modules/services/matrix/synapse.xml
index 4d0db9c5a5b..b4abe2901fe 100644
--- a/nixos/modules/services/matrix/synapse.xml
+++ b/nixos/modules/services/matrix/synapse.xml
@@ -67,20 +67,41 @@ in {
     recommendedGzipSettings = true;
     recommendedProxySettings = true;
     virtualHosts = {
-      "${config.networking.domain}" = { <co xml:id='ex-matrix-synapse-dns' />
+      # If the A and AAAA DNS records on example.org do not point on the same host as the
+      # records for myhostname.example.org, you can easily move the /.well-known
+      # virtualHost section of the code to the host that is serving example.org, while
+      # the rest stays on myhostname.example.org with no other changes required.
+      # This pattern also allows to seamlessly move the homeserver from
+      # myhostname.example.org to myotherhost.example.org by only changing the
+      # /.well-known redirection target.
+      "${config.networking.domain}" = {
         enableACME = true;
         forceSSL = true;
-        locations."= /.well-known/matrix/server".extraConfig = mkWellKnown serverConfig; <co xml:id='ex-matrix-synapse-well-known-server' />
-        locations."= /.well-known/matrix/client".extraConfig = mkWellKnown clientConfig; <co xml:id='ex-matrix-synapse-well-known-client' />
+        # This section is not needed if the server_name of matrix-synapse is equal to
+        # the domain (i.e. example.org from @foo:example.org) and the federation port
+        # is 8448.
+        # Further reference can be found in the docs about delegation under
+        # https://matrix-org.github.io/synapse/latest/delegate.html
+        locations."= /.well-known/matrix/server".extraConfig = mkWellKnown serverConfig;
+        # This is usually needed for homeserver discovery (from e.g. other Matrix clients).
+        # Further reference can be found in the upstream docs at
+        # https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixclient
+        locations."= /.well-known/matrix/client".extraConfig = mkWellKnown clientConfig;
       };
       "${fqdn}" = {
         enableACME = true;
         forceSSL = true;
-        locations."/".extraConfig = '' <co xml:id='ex-matrix-synapse-rev-default' />
+        # It's also possible to do a redirect here or something else, this vhost is not
+        # needed for Matrix. It's recommended though to *not put* element
+        # here, see also the section about Element.
+        locations."/".extraConfig = ''
           return 404;
         '';
-        locations."/_matrix".proxyPass = "http://[::1]:8008"; <co xml:id='ex-matrix-synapse-rev-proxy-pass' />
-        locations."/_synapse/client".proxyPass = "http://[::1]:8008"; <co xml:id='ex-matrix-synapse-rev-client' />
+        # Forward all Matrix API calls to the synapse Matrix homeserver. A trailing slash
+        # *must not* be used here.
+        locations."/_matrix".proxyPass = "http://[::1]:8008";
+        # Forward requests for e.g. SSO and password-resets.
+        locations."/_synapse/client".proxyPass = "http://[::1]:8008";
       };
     };
   };
@@ -104,56 +125,6 @@ in {
 }
 </programlisting>
   </para>
-  <calloutlist>
-   <callout arearefs='ex-matrix-synapse-dns'>
-    <para>
-     If the <code>A</code> and <code>AAAA</code> DNS records on
-     <literal>example.org</literal> do not point on the same host as the records
-     for <code>myhostname.example.org</code>, you can easily move the
-     <code>/.well-known</code> virtualHost section of the code to the host that
-     is serving <literal>example.org</literal>, while the rest stays on
-     <literal>myhostname.example.org</literal> with no other changes required.
-     This pattern also allows to seamlessly move the homeserver from
-     <literal>myhostname.example.org</literal> to
-     <literal>myotherhost.example.org</literal> by only changing the
-     <code>/.well-known</code> redirection target.
-    </para>
-   </callout>
-   <callout arearefs='ex-matrix-synapse-well-known-server'>
-    <para>
-     This section is not needed if the <link linkend="opt-services.matrix-synapse.settings.server_name">server_name</link>
-     of <literal>matrix-synapse</literal> is equal to the domain (i.e.
-     <literal>example.org</literal> from <literal>@foo:example.org</literal>)
-     and the federation port is 8448.
-     Further reference can be found in the <link xlink:href="https://matrix-org.github.io/synapse/latest/delegate.html">docs
-     about delegation</link>.
-    </para>
-   </callout>
-   <callout arearefs='ex-matrix-synapse-well-known-client'>
-    <para>
-     This is usually needed for homeserver discovery (from e.g. other Matrix clients).
-     Further reference can be found in the <link xlink:href="https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixclient">upstream docs</link>
-    </para>
-   </callout>
-   <callout arearefs='ex-matrix-synapse-rev-default'>
-    <para>
-     It's also possible to do a redirect here or something else, this vhost is not
-     needed for Matrix. It's recommended though to <emphasis>not put</emphasis> element
-     here, see also the <link linkend='ex-matrix-synapse-rev-default'>section about Element</link>.
-    </para>
-   </callout>
-   <callout arearefs='ex-matrix-synapse-rev-proxy-pass'>
-    <para>
-     Forward all Matrix API calls to the synapse Matrix homeserver. A trailing slash
-     <emphasis>must not</emphasis> be used here.
-    </para>
-   </callout>
-   <callout arearefs='ex-matrix-synapse-rev-client'>
-    <para>
-     Forward requests for e.g. SSO and password-resets.
-    </para>
-   </callout>
-  </calloutlist>
  </section>
  <section xml:id="module-services-matrix-register-users">
   <title>Registering Matrix users</title>
diff --git a/nixos/modules/services/web-apps/plausible.xml b/nixos/modules/services/web-apps/plausible.xml
index 929d4db2291..9546ae4e558 100644
--- a/nixos/modules/services/web-apps/plausible.xml
+++ b/nixos/modules/services/web-apps/plausible.xml
@@ -21,33 +21,23 @@
   services.plausible = {
     enable = true;
     adminUser = {
-      activate = true; <co xml:id='ex-plausible-cfg-activate' />
+      # activate is used to skip the email verification of the admin-user that's
+      # automatically created by plausible. This is only supported if
+      # postgresql is configured by the module. This is done by default, but
+      # can be turned off with services.plausible.database.postgres.setup.
+      activate = true;
       email = "admin@localhost";
       passwordFile = "/run/secrets/plausible-admin-pwd";
     };
     server = {
       baseUrl = "http://analytics.example.org";
-      secretKeybaseFile = "/run/secrets/plausible-secret-key-base"; <co xml:id='ex-plausible-cfg-secretbase' />
+      # secretKeybaseFile is a path to the file which contains the secret generated
+      # with openssl as described above.
+      secretKeybaseFile = "/run/secrets/plausible-secret-key-base";
     };
   };
 }
 </programlisting>
-   <calloutlist>
-    <callout arearefs='ex-plausible-cfg-activate'>
-     <para>
-      <varname>activate</varname> is used to skip the email verification of the admin-user that's
-      automatically created by <package>plausible</package>. This is only supported if
-      <package>postgresql</package> is configured by the module. This is done by default, but
-      can be turned off with <xref linkend="opt-services.plausible.database.postgres.setup" />.
-     </para>
-    </callout>
-    <callout arearefs='ex-plausible-cfg-secretbase'>
-     <para>
-      <varname>secretKeybaseFile</varname> is a path to the file which contains the secret generated
-      with <package>openssl</package> as described above.
-     </para>
-    </callout>
-   </calloutlist>
   </para>
  </section>
 </chapter>