Improve cross referencing in NixOS Manual

.editorconfig

@@ -13,8 +13,8 @@ charset = utf-8
 
 # see https://nixos.org/nixpkgs/manual/#chap-conventions
 
-# Match nix/ruby files, set indent to spaces with width of two
-[*.{nix,rb}]
+# Match nix/ruby/docbook files, set indent to spaces with width of two
+[*.{nix,rb,xml}]
 indent_style = space
 indent_size = 2
 

nixos/doc/manual/administration/cleaning-store.xml

@@ -29,8 +29,8 @@ this unit automatically at certain points in time, for instance, every
 night at 03:15:
 
 <programlisting>
-nix.gc.automatic = true;
-nix.gc.dates = "03:15";
+<xref linkend="opt-nix.gc.automatic"/> = true;
+<xref linkend="opt-nix.gc.dates"/> = "03:15";
 </programlisting>
 
 </para>

nixos/doc/manual/administration/container-networking.xml

@@ -39,9 +39,9 @@ IP address. This can be accomplished using the following configuration
 on the host:
 
 <programlisting>
-networking.nat.enable = true;
-networking.nat.internalInterfaces = ["ve-+"];
-networking.nat.externalInterface = "eth0";
+<xref linkend="opt-networking.nat.enable"/> = true;
+<xref linkend="opt-networking.nat.internalInterfaces"/> = ["ve-+"];
+<xref linkend="opt-networking.nat.externalInterface"/> = "eth0";
 </programlisting>
 where <literal>eth0</literal> should be replaced with the desired
 external interface. Note that <literal>ve-+</literal> is a wildcard

nixos/doc/manual/administration/control-groups.xml

@@ -47,7 +47,7 @@ would get 1/1001 of the cgroup’s CPU time.)  You can limit a service’s
 CPU share in <filename>configuration.nix</filename>:
 
 <programlisting>
-systemd.services.httpd.serviceConfig.CPUShares = 512;
+<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.CPUShares = 512;
 </programlisting>
 
 By default, every cgroup has 1024 CPU shares, so this will halve the
@@ -61,7 +61,7 @@ available memory.  Per-cgroup memory limits can be specified in
 <literal>httpd.service</literal> to 512 MiB of RAM (excluding swap):
 
 <programlisting>
-systemd.services.httpd.serviceConfig.MemoryLimit = "512M";
+<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.MemoryLimit = "512M";
 </programlisting>
 
 </para>

nixos/doc/manual/administration/declarative-containers.xml

@@ -15,8 +15,8 @@ following specifies that there shall be a container named
 containers.database =
   { config =
       { config, pkgs, ... }:
-      { services.postgresql.enable = true;
-        services.postgresql.package = pkgs.postgresql96;
+      { <xref linkend="opt-services.postgresql.enable"/> = true;
+      <xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql96;
       };
   };
 </programlisting>
@@ -33,11 +33,11 @@ ports. However, they cannot change the network configuration. You can
 give a container its own network as follows:
 
 <programlisting>
-containers.database =
-  { privateNetwork = true;
-    hostAddress = "192.168.100.10";
-    localAddress = "192.168.100.11";
-  };
+containers.database = {
+  <link linkend="opt-containers._name_.privateNetwork">privateNetwork</link> = true;
+  <link linkend="opt-containers._name_.hostAddress">hostAddress</link> = "192.168.100.10";
+  <link linkend="opt-containers._name_.localAddress">localAddress</link> = "192.168.100.11";
+};
 </programlisting>
 
 This gives the container a private virtual Ethernet interface with IP

nixos/doc/manual/administration/imperative-containers.xml

@@ -30,8 +30,8 @@ line. For instance, to create a container that has
 
 <screen>
 # nixos-container create foo --config '
-  services.openssh.enable = true;
-  users.extraUsers.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"];
+  <xref linkend="opt-services.openssh.enable"/> = true;
+  <link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.extraUsers.root.openssh.authorizedKeys.keys</link> = ["ssh-dss AAAAB3N…"];
 '
 </screen>
 
@@ -100,9 +100,9 @@ specify a new configuration on the command line:
 
 <screen>
 # nixos-container update foo --config '
-  services.httpd.enable = true;
-  services.httpd.adminAddr = "foo@example.org";
-  networking.firewall.allowedTCPPorts = [ 80 ];
+  <xref linkend="opt-services.httpd.enable"/> = true;
+  <xref linkend="opt-services.httpd.adminAddr"/> = "foo@example.org";
+  <xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 ];
 '
 
 # curl http://$(nixos-container show-ip foo)/

