Added cross-references to NixOS manual

19 files changed, 133 insertions, 133 deletions

diff --git a/nixos/doc/manual/configuration/abstractions.xml b/nixos/doc/manual/configuration/abstractions.xml
index cbd54bca62f..f794085295c 100644
--- a/nixos/doc/manual/configuration/abstractions.xml
+++ b/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;
diff --git a/nixos/doc/manual/configuration/ad-hoc-network-config.xml b/nixos/doc/manual/configuration/ad-hoc-network-config.xml
index 26a572ba1fb..c53b9598109 100644
--- a/nixos/doc/manual/configuration/ad-hoc-network-config.xml
+++ b/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
   '';
diff --git a/nixos/doc/manual/configuration/adding-custom-packages.xml b/nixos/doc/manual/configuration/adding-custom-packages.xml
index ab3665bae50..ae58f61d73e 100644
--- a/nixos/doc/manual/configuration/adding-custom-packages.xml
+++ b/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>
diff --git a/nixos/doc/manual/configuration/config-file.xml b/nixos/doc/manual/configuration/config-file.xml
index 3d1cdaf4c4a..60a4dac97d5 100644
--- a/nixos/doc/manual/configuration/config-file.xml
+++ b/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
diff --git a/nixos/doc/manual/configuration/customizing-packages.xml b/nixos/doc/manual/configuration/customizing-packages.xml
index 8aa01fb57a0..8b7654e9b42 100644
--- a/nixos/doc/manual/configuration/customizing-packages.xml
+++ b/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;
diff --git a/nixos/doc/manual/configuration/declarative-packages.xml b/nixos/doc/manual/configuration/declarative-packages.xml
index dc2fa715097..4c875e6f037 100644
--- a/nixos/doc/manual/configuration/declarative-packages.xml
+++ b/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" />
diff --git a/nixos/doc/manual/configuration/file-systems.xml b/nixos/doc/manual/configuration/file-systems.xml
index ae3d124cd6b..0ff37c38d8b 100644
--- a/nixos/doc/manual/configuration/file-systems.xml
+++ b/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" />
diff --git a/nixos/doc/manual/configuration/firewall.xml b/nixos/doc/manual/configuration/firewall.xml
index 75cccef95b3..ecc21a3bdf5 100644
--- a/nixos/doc/manual/configuration/firewall.xml
+++ b/nixos/doc/manual/configuration/firewall.xml
@@ -12,37 +12,37 @@ both IPv4 and IPv6 traffic. It is enabled by default. It can be
 disabled as follows:
 
 <programlisting>
-networking.firewall.enable = false;
+<xref linkend="opt-networking.firewall.enable"/> = false;
 </programlisting>
 
 If the firewall is enabled, you can open specific TCP ports to the
 outside world:
 
 <programlisting>
-networking.firewall.allowedTCPPorts = [ 80 443 ];
+<xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 443 ];
 </programlisting>
 
 Note that TCP port 22 (ssh) is opened automatically if the SSH daemon
-is enabled (<option>services.openssh.enable = true</option>). UDP
+is enabled (<option><xref linkend="opt-services.openssh.enable"/> = true</option>). UDP
 ports can be opened through
-<option>networking.firewall.allowedUDPPorts</option>.</para>
+<xref linkend="opt-networking.firewall.allowedUDPPorts"/>.</para>
 
 <para>To open ranges of TCP ports:
 
 <programlisting>
