nixos docs: give IDs to things

nixos/doc/manual/manual.xml

@@ -8,7 +8,7 @@
   <subtitle>Version <xi:include href="./generated/version" parse="text" />
   </subtitle>
  </info>
- <preface>
+ <preface xml:id="preface">
   <title>Preface</title>
   <para>
    This manual describes how to install, use and extend NixOS, a Linux

nixos/doc/manual/options-to-docbook.xsl

@@ -15,7 +15,7 @@
 
 
   <xsl:template match="/expr/list">
-    <appendix>
+    <appendix xml:id="appendix-configuration-options">
       <title>Configuration Options</title>
       <variablelist xml:id="configuration-variable-list">
         <xsl:for-each select="attrs">

nixos/modules/i18n/input-method/default.xml

@@ -23,7 +23,7 @@
       bridge.</para></listitem>
 </itemizedlist>
 
-<section><title>IBus</title>
+<section xml:id="module-services-input-methods-ibus"><title>IBus</title>
 
 <para>IBus is an Intelligent Input Bus. It provides full featured and user
   friendly input method user interface.</para>
@@ -82,7 +82,7 @@ ibus.engines = with pkgs.ibus-engines; [ table table-others ];
 </simplesect>
 </section>
 
-<section><title>Fcitx</title>
+<section xml:id="module-services-input-methods-fcitx"><title>Fcitx</title>
 
 <para>Fcitx is an input method framework with extension support. It has three
   built-in Input Method Engine, Pinyin, QuWei and Table-based input