nixos/doc/manual/configuration/abstractions.xml

@@ -11,7 +11,7 @@ to abstract.  Take, for instance, this Apache HTTP Server configuration:
 
 <programlisting>
 {
-  services.httpd.virtualHosts =
+  <xref linkend="opt-services.httpd.virtualHosts"/> =
     [ { hostName = "example.org";
         documentRoot = "/webroot";
         adminAddr = "alice@example.org";
@@ -43,7 +43,7 @@ let
     };
 in
 {
-  services.httpd.virtualHosts =
+  <xref linkend="opt-services.httpd.virtualHosts"/> =
     [ exampleOrgCommon
       (exampleOrgCommon // {
         enableSSL = true;
@@ -66,7 +66,7 @@ allowed.  Thus, you also could have written:
 
 <programlisting>
 {
-  services.httpd.virtualHosts =
+  <xref linkend="opt-services.httpd.virtualHosts"/> =
     let exampleOrgCommon = <replaceable>...</replaceable>; in
     [ exampleOrgCommon
       (exampleOrgCommon // { <replaceable>...</replaceable> })
@@ -86,7 +86,7 @@ the host name.  This can be done as follows:
 
 <programlisting>
 {
-  services.httpd.virtualHosts =
+  <xref linkend="opt-services.httpd.virtualHosts"/> =
     let
       makeVirtualHost = name:
         { hostName = name;
@@ -113,7 +113,7 @@ element in a list:
 
 <programlisting>
 {
-  services.httpd.virtualHosts =
+  <xref linkend="opt-services.httpd.virtualHosts"/> =
     let
       makeVirtualHost = <replaceable>...</replaceable>;
     in map makeVirtualHost
@@ -132,7 +132,7 @@ function that takes a <emphasis>set</emphasis> as its argument, like this:
 
 <programlisting>
 {
-  services.httpd.virtualHosts =
+  <xref linkend="opt-services.httpd.virtualHosts"/> =
     let
       makeVirtualHost = { name, root }:
         { hostName = name;

nixos/doc/manual/configuration/ad-hoc-network-config.xml

@@ -6,14 +6,14 @@
 
 <title>Ad-Hoc Configuration</title>
 
-<para>You can use <option>networking.localCommands</option> to specify
+<para>You can use <xref linkend="opt-networking.localCommands"/> to specify
 shell commands to be run at the end of
 <literal>network-setup.service</literal>.  This is useful for doing
 network configuration not covered by the existing NixOS modules.  For
 instance, to statically configure an IPv6 address:
 
 <programlisting>
-networking.localCommands =
+<xref linkend="opt-networking.localCommands"/> =
   ''
     ip -6 addr add 2001:610:685:1::1/64 dev eth0
   '';

nixos/doc/manual/configuration/adding-custom-packages.xml

@@ -24,7 +24,7 @@ manual.  Finally, you add it to
 <literal>environment.systemPackages</literal>, e.g.
 
 <programlisting>
-environment.systemPackages = [ pkgs.my-package ];
+<xref linkend="opt-environment.systemPackages"/> = [ pkgs.my-package ];
 </programlisting>
 
 and you run <command>nixos-rebuild</command>, specifying your own
@@ -41,7 +41,7 @@ Nixpkgs tree.  For instance, here is how you specify a build of the
 package directly in <filename>configuration.nix</filename>:
 
 <programlisting>
-environment.systemPackages =
+<xref linkend="opt-environment.systemPackages"/> =
   let
     my-hello = with pkgs; stdenv.mkDerivation rec {
       name = "hello-2.8";
@@ -57,7 +57,7 @@ environment.systemPackages =
 Of course, you can also move the definition of
 <literal>my-hello</literal> into a separate Nix expression, e.g.
 <programlisting>
-environment.systemPackages = [ (import ./my-hello.nix) ];
+<xref linkend="opt-environment.systemPackages"/> = [ (import ./my-hello.nix) ];
 </programlisting>
 where <filename>my-hello.nix</filename> contains:
 <programlisting>

nixos/doc/manual/configuration/config-file.xml

@@ -28,9 +28,9 @@ form <literal><replaceable>name</replaceable> =
 <programlisting>
 { config, pkgs, ... }:
 
-{ services.httpd.enable = true;
-  services.httpd.adminAddr = "alice@example.org";
-  services.httpd.documentRoot = "/webroot";
+{ <xref linkend="opt-services.httpd.enable"/> = true;
+  <xref linkend="opt-services.httpd.adminAddr"/> = "alice@example.org";
+  <xref linkend="opt-services.httpd.documentRoot"/> = "/webroot";
 }
 </programlisting>
 
@@ -40,7 +40,7 @@ the document root.</para>
 
 <para>Sets can be nested, and in fact dots in option names are
 shorthand for defining a set containing another set.  For instance,
-<option>services.httpd.enable</option> defines a set named
+<xref linkend="opt-services.httpd.enable"/> defines a set named
 <varname>services</varname> that contains a set named
 <varname>httpd</varname>, which in turn contains an option definition
 named <varname>enable</varname> with value <literal>true</literal>.
@@ -89,7 +89,7 @@ The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is no
       <para>Strings are enclosed in double quotes, e.g.
 
 <programlisting>
-networking.hostName = "dexter";
+<xref linkend="opt-networking.hostName"/> = "dexter";
 </programlisting>
 
       Special characters can be escaped by prefixing them with a
@@ -99,7 +99,7 @@ networking.hostName = "dexter";
       single quotes</emphasis>, e.g.
 
 <programlisting>
-networking.extraHosts =
+<xref linkend="opt-networking.extraHosts"/> =
   ''
     127.0.0.2 other-localhost
     10.0.0.1 server
@@ -125,8 +125,8 @@ networking.extraHosts =
       <literal>false</literal>, e.g.
 
 <programlisting>
-networking.firewall.enable = true;
-networking.firewall.allowPing = false;
+<xref linkend="opt-networking.firewall.enable"/> = true;
+<xref linkend="opt-networking.firewall.allowPing"/> = false;
 </programlisting>
       </para>
     </listitem>
@@ -138,7 +138,7 @@ networking.firewall.allowPing = false;
       <para>For example,
 
 <programlisting>
-boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60;
+<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 60;
 </programlisting>
 
       (Note that here the attribute name
@@ -158,7 +158,7 @@ boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60;
       enclosed in braces, as in the option definition
 
 <programlisting>
-fileSystems."/boot" =
+<xref linkend="opt-fileSystems"/>."/boot" =
   { device = "/dev/sda1";
     fsType = "ext4";
     options = [ "rw" "data=ordered" "relatime" ];
@@ -175,7 +175,7 @@ fileSystems."/boot" =
       elements are separated by whitespace, like this:
 
 <programlisting>
-boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
+<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];
 </programlisting>
 
       List elements can be any other type, e.g. sets:
@@ -195,12 +195,12 @@ swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
       the function argument <varname>pkgs</varname>.  Typical uses:
 
 <programlisting>
-environment.systemPackages =
+<xref linkend="opt-environment.systemPackages"/> =
   [ pkgs.thunderbird
     pkgs.emacs
   ];
 
-postgresql.package = pkgs.postgresql90;
+<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql90;
 </programlisting>
 
       The latter option definition changes the default PostgreSQL

nixos/doc/manual/configuration/customizing-packages.xml

@@ -28,7 +28,7 @@ has a dependency on GTK+ 2.  If you want to build it against GTK+ 3,
 you can specify that as follows:
 
 <programlisting>
-environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
+<xref linkend="opt-environment.systemPackages"/> = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
 </programlisting>
 
 The function <varname>override</varname> performs the call to the Nix
@@ -38,7 +38,7 @@ the set of arguments specified by you.  So here the function argument
 causing Emacs to depend on GTK+ 3.  (The parentheses are necessary
 because in Nix, function application binds more weakly than list
 construction, so without them,
-<literal>environment.systemPackages</literal> would be a list with two
+<xref linkend="opt-environment.systemPackages"/> would be a list with two
 elements.)</para>
 
 <para>Even greater customisation is possible using the function
@@ -51,7 +51,7 @@ For instance, if you want to override the source code of Emacs, you
 can say:
 
 <programlisting>
-environment.systemPackages = [
+<xref linkend="opt-environment.systemPackages"/> = [
   (pkgs.emacs.overrideAttrs (oldAttrs: {
     name = "emacs-25.0-pre";
     src = /path/to/my/emacs/tree;

nixos/doc/manual/configuration/declarative-packages.xml

@@ -8,12 +8,12 @@
 
 <para>With declarative package management, you specify which packages
 you want on your system by setting the option
-<option>environment.systemPackages</option>.  For instance, adding the
+<xref linkend="opt-environment.systemPackages"/>.  For instance, adding the
 following line to <filename>configuration.nix</filename> enables the
 Mozilla Thunderbird email application:
 
 <programlisting>
-environment.systemPackages = [ pkgs.thunderbird ];
+<xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird ];
 </programlisting>
 
 The effect of this specification is that the Thunderbird package from
@@ -34,7 +34,7 @@ name</emphasis>, such as
 different channels that you might have.)</para>
 
 <para>To “uninstall” a package, simply remove it from
-<option>environment.systemPackages</option> and run
+<xref linkend="opt-environment.systemPackages"/> and run
 <command>nixos-rebuild switch</command>.</para>
 
 <xi:include href="customizing-packages.xml" />

nixos/doc/manual/configuration/file-systems.xml

@@ -13,21 +13,21 @@ device <filename>/dev/disk/by-label/data</filename> onto the mount
 point <filename>/data</filename>:
 
 <programlisting>
-fileSystems."/data" =
+<xref linkend="opt-fileSystems"/>."/data" =
   { device = "/dev/disk/by-label/data";
     fsType = "ext4";
   };
 </programlisting>
 
 Mount points are created automatically if they don’t already exist.
-For <option>device</option>, it’s best to use the topology-independent
+For <option><link linkend="opt-fileSystems._name__.device">device</link></option>, it’s best to use the topology-independent
 device aliases in <filename>/dev/disk/by-label</filename> and
 <filename>/dev/disk/by-uuid</filename>, as these don’t change if the
 topology changes (e.g. if a disk is moved to another IDE
 controller).</para>
 
 <para>You can usually omit the file system type
-(<option>fsType</option>), since <command>mount</command> can usually
+(<option><link linkend="opt-fileSystems._name__.fsType">fsType</link></option>), since <command>mount</command> can usually
 detect the type and load the necessary kernel module automatically.
 However, if the file system is needed at early boot (in the initial
 ramdisk) and is not <literal>ext2</literal>, <literal>ext3</literal>
@@ -38,7 +38,7 @@ available.</para>
 <note><para>System startup will fail if any of the filesystems fails to mount,
 dropping you to the emergency shell.
 You can make a mount asynchronous and non-critical by adding
-<literal>options = [ "nofail" ];</literal>.
+<literal><link linkend="opt-fileSystems._name__.options">options</link> = [ "nofail" ];</literal>.
 </para></note>
 
 <xi:include href="luks-file-systems.xml" />