-networking.firewall.allowedTCPPortRanges = [
+<xref linkend="opt-networking.firewall.allowedTCPPortRanges"/> = [
   { from = 4000; to = 4007; }
   { from = 8000; to = 8010; }
 ];
 </programlisting>
 
 Similarly, UDP port ranges can be opened through
-<option>networking.firewall.allowedUDPPortRanges</option>.</para>
+<xref linkend="opt-networking.firewall.allowedUDPPortRanges"/>.</para>
 
 <para>Also of interest is
 
 <programlisting>
-networking.firewall.allowPing = true;
+<xref linkend="opt-networking.firewall.allowPing"/> = true;
 </programlisting>
 
 to allow the machine to respond to ping requests.  (ICMPv6 pings are
diff --git a/nixos/doc/manual/configuration/ipv4-config.xml b/nixos/doc/manual/configuration/ipv4-config.xml
index 68238b547d6..f3ce4af39b9 100644
--- a/nixos/doc/manual/configuration/ipv4-config.xml
+++ b/nixos/doc/manual/configuration/ipv4-config.xml
@@ -12,15 +12,15 @@ interfaces.  However, you can configure an interface manually as
 follows:
 
 <programlisting>
-networking.interfaces.eth0.ipv4.addresses = [ { address = "192.168.1.2"; prefixLength = 24; } ];
+<link linkend="opt-networking.interfaces._name__.ipv4.addresses">networking.interfaces.eth0.ipv4.addresses</link> = [ { address = "192.168.1.2"; prefixLength = 24; } ];
 </programlisting>
 
 Typically you’ll also want to set a default gateway and set of name
 servers:
 
 <programlisting>
-networking.defaultGateway = "192.168.1.1";
-networking.nameservers = [ "8.8.8.8" ];
+<xref linkend="opt-networking.defaultGateway"/> = "192.168.1.1";
+<xref linkend="opt-networking.nameservers"/> = [ "8.8.8.8" ];
 </programlisting>
 
 </para>
@@ -31,10 +31,10 @@ service
 The default gateway and name server configuration is performed by
 <literal>network-setup.service</literal>.</para></note>
 
-<para>The host name is set using <option>networking.hostName</option>:
+<para>The host name is set using <xref linkend="opt-networking.hostName"/>:
 
 <programlisting>
-networking.hostName = "cartman";
+<xref linkend="opt-networking.hostName"/> = "cartman";
 </programlisting>
 
 The default host name is <literal>nixos</literal>.  Set it to the
diff --git a/nixos/doc/manual/configuration/ipv6-config.xml b/nixos/doc/manual/configuration/ipv6-config.xml
index 74a21e18ec3..6b0ba0d48f0 100644
--- a/nixos/doc/manual/configuration/ipv6-config.xml
+++ b/nixos/doc/manual/configuration/ipv6-config.xml
@@ -11,14 +11,14 @@ is used to automatically assign IPv6 addresses to all interfaces.  You
 can disable IPv6 support globally by setting:
 
 <programlisting>
-networking.enableIPv6 = false;
+<xref linkend="opt-networking.enableIPv6"/> = false;
 </programlisting></para>
 
 <para>You can disable IPv6 on a single interface using a normal sysctl (in this
 example, we use interface <varname>eth0</varname>):
 
 <programlisting>
-boot.kernel.sysctl."net.ipv6.conf.eth0.disable_ipv6" = true;
+<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv6.conf.eth0.disable_ipv6" = true;
 </programlisting>
 </para>
 
@@ -26,14 +26,14 @@ boot.kernel.sysctl."net.ipv6.conf.eth0.disable_ipv6" = true;
 DHCPv6. You can configure an interface manually:
 
 <programlisting>
-networking.interfaces.eth0.ipv6.addresses = [ { address = "fe00:aa:bb:cc::2"; prefixLength = 64; } ];
+<link linkend="opt-networking.interfaces._name__.ipv6.addresses">networking.interfaces.eth0.ipv6.addresses</link> = [ { address = "fe00:aa:bb:cc::2"; prefixLength = 64; } ];
 </programlisting>
 </para>
 
 <para>For configuring a gateway, optionally with explicitly specified interface:
 
 <programlisting>
-networking.defaultGateway6 = {
+<xref linkend="opt-networking.defaultGateway6"/> = {
   address = "fe00::1";
   interface = "enp0s3";
 }
diff --git a/nixos/doc/manual/configuration/linux-kernel.xml b/nixos/doc/manual/configuration/linux-kernel.xml
index 52be26d6024..b9325629256 100644
--- a/nixos/doc/manual/configuration/linux-kernel.xml
+++ b/nixos/doc/manual/configuration/linux-kernel.xml
@@ -10,7 +10,7 @@
 the option <option>boot.kernelPackages</option>.  For instance, this
 selects the Linux 3.10 kernel:
 <programlisting>
-boot.kernelPackages = pkgs.linuxPackages_3_10;
+<xref linkend="opt-boot.kernelPackages"/> = pkgs.linuxPackages_3_10;
 </programlisting>
 Note that this not only replaces the kernel, but also packages that
 are specific to the kernel version, such as the NVIDIA video drivers.
@@ -45,23 +45,23 @@ is typically <literal>y</literal>, <literal>n</literal> or
 
 <para>Kernel modules for hardware devices are generally loaded
 automatically by <command>udev</command>.  You can force a module to
-be loaded via <option>boot.kernelModules</option>, e.g.
+be loaded via <xref linkend="opt-boot.kernelModules"/>, e.g.
 <programlisting>
-boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
+<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];
 </programlisting>
 If the module is required early during the boot (e.g. to mount the
 root file system), you can use
-<option>boot.initrd.extraKernelModules</option>:
+<xref linkend="opt-boot.initrd.extraKernelModules"/>:
 <programlisting>
-boot.initrd.extraKernelModules = [ "cifs" ];
+<xref linkend="opt-boot.initrd.extraKernelModules"/> = [ "cifs" ];
 </programlisting>
 This causes the specified modules and their dependencies to be added
 to the initial ramdisk.</para>
 
 <para>Kernel runtime parameters can be set through
-<option>boot.kernel.sysctl</option>, e.g.
+<xref linkend="opt-boot.kernel.sysctl"/>, e.g.
 <programlisting>
-boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120;
+<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 120;
 </programlisting>
 sets the kernel’s TCP keepalive time to 120 seconds.  To see the
 available parameters, run <command>sysctl -a</command>.</para>
diff --git a/nixos/doc/manual/configuration/luks-file-systems.xml b/nixos/doc/manual/configuration/luks-file-systems.xml
index 00c795cd089..6c2b4cc60b5 100644
--- a/nixos/doc/manual/configuration/luks-file-systems.xml
+++ b/nixos/doc/manual/configuration/luks-file-systems.xml
@@ -33,13 +33,13 @@ as <filename>/</filename>, add the following to
 <filename>configuration.nix</filename>:
 
 <programlisting>
-boot.initrd.luks.devices.crypted.device = "/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d";
-fileSystems."/".device = "/dev/mapper/crypted";
+<link linkend="opt-boot.initrd.luks.devices._name__.device">boot.initrd.luks.devices.crypted.device</link> = "/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d";
+<xref linkend="opt-fileSystems"/>."/".device = "/dev/mapper/crypted";
 </programlisting>
 
 Should grub be used as bootloader, and <filename>/boot</filename> is located
 on an encrypted partition, it is necessary to add the following grub option:
-<programlisting>boot.loader.grub.enableCryptodisk = true;</programlisting>
+<programlisting><xref linkend="opt-boot.loader.grub.enableCryptodisk"/> = true;</programlisting>
 
 </para>
 
diff --git a/nixos/doc/manual/configuration/modularity.xml b/nixos/doc/manual/configuration/modularity.xml
index 5420c7f8838..2f76459a24e 100644
--- a/nixos/doc/manual/configuration/modularity.xml
+++ b/nixos/doc/manual/configuration/modularity.xml
@@ -22,8 +22,8 @@ use other modules by including them from
 { config, pkgs, ... }:
 
 { imports = [ ./vpn.nix ./kde.nix ];
-  services.httpd.enable = true;
-  environment.systemPackages = [ pkgs.emacs ];
+  <xref linkend="opt-services.httpd.enable"/> = true;
+  <xref linkend="opt-environment.systemPackages"/> = [ pkgs.emacs ];
   <replaceable>...</replaceable>
 }
 </programlisting>
@@ -35,25 +35,25 @@ latter might look like this:
 <programlisting>
 { config, pkgs, ... }:
 
-{ services.xserver.enable = true;
-  services.xserver.displayManager.sddm.enable = true;
-  services.xserver.desktopManager.plasma5.enable = true;
+{ <xref linkend="opt-services.xserver.enable"/> = true;
+  <xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true;
+  <xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true;
 }
 </programlisting>
 
 Note that both <filename>configuration.nix</filename> and
 <filename>kde.nix</filename> define the option
-<option>environment.systemPackages</option>.  When multiple modules
+<xref linkend="opt-environment.systemPackages"/>.  When multiple modules
 define an option, NixOS will try to <emphasis>merge</emphasis> the
 definitions.  In the case of
-<option>environment.systemPackages</option>, that’s easy: the lists of
+<xref linkend="opt-environment.systemPackages"/>, that’s easy: the lists of
 packages can simply be concatenated.  The value in
 <filename>configuration.nix</filename> is merged last, so for
 list-type options, it will appear at the end of the merged list. If
 you want it to appear first, you can use <varname>mkBefore</varname>:
 
 <programlisting>
-boot.kernelModules = mkBefore [ "kvm-intel" ];
+<xref linkend="opt-boot.kernelModules"/> = mkBefore [ "kvm-intel" ];
 </programlisting>
 
 This causes the <literal>kvm-intel</literal> kernel module to be
@@ -61,7 +61,7 @@ loaded before any other kernel modules.</para>
 
 <para>For other types of options, a merge may not be possible. For
 instance, if two modules define
-<option>services.httpd.adminAddr</option>,
+<xref linkend="opt-services.httpd.adminAddr"/>,
 <command>nixos-rebuild</command> will give an error:
 
 <screen>
@@ -72,7 +72,7 @@ When that happens, it’s possible to force one definition take
 precedence over the others:
 
 <programlisting>
-services.httpd.adminAddr = pkgs.lib.mkForce "bob@example.org";
+<xref linkend="opt-services.httpd.adminAddr"/> = pkgs.lib.mkForce "bob@example.org";
 </programlisting>
 
 </para>
@@ -89,15 +89,15 @@ wondering how it’s possible that the (indirect)
 is a “lazy” language — it only computes values when they are needed.
 This works as long as no individual configuration value depends on
 itself.</para></footnote>.  For example, here is a module that adds
-some packages to <option>environment.systemPackages</option> only if
-<option>services.xserver.enable</option> is set to
+some packages to <xref linkend="opt-environment.systemPackages"/> only if
+<xref linkend="opt-services.xserver.enable"/> is set to
 <literal>true</literal> somewhere else:
 
 <programlisting>
 { config, pkgs, ... }:
 
-{ environment.systemPackages =
-    if config.services.xserver.enable then
+{ <xref linkend="opt-environment.systemPackages"/> =
+    if config.<xref linkend="opt-services.xserver.enable"/> then
       [ pkgs.firefox
         pkgs.thunderbird
       ]
@@ -113,10 +113,10 @@ value of a configuration option is.  The command
 <option>nixos-option</option> allows you to find out:
 
 <screen>
-$ nixos-option services.xserver.enable
+$ nixos-option <xref linkend="opt-services.xserver.enable"/>
 true
 
-$ nixos-option boot.kernelModules
+$ nixos-option <xref linkend="opt-boot.kernelModules"/>
 [ "tun" "ipv6" "loop" <replaceable>...</replaceable> ]
 </screen>
 
@@ -130,10 +130,10 @@ typical use:
 <screen>
 $ nix-repl '&lt;nixpkgs/nixos>'
 
-nix-repl> config.networking.hostName
+nix-repl> config.<xref linkend="opt-networking.hostName"/>
 "mandark"
 
-nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts
+nix-repl> map (x: x.hostName) config.<xref linkend="opt-services.httpd.virtualHosts"/>
 [ "example.org" "example.gov" ]
 </screen>
 
diff --git a/nixos/doc/manual/configuration/network-manager.xml b/nixos/doc/manual/configuration/network-manager.xml
index b4808e74ff9..bbbee3a52ed 100644
--- a/nixos/doc/manual/configuration/network-manager.xml
+++ b/nixos/doc/manual/configuration/network-manager.xml
@@ -10,7 +10,7 @@
 use NetworkManager. You can enable NetworkManager by setting:
 
 <programlisting>
-networking.networkmanager.enable = true;
+<xref linkend="opt-networking.networkmanager.enable"/> = true;
 </programlisting>
 
 some desktop managers (e.g., GNOME) enable NetworkManager
@@ -20,7 +20,7 @@ automatically for you.</para>
 belong to the <code>networkmanager</code> group:
 
 <programlisting>
-users.extraUsers.youruser.extraGroups = [ "networkmanager" ];
+<link linkend="opt-users.users._name__.extraGroups">users.extraUsers.youruser.extraGroups</link> = [ "networkmanager" ];
 </programlisting>
 </para>
 
diff --git a/nixos/doc/manual/configuration/ssh.xml b/nixos/doc/manual/configuration/ssh.xml
index 7c928baaf89..7dbe598cffe 100644
--- a/nixos/doc/manual/configuration/ssh.xml
+++ b/nixos/doc/manual/configuration/ssh.xml
@@ -10,12 +10,12 @@
 setting:
 
 <programlisting>
-services.openssh.enable = true;
+<xref linkend="opt-services.openssh.enable"/> = true;
 </programlisting>
 
 By default, root logins using a password are disallowed.  They can be
 disabled entirely by setting
-<literal>services.openssh.permitRootLogin</literal> to
+<xref linkend="opt-services.openssh.permitRootLogin"/> to
 <literal>"no"</literal>.</para>
 
 <para>You can declaratively specify authorised RSA/DSA public keys for
@@ -23,7 +23,7 @@ a user as follows:
 
 <!-- FIXME: this might not work if the user is unmanaged. -->
 <programlisting>
-users.extraUsers.alice.openssh.authorizedKeys.keys =
+<link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.extraUsers.alice.openssh.authorizedKeys.keys</link> =
   [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];
 </programlisting>
 
diff --git a/nixos/doc/manual/configuration/user-mgmt.xml b/nixos/doc/manual/configuration/user-mgmt.xml
index c6656edff6c..848b221baa7 100644
--- a/nixos/doc/manual/configuration/user-mgmt.xml
+++ b/nixos/doc/manual/configuration/user-mgmt.xml
@@ -12,12 +12,12 @@ management.  In the declarative style, users are specified in
 states that a user account named <literal>alice</literal> shall exist:
 
 <programlisting>
-users.users.alice =
-  { isNormalUser = true;
-    home = "/home/alice";
-    description = "Alice Foobar";
-    extraGroups = [ "wheel" "networkmanager" ];
-    openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ];
+<xref linkend="opt-users.users"/>.alice =
+  { <link linkend="opt-users.users._name__.isNormalUser">isNormalUser</link> = true;
+    <link linkend="opt-users.users._name__.home">home</link> = "/home/alice";
+    <link linkend="opt-users.users._name__.description">description</link> = "Alice Foobar";
+    <link linkend="opt-users.users._name__.extraGroups">extraGroups</link> = [ "wheel" "networkmanager" ];
+    <link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">openssh.authorizedKeys.keys</link> = [ "ssh-dss AAAAB3Nza... alice@foobar" ];
   };
 </programlisting>
 
@@ -32,13 +32,13 @@ a password. However, you can use the <command>passwd</command> program
 to set a password, which is retained across invocations of
 <command>nixos-rebuild</command>.</para>
 
-<para>If you set users.mutableUsers to false, then the contents of /etc/passwd
-and /etc/group will be congruent to your NixOS configuration. For instance,
-if you remove a user from users.users and run nixos-rebuild, the user
-account will cease to exist. Also, imperative commands for managing users
+<para>If you set <xref linkend="opt-users.mutableUsers"/> to false, then the contents of
+<literal>/etc/passwd</literal> and <literal>/etc/group</literal> will be congruent to
+your NixOS configuration. For instance, if you remove a user from <xref linkend="opt-users.users"/>
+and run nixos-rebuild, the user account will cease to exist. Also, imperative commands for managing users
 and groups, such as useradd, are no longer available. Passwords may still be
-assigned by setting the user's <literal>hashedPassword</literal> option. A
-hashed password can be generated using <command>mkpasswd -m sha-512</command>
+assigned by setting the user's <link linkend="opt-users.users._name__.hashedPassword">hashedPassword</link>
+option. A hashed password can be generated using <command>mkpasswd -m sha-512</command>
 after installing the <literal>mkpasswd</literal> package.</para>
 
 <para>A user ID (uid) is assigned automatically.  You can also specify
@@ -54,7 +54,7 @@ to the user specification.</para>
 group named <literal>students</literal> shall exist:
 
 <programlisting>
-users.groups.students.gid = 1000;
+<xref linkend="opt-users.groups"/>.students.gid = 1000;
 </programlisting>
 
 As with users, the group ID (gid) is optional and will be assigned
diff --git a/nixos/doc/manual/configuration/wireless.xml b/nixos/doc/manual/configuration/wireless.xml
index 1868380dcbf..6ce43a43700 100644
--- a/nixos/doc/manual/configuration/wireless.xml
+++ b/nixos/doc/manual/configuration/wireless.xml
@@ -15,12 +15,12 @@ section on wireless networks.</para>
 NixOS will start wpa_supplicant for you if you enable this setting:
 
 <programlisting>
-networking.wireless.enable = true;
+<xref linkend="opt-networking.wireless.enable"/> = true;
 </programlisting>
 
 NixOS lets you specify networks for wpa_supplicant declaratively:
 <programlisting>
-networking.wireless.networks = {
+<xref linkend="opt-networking.wireless.networks"/> = {
   echelon = {
     psk = "abcdefgh";
   };
diff --git a/nixos/doc/manual/configuration/x-windows.xml b/nixos/doc/manual/configuration/x-windows.xml
index 9c2c59006f1..fd0daf6c6e5 100644
--- a/nixos/doc/manual/configuration/x-windows.xml
+++ b/nixos/doc/manual/configuration/x-windows.xml
@@ -9,14 +9,14 @@
 <para>The X Window System (X11) provides the basis of NixOS’ graphical
 user interface.  It can be enabled as follows:
 <programlisting>
-services.xserver.enable = true;
+<xref linkend="opt-services.xserver.enable"/> = true;
 </programlisting>
 The X server will automatically detect and use the appropriate video
 driver from a set of X.org drivers (such as <literal>vesa</literal>
 and <literal>intel</literal>).  You can also specify a driver
 manually, e.g.
 <programlisting>
-services.xserver.videoDrivers = [ "r128" ];
+<xref linkend="opt-services.xserver.videoDrivers"/> = [ "r128" ];
 </programlisting>
 to enable X.org’s <literal>xf86-video-r128</literal> driver.</para>
 
@@ -25,13 +25,13 @@ Otherwise, you can only log into a plain undecorated
 <command>xterm</command> window.  Thus you should pick one or more of
 the following lines:
 <programlisting>
-services.xserver.desktopManager.plasma5.enable = true;
-services.xserver.desktopManager.xfce.enable = true;
-services.xserver.desktopManager.gnome3.enable = true;
-services.xserver.windowManager.xmonad.enable = true;
-services.xserver.windowManager.twm.enable = true;
-services.xserver.windowManager.icewm.enable = true;
-services.xserver.windowManager.i3.enable = true;
+<xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true;
+<xref linkend="opt-services.xserver.desktopManager.xfce.enable"/> = true;
+<xref linkend="opt-services.xserver.desktopManager.gnome3.enable"/> = true;
+<xref linkend="opt-services.xserver.windowManager.xmonad.enable"/> = true;
+<xref linkend="opt-services.xserver.windowManager.twm.enable"/> = true;
+<xref linkend="opt-services.xserver.windowManager.icewm.enable"/> = true;
+<xref linkend="opt-services.xserver.windowManager.i3.enable"/> = true;
 </programlisting>
 </para>
 
@@ -40,22 +40,22 @@ program that provides a graphical login prompt and manages the X
 server) is SLiM. You can select an alternative one by picking one
 of the following lines:
 <programlisting>
-services.xserver.displayManager.sddm.enable = true;
-services.xserver.displayManager.lightdm.enable = true;
+<xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true;
+<xref linkend="opt-services.xserver.displayManager.lightdm.enable"/> = true;
 </programlisting>
 </para>
 
 <para>You can set the keyboard layout (and optionally the layout variant):
 <programlisting>
-services.xserver.layout = "de";
-services.xserver.xkbVariant = "neo";
+<xref linkend="opt-services.xserver.layout"/> = "de";
+<xref linkend="opt-services.xserver.xkbVariant"/> = "neo";
 </programlisting>
 </para>
 
 <para>The X server is started automatically at boot time.  If you
 don’t want this to happen, you can set:
 <programlisting>
-services.xserver.autorun = false;
+<xref linkend="opt-services.xserver.autorun"/> = false;
 </programlisting>
 The X server can then be started manually:
 <screen>
@@ -70,13 +70,13 @@ The X server can then be started manually:
 has better 3D performance than the X.org drivers.  It is not enabled
 by default because it’s not free software.  You can enable it as follows:
 <programlisting>
-services.xserver.videoDrivers = [ "nvidia" ];
+<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidia" ];
 </programlisting>
 Or if you have an older card, you may have to use one of the legacy drivers:
 <programlisting>
-services.xserver.videoDrivers = [ "nvidiaLegacy340" ];
-services.xserver.videoDrivers = [ "nvidiaLegacy304" ];
-services.xserver.videoDrivers = [ "nvidiaLegacy173" ];
+<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy340" ];
+<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy304" ];
+<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy173" ];
 </programlisting>
 You may need to reboot after enabling this driver to prevent a clash
 with other kernel modules.</para>
@@ -84,7 +84,7 @@ with other kernel modules.</para>
 <para>On 64-bit systems, if you want full acceleration for 32-bit
 programs such as Wine, you should also set the following:
 <programlisting>
-hardware.opengl.driSupport32Bit = true;
+<xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true;
 </programlisting>
 </para>
 
@@ -96,7 +96,7 @@ hardware.opengl.driSupport32Bit = true;
 has better 3D performance than the X.org drivers.  It is not enabled
 by default because it’s not free software.  You can enable it as follows:
 <programlisting>
-services.xserver.videoDrivers = [ "ati_unfree" ];
+<xref linkend="opt-services.xserver.videoDrivers"/> = [ "ati_unfree" ];
 </programlisting>
 You will need to reboot after enabling this driver to prevent a clash
 with other kernel modules.</para>
@@ -104,7 +104,7 @@ with other kernel modules.</para>
 <para>On 64-bit systems, if you want full acceleration for 32-bit
 programs such as Wine, you should also set the following:
 <programlisting>
-hardware.opengl.driSupport32Bit = true;
+<xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true;
 </programlisting>
 </para>
 
@@ -115,12 +115,12 @@ hardware.opengl.driSupport32Bit = true;
 <para>Support for Synaptics touchpads (found in many laptops such as
 the Dell Latitude series) can be enabled as follows:
 <programlisting>
-services.xserver.libinput.enable = true;
+<xref linkend="opt-services.xserver.libinput.enable"/> = true;
 </programlisting>
 The driver has many options (see <xref linkend="ch-options"/>).  For
 instance, the following disables tap-to-click behavior:
 <programlisting>
-services.xserver.libinput.tapping = false;
+<xref linkend="opt-services.xserver.libinput.tapping"/> = false;
 </programlisting>
 Note: the use of <literal>services.xserver.synaptics</literal> is deprecated since NixOS 17.09.
 </para>
diff --git a/nixos/doc/manual/configuration/xfce.xml b/nixos/doc/manual/configuration/xfce.xml
index 18804d2c08b..8cb592faed5 100644
--- a/nixos/doc/manual/configuration/xfce.xml
+++ b/nixos/doc/manual/configuration/xfce.xml
@@ -9,9 +9,9 @@
     <para>
         To enable the Xfce Desktop Environment, set
         <programlisting>
-services.xserver.desktopManager = {
-    xfce.enable = true;
-    default = "xfce";
+<link linkend="opt-services.xserver.desktopManager.default">services.xserver.desktopManager</link> = {
+  <link linkend="opt-services.xserver.desktopManager.xfce.enable">xfce.enable</link> = true;
+  <link linkend="opt-services.xserver.desktopManager.default">default</link> = "xfce";
 };
         </programlisting>
     </para>
@@ -20,12 +20,12 @@ services.xserver.desktopManager = {
         Optionally, <emphasis>compton</emphasis>
         can be enabled for nice graphical effects, some example settings:
         <programlisting>
-services.compton = {
-  enable          = true;
-  fade            = true;
-  inactiveOpacity = "0.9";
-  shadow          = true;
-  fadeDelta       = 4;
+<link linkend="opt-services.compton.enable">services.compton</link> = {
+  <link linkend="opt-services.compton.enable">enable</link>          = true;
+  <link linkend="opt-services.compton.fade">fade</link>            = true;
+  <link linkend="opt-services.compton.inactiveOpacity">inactiveOpacity</link> = "0.9";
+  <link linkend="opt-services.compton.shadow">shadow</link>          = true;
+  <link linkend="opt-services.compton.fadeDelta">fadeDelta</link>       = 4;
 };
         </programlisting>
     </para>
@@ -33,9 +33,9 @@ services.compton = {
     <para>
         Some Xfce programs are not installed automatically.
         To install them manually (system wide), put them into your
-        <literal>environment.systemPackages</literal>.
+        <xref linkend="opt-environment.systemPackages"/>.
     </para>
-         
+
     <simplesect>
         <title>Thunar Volume Support</title>
 
@@ -44,7 +44,7 @@ services.compton = {
             <emphasis>Thunar</emphasis>
             volume support, put
             <programlisting>
-services.xserver.desktopManager.xfce.enable = true;
+<xref linkend="opt-services.xserver.desktopManager.xfce.enable"/> = true;
             </programlisting>
             into your <emphasis>configuration.nix</emphasis>.
         </para>