@@ -122,7 +122,7 @@ i18n.inputMethod = {
 </itemizedlist>
 </section>
 
-<section><title>Nabi</title>
+<section xml:id="module-services-input-methods-nabi"><title>Nabi</title>
 
 <para>Nabi is an easy to use Korean X input method. It allows you to enter
   phonetic Korean characters (hangul) and pictographic Korean characters
@@ -136,7 +136,7 @@ i18n.inputMethod = {
 </programlisting>
 </section>
 
-<section><title>Uim</title>
+<section xml:id="module-services-input-methods-uim"><title>Uim</title>
 
 <para>Uim (short for "universal input method") is a multilingual input method
   framework. Applications can use it through so-called bridges.</para>

nixos/modules/programs/zsh/oh-my-zsh.xml

@@ -10,7 +10,7 @@
 to manage your <link xlink:href="https://www.zsh.org/">ZSH</link> configuration
 including completion scripts for several CLI tools or custom prompt themes.</para>
 
-<section><title>Basic usage</title>
+<section xml:id="module-programs-oh-my-zsh-usage"><title>Basic usage</title>
 <para>The module uses the <literal>oh-my-zsh</literal> package with all available features.  The
 initial setup using Nix expressions is fairly similar to the configuration format
 of <literal>oh-my-zsh</literal>.
@@ -32,7 +32,7 @@ For a detailed explanation of these arguments please refer to the
 configuration and writes it into your <literal>/etc/zshrc</literal>.
 </para></section>
 
-<section><title>Custom additions</title>
+<section xml:id="module-programs-oh-my-zsh-additions"><title>Custom additions</title>
 
 <para>Sometimes third-party or custom scripts such as a modified theme may be needed.
 <literal>oh-my-zsh</literal> provides the
@@ -48,7 +48,7 @@ environment variable for this which points to a directory with additional script
 </programlisting>
 </para></section>
 
-<section><title>Custom environments</title>
+<section xml:id="module-programs-oh-my-zsh-environments"><title>Custom environments</title>
 
 <para>There are several extensions for <literal>oh-my-zsh</literal> packaged in <literal>nixpkgs</literal>.
 One of them is <link xlink:href="https://github.com/spwhitt/nix-zsh-completions">nix-zsh-completions</link>
@@ -77,7 +77,7 @@ as it requires an immutable store path while <literal>custom</literal> shall rem
 will be thrown if both <literal>custom</literal> and <literal>customPkgs</literal> are set.</emphasis>
 </para></section>
 
-<section><title>Package your own customizations</title>
+<section xml:id="module-programs-oh-my-zsh-packaging-customizations"><title>Package your own customizations</title>
 
 <para>If third-party customizations (e.g. new themes) are supposed to be added to <literal>oh-my-zsh</literal>
 there are several pitfalls to keep in mind:</para>

nixos/modules/security/acme.xml

@@ -11,7 +11,7 @@ retrieval and renewal using the ACME protocol. This is currently only
 implemented by and for Let's Encrypt. The alternative ACME client
 <literal>simp_le</literal> is used under the hood.</para>
 
-<section><title>Prerequisites</title>
+<section xml:id="module-security-acme-prerequisites"><title>Prerequisites</title>
 
 <para>You need to have a running HTTP server for verification. The server must
 have a webroot defined that can serve
@@ -41,7 +41,7 @@ http {
 
 </section>
 
-<section><title>Configuring</title>
+<section xml:id="module-security-acme-configuring"><title>Configuring</title>
 
 <para>To enable ACME certificate retrieval &amp; renewal for a certificate for
 <literal>foo.example.com</literal>, add the following in your
@@ -66,7 +66,7 @@ options for the <link linkend="opt-security.acme.certs">security.acme</link> mod
 
 </section>
 
-<section><title>Using ACME certificates in Nginx</title>
+<section xml:id="module-security-acme-nginx"><title>Using ACME certificates in Nginx</title>
 <para>NixOS supports fetching ACME certificates for you by setting
   <literal><link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;</literal> in a virtualHost config. We
 first create self-signed placeholder certificates in place of the

nixos/modules/services/databases/foundationdb.xml

@@ -17,7 +17,7 @@
 <para>FoundationDB (or "FDB") is an open source, distributed, transactional
 key-value store.</para>
 
-<section><title>Configuring and basic setup</title>
+<section xml:id="module-services-foundationdb-configuring"><title>Configuring and basic setup</title>
 
 <para>To enable FoundationDB, add the following to your
 <filename>configuration.nix</filename>:
@@ -133,7 +133,7 @@ corresponding <option>services.foundationdb.logDir</option> as well.</para>
 
 </section>
 
-<section><title>Scaling processes and backup agents</title>
+<section xml:id="module-services-foundationdb-scaling"><title>Scaling processes and backup agents</title>
 
 <para>Scaling the number of server processes is quite easy; simply specify
 <option>services.foundationdb.serverProcesses</option> to be the number of
@@ -151,7 +151,7 @@ available backup processes.</para>
 
 </section>
 
-<section><title>Clustering</title>
+<section xml:id="module-services-foundationdb-clustering"><title>Clustering</title>
 
 <para>FoundationDB on NixOS works similarly to other Linux systems, so this
 section will be brief. Please refer to the full FoundationDB documentation for
@@ -221,7 +221,7 @@ informing all client processes to do the same.</para>
 
 </section>
 
-<section><title>Client connectivity</title>
+<section xml:id="module-services-foundationdb-connectivity"><title>Client connectivity</title>
 
 <para>By default, all clients must use the current
 <command>fdb.cluster</command> file to access a given FoundationDB cluster.
@@ -232,7 +232,7 @@ to a new node in order to connect, if it is not part of the cluster.</para>
 
 </section>
 
-<section><title>Client authorization and TLS</title>
+<section xml:id="module-services-foundationdb-authorization"><title>Client authorization and TLS</title>
 
 <para>By default, any user who can connect to a FoundationDB process with the
 correct cluster configuration can access anything. FoundationDB uses a
@@ -270,7 +270,7 @@ on.</para>
 
 </section>
 
-<section><title>Backups and Disaster Recovery</title>
+<section xml:id="module-services-foundationdb-disaster-recovery"><title>Backups and Disaster Recovery</title>
 
 <para>The usual rules for doing FoundationDB backups apply on NixOS as written
 in the FoundationDB manual. However, one important difference is the security
@@ -316,7 +316,7 @@ $ sudo -u foundationdb fdbbackup status -t default
 
 </section>
 
-<section><title>Known limitations</title>
+<section xml:id="module-services-foundationdb-limitations"><title>Known limitations</title>
 
 <para>The FoundationDB setup for NixOS should currently be considered beta.
 FoundationDB is not new software, but the NixOS compilation and integration has
@@ -333,7 +333,7 @@ only undergone fairly basic testing of all the available functionality.</para>
 
 </section>
 
-<section><title>Options</title>
+<section xml:id="module-services-foundationdb-options"><title>Options</title>
 
 <para>NixOS's FoundationDB module allows you to configure all of the most
 relevant configuration options for <command>fdbmonitor</command>, matching it
@@ -343,7 +343,7 @@ also read the FoundationDB documentation as well.</para>
 
 </section>
 
-<section><title>Full documentation</title>
+<section xml:id="module-services-foundationdb-full-docs"><title>Full documentation</title>
 
 <para>FoundationDB is a complex piece of software, and requires careful
 administration to properly use. Full documentation for administration can be

nixos/modules/services/databases/postgresql.xml

@@ -17,7 +17,7 @@
 
 <para>PostgreSQL is an advanced, free relational database.<!-- MORE --></para>
 
-<section><title>Configuring</title>
+<section xml:id="module-services-postgres-configuring"><title>Configuring</title>
 
 <para>To enable PostgreSQL, add the following to your
 <filename>configuration.nix</filename>:
@@ -60,14 +60,14 @@ alice=>
 </section>
 
 
-<section><title>Upgrading</title>
+<section xml:id="module-services-postgres-upgrading"><title>Upgrading</title>
 
 <para>FIXME: document dump/upgrade/load cycle.</para>
 
 </section>
 
 
-<section><title>Options</title>
+<section xml:id="module-services-postgres-options"><title>Options</title>
 
   <para>A complete list of options for the PostgreSQL module may be found <link linkend="opt-services.postgresql.enable">here</link>.</para>
 

nixos/modules/services/editors/emacs.xml

@@ -39,7 +39,7 @@
     starting the Emacs daemon.
   </para>
 
-  <section>
+  <section xml:id="module-services-emacs-installing">
     <title>Installing <application>Emacs</application></title>
 
     <para>
@@ -49,7 +49,7 @@
       can be enabled.
     </para>
 
-    <section>
+    <section xml:id="module-services-emacs-releases">
       <title>The Different Releases of Emacs</title>
 
       <para>
@@ -100,7 +100,7 @@
       </para>
 
     </section>
-    <section>
+    <section xml:id="module-services-emacs-adding-packages">
       <title>Adding Packages to Emacs</title>
       <para>
         Emacs includes an entire ecosystem of functionality beyond
@@ -339,7 +339,7 @@ https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides
       </para>
     </section>
 
-    <section>
+    <section xml:id="module-services-emacs-advanced">
       <title>Advanced Emacs Configuration</title>
 
       <para>
@@ -380,7 +380,7 @@ in [...]
     </section>
   </section>
 
-<section>
+<section xml:id="module-services-emacs-running">
   <title>Running Emacs as a Service</title>
   <para>
     <productname>NixOS</productname> provides an optional
@@ -396,7 +396,7 @@ in [...]
     <filename>modules/services/editors/emacs.nix</filename>
   </para>
 
-  <section>
+  <section xml:id="module-services-emacs-enabling">
     <title>Enabling the Service</title>
 
     <para>
@@ -438,7 +438,7 @@ $ systemctl --user start emacs.service  # to start the Emacs daemon
 
   </section>
 
-  <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
@@ -457,7 +457,7 @@ emacsclient --create-frame --tty  # opens a new frame on the current terminal
     </para>
   </section>
 
-  <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>-->
 
@@ -487,7 +487,7 @@ emacsclient --create-frame --tty  # opens a new frame on the current terminal
     </para>
   </section>
 
-  <section>
+  <section xml:id="module-services-emacs-per-user">
     <title>Per-User Enabling of the Service</title>
 
     <para>
@@ -515,7 +515,7 @@ emacsclient --create-frame --tty  # opens a new frame on the current terminal
   </section>
 </section>
 
-<section>
+<section xml:id="module-services-emacs-configuring">
   <title>Configuring Emacs</title>
 
   <para>
@@ -548,7 +548,7 @@ emacsclient --create-frame --tty  # opens a new frame on the current terminal
       server-switch-hook, server-done-hook?
   -->
 
-  <section>
+  <section xml:id="module-services-emacs-major-mode">
     <title>A Major Mode for Nix Expressions</title>
 
     <para>
@@ -558,7 +558,7 @@ emacsclient --create-frame --tty  # opens a new frame on the current terminal
     </para>
   </section>
 
-  <section>
+  <section xml:id="module-services-emacs-man-pages">
     <title>Accessing man pages</title>
     <para>
       You can use <function>woman</function> to get completion of all

nixos/modules/services/misc/gitlab.xml

@@ -8,7 +8,7 @@
 
 <para>Gitlab is a feature-rich git hosting service.</para>
 
-<section><title>Prerequisites</title>
+<section xml:id="module-services-gitlab-prerequisites"><title>Prerequisites</title>
 
 <para>The gitlab service exposes only an Unix socket at
 <literal>/run/gitlab/gitlab-workhorse.socket</literal>. You need to configure a
@@ -35,7 +35,7 @@ webserver to proxy HTTP requests to the socket.</para>
 
 </section>
 
-<section><title>Configuring</title>
+<section xml:id="module-services-gitlab-configuring"><title>Configuring</title>
 
 <para>Gitlab depends on both PostgreSQL and Redis and will automatically enable
 both services. In the case of PostgreSQL, a database and a role will be created.
@@ -119,7 +119,7 @@ options for the <link linkend="opt-services.gitlab.enable">services.gitlab</link
 
 </section>
 
-<section><title>Maintenance</title>
+<section xml:id="module-services-gitlab-maintenance"><title>Maintenance</title>
 
 <para>You can run Gitlab's rake tasks with <literal>gitlab-rake</literal>
 which will be available on the system when gitlab is enabled. You will

nixos/modules/services/misc/taskserver/doc.xml

@@ -16,7 +16,7 @@
     <link xlink:href="https://taskwarrior.org/docs/#taskd"/>
   </para>
 
-  <section>
+  <section xml:id="module-services-taskserver-configuration">
     <title>Configuration</title>
 
     <para>
@@ -48,7 +48,7 @@
     </para>
   </section>
 
-  <section>
+  <section xml:id="module-services-taskserver-nixos-taskserver-tool">
     <title>The nixos-taskserver tool</title>
 
     <para>
@@ -78,7 +78,7 @@
       <option>--help</option> switch.
     </para>
   </section>
-  <section>
+  <section xml:id="module-services-taskserver-declarative-ca-management">
     <title>Declarative/automatic CA management</title>
 
     <para>
@@ -131,7 +131,7 @@ $ ssh server nixos-taskserver user export my-company alice | sh
       <command>task sync</command> after that stage.
     </para>
   </section>
-  <section>
+  <section xml:id="module-services-taskserver-manual-ca-management">
     <title>Manual CA management</title>
 
     <para>

nixos/modules/services/monitoring/prometheus/exporters.xml

@@ -8,7 +8,7 @@
 
 <para>Prometheus exporters provide metrics for the <link xlink:href="https://prometheus.io">prometheus monitoring system</link>.</para>
 
-<section><title>Configuration</title>
+<section xml:id="module-services-prometheus-exporters-configuration"><title>Configuration</title>
   <para>One of the most common exporters is the <link xlink:href="https://github.com/prometheus/node_exporter">node exporter</link>, it provides hardware and OS metrics from the host it's running on. The exporter could be configured as follows:
 <programlisting>
   services.promtheus.exporters.node = {
@@ -33,7 +33,7 @@ For more information about configuration see <literal>man configuration.nix</lit
 search through the <link xlink:href="https://nixos.org/nixos/options.html#prometheus.exporters">available options</link>.
 </para>
 </section>
-<section><title>Adding a new exporter</title>
+<section xml:id="module-services-prometheus-exporters-new-exporter"><title>Adding a new exporter</title>
   <para>To add a new exporter, it has to be packaged first (see <literal>nixpkgs/pkgs/servers/monitoring/prometheus/</literal> for examples), then a module can be added. The postfix exporter is used in this example:</para>
 <itemizedlist>
   <listitem>

nixos/modules/services/networking/dnscrypt-proxy.xml

@@ -14,7 +14,7 @@
     upstream is trustworthy).
   </para>
 
-  <sect1><title>Basic configuration</title>
+  <sect1 xml:id="sec-dnscrypt-proxy-configuration"><title>Basic configuration</title>
 
   <para>
     To enable the client proxy, set
@@ -31,7 +31,7 @@
 
   </sect1>
 
-  <sect1><title>As a forwarder for another DNS client</title>
+  <sect1 xml:id="sec-dnscrypt-proxy-forwarder"><title>As a forwarder for another DNS client</title>
 
   <para>
     To run the DNSCrypt proxy client as a forwarder for another
@@ -42,7 +42,7 @@
     </programlisting>
   </para>
 
-  <sect2><title>dnsmasq</title>
+  <sect2 xml:id="sec-dnscrypt-proxy-forwarder-dsnmasq"><title>dnsmasq</title>
   <para>
     <programlisting>
 {
@@ -53,7 +53,7 @@
   </para>
   </sect2>
 
-  <sect2><title>unbound</title>
+  <sect2 xml:id="sec-dnscrypt-proxy-forwarder-unbound"><title>unbound</title>
   <para>
     <programlisting>
 {

nixos/modules/services/web-apps/matomo-doc.xml

@@ -15,7 +15,7 @@
   </para>
 
 
-  <section>
+  <section xml:id="module-services-matomo-database-setup">
     <title>Database Setup</title>
 
     <para>
@@ -51,7 +51,7 @@
   </section>
 
 
-  <section>
+  <section xml:id="module-services-matomo-backups">
     <title>Backup</title>
     <para>
       You only need to take backups of your MySQL database and the
@@ -62,7 +62,7 @@
   </section>
 
 
-  <section>
+  <section xml:id="module-services-matomo-issues">
     <title>Issues</title>
     <itemizedlist>
       <listitem>
@@ -83,7 +83,7 @@
   </section>
 
 
-  <section>
+  <section xml:id="module-services-matomo-other-web-servers">
     <title>Using other Web Servers than nginx</title>
 
     <para>