Added cross-references to NixOS manual

39 files changed, 340 insertions, 338 deletions

diff --git a/nixos/doc/manual/administration/cleaning-store.xml b/nixos/doc/manual/administration/cleaning-store.xml
index 4cf62947f52..52512b8f127 100644
--- a/nixos/doc/manual/administration/cleaning-store.xml
+++ b/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>
diff --git a/nixos/doc/manual/administration/container-networking.xml b/nixos/doc/manual/administration/container-networking.xml
index d89d262eff4..2fc353059df 100644
--- a/nixos/doc/manual/administration/container-networking.xml
+++ b/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
diff --git a/nixos/doc/manual/administration/control-groups.xml b/nixos/doc/manual/administration/control-groups.xml
index 0d7b8ae910a..03db40a3bc5 100644
--- a/nixos/doc/manual/administration/control-groups.xml
+++ b/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>
diff --git a/nixos/doc/manual/administration/declarative-containers.xml b/nixos/doc/manual/administration/declarative-containers.xml
index 94f03a2ee11..79b230e5fc7 100644
--- a/nixos/doc/manual/administration/declarative-containers.xml
+++ b/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
diff --git a/nixos/doc/manual/administration/imperative-containers.xml b/nixos/doc/manual/administration/imperative-containers.xml
index d5d8140e076..d39ac7f8bef 100644
--- a/nixos/doc/manual/administration/imperative-containers.xml
+++ b/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)/
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>
diff --git a/nixos/doc/manual/installation/changing-config.xml b/nixos/doc/manual/installation/changing-config.xml
index 4db9020b960..52d8a292f8b 100644
--- a/nixos/doc/manual/installation/changing-config.xml
+++ b/nixos/doc/manual/installation/changing-config.xml
@@ -75,7 +75,7 @@ have set <literal>mutableUsers = false</literal>.  Another way is to
 temporarily add the following to your configuration:
 
 <screen>
-users.extraUsers.your-user.initialPassword = "test"  
+<link linkend="opt-users.users._name__.initialHashedPassword">users.extraUsers.your-user.initialHashedPassword</link> = "test";
 </screen>
 
 <emphasis>Important:</emphasis> delete the $hostname.qcow2 file if you
diff --git a/nixos/doc/manual/installation/installing-from-other-distro.xml b/nixos/doc/manual/installation/installing-from-other-distro.xml
index ecd020a067a..11fcb43732a 100644
--- a/nixos/doc/manual/installation/installing-from-other-distro.xml
+++ b/nixos/doc/manual/installation/installing-from-other-distro.xml
@@ -111,7 +111,7 @@ $ nix-channel --add https://nixos.org/channels/nixos-<replaceable>version</repla
                 <literal>configuration.nix</literal>:</para>
 
             <programlisting>
-boot.loader.grub.extraEntries = ''
+<xref linkend="opt-boot.loader.grub.extraEntries"/> = ''
   menuentry "Ubuntu" {
     search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e
     configfile "($ubuntu)/boot/grub/grub.cfg"
@@ -183,7 +183,7 @@ $ sudo groupdel nixbld</screen>
                 account with <literal>sudo passwd -l root</literal> if you use
                 <literal>sudo</literal>)</para>
 
-            <programlisting>users.extraUsers.root.initialHashedPassword = "";</programlisting>
+              <programlisting><link linkend="opt-users.users._name__.initialHashedPassword">users.extraUsers.root.initialHashedPassword</link> = "";</programlisting>
         </listitem>
 
         <listitem>
diff --git a/nixos/doc/manual/installation/installing-virtualbox-guest.xml b/nixos/doc/manual/installation/installing-virtualbox-guest.xml
index 7fcd22a112c..2b31b7ed315 100644
--- a/nixos/doc/manual/installation/installing-virtualbox-guest.xml
+++ b/nixos/doc/manual/installation/installing-virtualbox-guest.xml
@@ -42,7 +42,7 @@
 </para>
 
 <programlisting>
-boot.loader.grub.device = "/dev/sda";
+<xref linkend="opt-boot.loader.grub.device"/> = "/dev/sda";
 </programlisting>
 
 <para>
@@ -51,7 +51,7 @@ boot.loader.grub.device = "/dev/sda";
 </para>
 
 <programlisting>
-boot.initrd.checkJournalingFS = false;
+<xref linkend="opt-boot.initrd.checkJournalingFS"/> = false;
 </programlisting>
 
 <para>
diff --git a/nixos/doc/manual/installation/installing.xml b/nixos/doc/manual/installation/installing.xml
index e20b6574b72..f967a7fe268 100644
--- a/nixos/doc/manual/installation/installing.xml
+++ b/nixos/doc/manual/installation/installing.xml
@@ -208,26 +208,29 @@ for a UEFI installation is by and large the same as a BIOS installation. The dif
     <variablelist>
 
       <varlistentry><term>BIOS systems</term>
-      <listitem><para>You <emphasis>must</emphasis> set the option
-    <option>boot.loader.grub.device</option> to specify on which disk
-    the GRUB boot loader is to be installed.  Without it, NixOS cannot
-      boot.</para></listitem></varlistentry>
+        <listitem><para>You <emphasis>must</emphasis> set the option
+            <xref linkend="opt-boot.loader.grub.device"/> to specify on which disk
+            the GRUB boot loader is to be installed.  Without it, NixOS cannot
+            boot.</para></listitem></varlistentry>
 
       <varlistentry><term>UEFI systems</term>
-      <listitem><para>You <emphasis>must</emphasis> set the option
-      <option>boot.loader.systemd-boot.enable</option> to <literal>true</literal>.
-      <command>nixos-generate-config</command> should do this automatically for new
-      configurations when booted in
-      UEFI mode.</para>
-      <para>You may want to look at the options starting with
-      <option>boot.loader.efi</option> and <option>boot.loader.systemd-boot</option>
-      as well.</para></listitem></varlistentry>
+        <listitem><para>You <emphasis>must</emphasis> set the option
+            <xref linkend="opt-boot.loader.systemd-boot.enable"/> to <literal>true</literal>.
+            <command>nixos-generate-config</command> should do this automatically for new
+            configurations when booted in
+            UEFI mode.</para>
+          <para>You may want to look at the options starting with
+            <option><link linkend="opt-boot.loader.efi.canTouchEfiVariables">boot.loader.efi</link></option> and
+            <option><link linkend="opt-boot.loader.systemd-boot.enable">boot.loader.systemd</link></option> as well.
+          </para>
+        </listitem>
+      </varlistentry>
 
     </variablelist>
 
     <para>If there are other operating systems running on the machine before
     installing NixOS, the
-    <option>boot.loader.grub.useOSProber</option> option can be set to
+    <xref linkend="opt-boot.loader.grub.useOSProber"/> option can be set to
     <literal>true</literal> to automatically add them to the grub menu.</para>
 
     <para>Another critical option is <option>fileSystems</option>,
@@ -269,15 +272,15 @@ for a UEFI installation is by and large the same as a BIOS installation. The dif
     <para>As the last step, <command>nixos-install</command> will ask
     you to set the password for the <literal>root</literal> user, e.g.
 
-<screen>
-setting root password...
-Enter new UNIX password: ***
-Retype new UNIX password: ***
-</screen>
+    <screen>
+      setting root password...
+      Enter new UNIX password: ***
+      Retype new UNIX password: ***
+    </screen>
 
     <note>
       <para>
-        To prevent the password prompt, set <code>users.mutableUsers = false;</code> in
+        To prevent the password prompt, set <code><xref linkend="opt-users.mutableUsers"/> = false;</code> in
         <filename>configuration.nix</filename>, which allows unattended installation
         necessary in automation.
       </para>
@@ -290,20 +293,20 @@ Retype new UNIX password: ***
   <listitem>
     <para>If everything went well:
 
-<screen>
-# reboot</screen>
+      <screen>
+        # reboot</screen>
 
   </para></listitem>
 
   <listitem>
 
     <para>You should now be able to boot into the installed NixOS. The
-    GRUB boot menu shows a list of <emphasis>available
-    configurations</emphasis> (initially just one). Every time you
-    change the NixOS configuration (see <link
-    linkend="sec-changing-config">Changing Configuration</link> ), a
-    new item is added to the menu. This allows you to easily roll back
-    to a previous configuration if something goes wrong.</para>
+      GRUB boot menu shows a list of <emphasis>available
+        configurations</emphasis> (initially just one). Every time you
+      change the NixOS configuration (see <link
+        linkend="sec-changing-config">Changing Configuration</link> ), a
+      new item is added to the menu. This allows you to easily roll back
+      to a previous configuration if something goes wrong.</para>
 
     <para>You should log in and change the <literal>root</literal>
     password with <command>passwd</command>.</para>
@@ -376,26 +379,26 @@ drive (here <filename>/dev/sda</filename>).  <xref linkend="ex-config"
 </example>
 
 <example xml:id='ex-config'><title>NixOS Configuration</title>
-<screen>
-{ config, pkgs, ... }:
+  <screen>
+    { config, pkgs, ... }:
 
-{
-  imports =
+    {
+    imports =
     [ # Include the results of the hardware scan.
-      ./hardware-configuration.nix
+    ./hardware-configuration.nix
     ];
 
-  boot.loader.grub.device = "/dev/sda";   # <lineannotation>(for BIOS systems only)</lineannotation>
-  boot.loader.systemd-boot.enable = true; # <lineannotation>(for UEFI systems only)</lineannotation>
+    <xref linkend="opt-boot.loader.grub.device"/> = "/dev/sda";   # <lineannotation>(for BIOS systems only)</lineannotation>
+    <xref linkend="opt-boot.loader.systemd-boot.enable"/> = true; # <lineannotation>(for UEFI systems only)</lineannotation>
 
-  # Note: setting fileSystems is generally not
-  # necessary, since nixos-generate-config figures them out
-  # automatically in hardware-configuration.nix.
-  #fileSystems."/".device = "/dev/disk/by-label/nixos";
+    # Note: setting fileSystems is generally not
+    # necessary, since nixos-generate-config figures them out
+    # automatically in hardware-configuration.nix.
+    #<link linkend="opt-fileSystems._name__.device">fileSystems."/".device</link> = "/dev/disk/by-label/nixos";
 
-  # Enable the OpenSSH server.
-  services.sshd.enable = true;
-}</screen>
+    # Enable the OpenSSH server.
+    services.sshd.enable = true;
+    }</screen>
 </example>
 
 <xi:include href="installing-usb.xml" />
diff --git a/nixos/doc/manual/installation/upgrading.xml b/nixos/doc/manual/installation/upgrading.xml
index aee6523345c..24881c8fec0 100644
--- a/nixos/doc/manual/installation/upgrading.xml
+++ b/nixos/doc/manual/installation/upgrading.xml
@@ -119,7 +119,7 @@ able to go back to your original channel.</para></warning>
 the following to <filename>configuration.nix</filename>:
 
 <programlisting>
-system.autoUpgrade.enable = true;
+<xref linkend="opt-system.autoUpgrade.enable"/> = true;
 </programlisting>
 
 This enables a periodically executed systemd service named
@@ -130,7 +130,7 @@ runs, see <command>systemctl list-timers</command>.)  You can also
 specify a channel explicitly, e.g.
 
 <programlisting>
-system.autoUpgrade.channel = https://nixos.org/channels/nixos-17.03;
+<xref linkend="opt-system.autoUpgrade.channel"/> = https://nixos.org/channels/nixos-17.03;
 </programlisting>
 
 </para>
diff --git a/nixos/modules/i18n/input-method/default.xml b/nixos/modules/i18n/input-method/default.xml
index 45d6daf068b..76ffa8cb7e3 100644
--- a/nixos/modules/i18n/input-method/default.xml
+++ b/nixos/modules/i18n/input-method/default.xml
@@ -6,56 +6,56 @@
 
 <title>Input Methods</title>
 
-<para>Input methods are an operating system component that allows any data, such 
-  as keyboard strokes or mouse movements, to be received as input. In this way 
-  users can enter characters and symbols not found on their input devices. Using 
-  an input method is obligatory for any language that has more graphemes than 
+<para>Input methods are an operating system component that allows any data, such
+  as keyboard strokes or mouse movements, to be received as input. In this way
+  users can enter characters and symbols not found on their input devices. Using
+  an input method is obligatory for any language that has more graphemes than
   there are keys on the keyboard.</para>
 
 <para>The following input methods are available in NixOS:</para>
 
 <itemizedlist>
   <listitem><para>IBus: The intelligent input bus.</para></listitem>
-  <listitem><para>Fcitx: A customizable lightweight input 
+  <listitem><para>Fcitx: A customizable lightweight input
       method.</para></listitem>
   <listitem><para>Nabi: A Korean input method based on XIM.</para></listitem>
-  <listitem><para>Uim: The universal input method, is a library with a XIM 
+  <listitem><para>Uim: The universal input method, is a library with a XIM
       bridge.</para></listitem>
 </itemizedlist>
 
 <section><title>IBus</title>
 
-<para>IBus is an Intelligent Input Bus. It provides full featured and user 
+<para>IBus is an Intelligent Input Bus. It provides full featured and user
   friendly input method user interface.</para>
 
 <para>The following snippet can be used to configure IBus:</para>
 
 <programlisting>
 i18n.inputMethod = {
-  enabled = "ibus";
-  ibus.engines = with pkgs.ibus-engines; [ anthy hangul mozc ];
+  <link linkend="opt-i18n.inputMethod.enabled">enabled</link> = "ibus";
+  <link linkend="opt-i18n.inputMethod.ibus.engines">ibus.engines</link> = with pkgs.ibus-engines; [ anthy hangul mozc ];
 };
 </programlisting>
 
-<para><literal>i18n.inputMethod.ibus.engines</literal> is optional and can be 
+<para><literal>i18n.inputMethod.ibus.engines</literal> is optional and can be
   used to add extra IBus engines.</para>
 
 <para>Available extra IBus engines are:</para>
 
 <itemizedlist>
-  <listitem><para>Anthy (<literal>ibus-engines.anthy</literal>): Anthy is a 
-      system for Japanese input method. It converts Hiragana text to Kana Kanji 
+  <listitem><para>Anthy (<literal>ibus-engines.anthy</literal>): Anthy is a
+      system for Japanese input method. It converts Hiragana text to Kana Kanji
       mixed text.</para></listitem>
-  <listitem><para>Hangul (<literal>ibus-engines.hangul</literal>): Korean input 
+  <listitem><para>Hangul (<literal>ibus-engines.hangul</literal>): Korean input
       method.</para></listitem>
-  <listitem><para>m17n (<literal>ibus-engines.m17n</literal>): m17n is an input 
-      method that uses input methods and corresponding icons in the m17n 
+  <listitem><para>m17n (<literal>ibus-engines.m17n</literal>): m17n is an input
+      method that uses input methods and corresponding icons in the m17n
       database.</para></listitem>
-  <listitem><para>mozc (<literal>ibus-engines.mozc</literal>): A Japanese input 
+  <listitem><para>mozc (<literal>ibus-engines.mozc</literal>): A Japanese input
       method from Google.</para></listitem>
-  <listitem><para>Table (<literal>ibus-engines.table</literal>): An input method 
+  <listitem><para>Table (<literal>ibus-engines.table</literal>): An input method
       that load tables of input methods.</para></listitem>
-  <listitem><para>table-others (<literal>ibus-engines.table-others</literal>): 
+  <listitem><para>table-others (<literal>ibus-engines.table-others</literal>):
       Various table-based input methods. To use this, and any other table-based
       input methods, it must appear in the list of engines along with
       <literal>table</literal>. For example:
@@ -72,71 +72,71 @@ ibus.engines = with pkgs.ibus-engines; [ table table-others ];
 
 <section><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 
+<para>Fcitx is an input method framework with extension support. It has three
+  built-in Input Method Engine, Pinyin, QuWei and Table-based input
   methods.</para>
 <para>The following snippet can be used to configure Fcitx:</para>
 
 <programlisting>
 i18n.inputMethod = {
-  enabled = "fcitx";
-  fcitx.engines = with pkgs.fcitx-engines; [ mozc hangul m17n ];
+  <link linkend="opt-i18n.inputMethod.enabled">enabled</link> = "fcitx";
+  <link linkend="opt-i18n.inputMethod.fcitx.engines">fcitx.engines</link> = with pkgs.fcitx-engines; [ mozc hangul m17n ];
 };
 </programlisting>
 
-<para><literal>i18n.inputMethod.fcitx.engines</literal> is optional and can be 
+<para><literal>i18n.inputMethod.fcitx.engines</literal> is optional and can be
   used to add extra Fcitx engines.</para>
 
 <para>Available extra Fcitx engines are:</para>
 
 <itemizedlist>
-  <listitem><para>Anthy (<literal>fcitx-engines.anthy</literal>): Anthy is a 
-      system for Japanese input method. It converts Hiragana text to Kana Kanji 
+  <listitem><para>Anthy (<literal>fcitx-engines.anthy</literal>): Anthy is a
+      system for Japanese input method. It converts Hiragana text to Kana Kanji
       mixed text.</para></listitem>
-  <listitem><para>Chewing (<literal>fcitx-engines.chewing</literal>): Chewing is 
-      an intelligent Zhuyin input method. It is one of the most popular input 
+  <listitem><para>Chewing (<literal>fcitx-engines.chewing</literal>): Chewing is
+      an intelligent Zhuyin input method. It is one of the most popular input
       methods among Traditional Chinese Unix users.</para></listitem>
-  <listitem><para>Hangul (<literal>fcitx-engines.hangul</literal>): Korean input 
+  <listitem><para>Hangul (<literal>fcitx-engines.hangul</literal>): Korean input
       method.</para></listitem>
-  <listitem><para>Unikey (<literal>fcitx-engines.unikey</literal>): Vietnamese input 
+  <listitem><para>Unikey (<literal>fcitx-engines.unikey</literal>): Vietnamese input
       method.</para></listitem>
-  <listitem><para>m17n (<literal>fcitx-engines.m17n</literal>): m17n is an input 
-      method that uses input methods and corresponding icons in the m17n 
+  <listitem><para>m17n (<literal>fcitx-engines.m17n</literal>): m17n is an input
+      method that uses input methods and corresponding icons in the m17n
       database.</para></listitem>
-  <listitem><para>mozc (<literal>fcitx-engines.mozc</literal>): A Japanese input 
+  <listitem><para>mozc (<literal>fcitx-engines.mozc</literal>): A Japanese input
       method from Google.</para></listitem>
-  <listitem><para>table-others (<literal>fcitx-engines.table-others</literal>): 
+  <listitem><para>table-others (<literal>fcitx-engines.table-others</literal>):
       Various table-based input methods.</para></listitem>
 </itemizedlist>
 </section>
 
 <section><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 
+<para>Nabi is an easy to use Korean X input method. It allows you to enter
+  phonetic Korean characters (hangul) and pictographic Korean characters
   (hanja).</para>
 <para>The following snippet can be used to configure Nabi:</para>
 
 <programlisting>
 i18n.inputMethod = {
-  enabled = "nabi";
+  <link linkend="opt-i18n.inputMethod.enabled">enabled</link> = "nabi";
 };
 </programlisting>
 </section>
 
 <section><title>Uim</title>
 
-<para>Uim (short for "universal input method") is a multilingual input method 
+<para>Uim (short for "universal input method") is a multilingual input method
   framework. Applications can use it through so-called bridges.</para>
 <para>The following snippet can be used to configure uim:</para>
 
 <programlisting>
 i18n.inputMethod = {
-  enabled = "uim";
+  <link linkend="opt-i18n.inputMethod.enabled">enabled</link> = "uim";
 };
 </programlisting>
 
-<para>Note: The <literal>i18n.inputMethod.uim.toolbar</literal> option can be 
+<para>Note: The <xref linkend="opt-i18n.inputMethod.uim.toolbar"/> option can be
   used to choose uim toolbar.</para>
 
 </section>
diff --git a/nixos/modules/programs/digitalbitbox/doc.xml b/nixos/modules/programs/digitalbitbox/doc.xml
index 7acbc2fc4dd..a26653dda53 100644
--- a/nixos/modules/programs/digitalbitbox/doc.xml
+++ b/nixos/modules/programs/digitalbitbox/doc.xml
@@ -15,9 +15,9 @@
     installed by setting <literal>programs.digitalbitbox</literal>
     to <literal>true</literal> in a manner similar to
 
-    <programlisting>
-      programs.digitalbitbox.enable = true;
-    </programlisting>
+<programlisting>
+<xref linkend="opt-programs.digitalbitbox.enable"/> = true;
+</programlisting>
 
     and bundles the <literal>digitalbitbox</literal> package (see <xref
       linkend="sec-digitalbitbox-package" />), which contains the
@@ -46,11 +46,11 @@
       <literal>digitalbitbox</literal> package which could be installed
       as follows:
 
-      <programlisting>
-        environment.systemPackages = [
-          pkgs.digitalbitbox
-        ];
-      </programlisting>
+<programlisting>
+<xref linkend="opt-environment.systemPackages"/> = [
+  pkgs.digitalbitbox
+];
+</programlisting>
     </para>
   </section>
 
@@ -62,9 +62,9 @@
       The digitalbitbox hardware package enables the udev rules for
       Digital Bitbox devices and may be installed as follows:
 
-      <programlisting>
-        hardware.digitalbitbox.enable = true;
-      </programlisting>
+<programlisting>
+<xref linkend="opt-hardware.digitalbitbox.enable"/> = true;
+</programlisting>
     </para>
 
     <para>
@@ -72,14 +72,14 @@
       the <literal>udevRule51</literal> and <literal>udevRule52</literal>
       attributes by means of overriding as follows:
 
-      <programlisting>
-        programs.digitalbitbox = {
-          enable = true;
-          package = pkgs.digitalbitbox.override {
-            udevRule51 = "something else";
-          };
-        };
-      </programlisting>
+<programlisting>
+programs.digitalbitbox = {
+  <link linkend="opt-programs.digitalbitbox.enable">enable</link> = true;
+  <link linkend="opt-programs.digitalbitbox.package">package</link> = pkgs.digitalbitbox.override {
+    udevRule51 = "something else";
+  };
+};
+</programlisting>
     </para>
   </section>
 </chapter>
diff --git a/nixos/modules/programs/plotinus.xml b/nixos/modules/programs/plotinus.xml
index 85b0e023e6c..91740ee16ec 100644
--- a/nixos/modules/programs/plotinus.xml
+++ b/nixos/modules/programs/plotinus.xml
@@ -17,7 +17,7 @@
 <para>To enable Plotinus, add the following to your <filename>configuration.nix</filename>:
 
 <programlisting>
-programs.plotinus.enable = true;
+<xref linkend="opt-programs.plotinus.enable"/> = true;
 </programlisting>
 
 </para>
diff --git a/nixos/modules/security/acme.xml b/nixos/modules/security/acme.xml
index 6130ed82ed3..7cdc554989e 100644
--- a/nixos/modules/security/acme.xml
+++ b/nixos/modules/security/acme.xml
@@ -48,9 +48,9 @@ http {
 <filename>configuration.nix</filename>:
 
 <programlisting>
-security.acme.certs."foo.example.com" = {
-  webroot = "/var/www/challenges";
-  email = "foo@example.com";
+<xref linkend="opt-security.acme.certs"/>."foo.example.com" = {
+  <link linkend="opt-security.acme.certs._name_.webroot">webroot</link> = "/var/www/challenges";
+  <link linkend="opt-security.acme.certs._name_.email">email</link> = "foo@example.com";
 };
 </programlisting>
 </para>
@@ -58,17 +58,17 @@ security.acme.certs."foo.example.com" = {
 <para>The private key <filename>key.pem</filename> and certificate
 <filename>fullchain.pem</filename> will be put into
 <filename>/var/lib/acme/foo.example.com</filename>. The target directory can
-be configured with the option <literal>security.acme.directory</literal>.
+be configured with the option <xref linkend="opt-security.acme.directory"/>.
 </para>
 
 <para>Refer to <xref linkend="ch-options" /> for all available configuration
-options for the <literal>security.acme</literal> module.</para>
+options for the <link linkend="opt-security.acme.certs">security.acme</link> module.</para>
 
 </section>
 
 <section><title>Using ACME certificates in Nginx</title>
 <para>NixOS supports fetching ACME certificates for you by setting
-<literal>enableACME = true;</literal> in a virtualHost config. We
+  <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
 real ACME certs. The placeholder certs are overwritten when the ACME
 certs arrive. For <literal>foo.example.com</literal> the config would
@@ -77,13 +77,13 @@ look like.
 
 <programlisting>
 services.nginx = {
-  enable = true;
-  virtualHosts = {
+  <link linkend="opt-services.nginx.enable">enable = true;</link>
+  <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = {
     "foo.example.com" = {
-      forceSSL = true;
-      enableACME = true;
+      <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
+      <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;
       locations."/" = {
-        root = "/var/www";
+        <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.root">root</link> = "/var/www";
       };
     };
   };
diff --git a/nixos/modules/security/hidepid.xml b/nixos/modules/security/hidepid.xml
index 5715ee7ac16..d69341eb3cd 100644
--- a/nixos/modules/security/hidepid.xml
+++ b/nixos/modules/security/hidepid.xml
@@ -8,9 +8,9 @@
 
   <para>
     Setting
-    <programlisting>
-      security.hideProcessInformation = true;
-    </programlisting>
+<programlisting>
+<xref linkend="opt-security.hideProcessInformation"/> = true;
+</programlisting>
     ensures that access to process information is restricted to the
     owning user.  This implies, among other things, that command-line
     arguments remain private.  Unless your deployment relies on unprivileged
@@ -25,9 +25,9 @@
 
   <para>
     To allow a service <replaceable>foo</replaceable> to run without process information hiding, set
-    <programlisting>
-      systemd.services.<replaceable>foo</replaceable>.serviceConfig.SupplementaryGroups = [ "proc" ];
-    </programlisting>
+<programlisting>
+<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.<replaceable>foo</replaceable>.serviceConfig</link>.SupplementaryGroups = [ "proc" ];
+</programlisting>
   </para>
 
 </chapter>
diff --git a/nixos/modules/services/databases/postgresql.xml b/nixos/modules/services/databases/postgresql.xml
index a9802694295..98a631c0cd3 100644
--- a/nixos/modules/services/databases/postgresql.xml
+++ b/nixos/modules/services/databases/postgresql.xml
@@ -23,15 +23,15 @@
 <filename>configuration.nix</filename>:
 
 <programlisting>
-services.postgresql.enable = true;
-services.postgresql.package = pkgs.postgresql94;
+<xref linkend="opt-services.postgresql.enable"/> = true;
+<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql94;
 </programlisting>
 
 Note that you are required to specify the desired version of
 PostgreSQL (e.g. <literal>pkgs.postgresql94</literal>). Since
 upgrading your PostgreSQL version requires a database dump and reload
 (see below), NixOS cannot provide a default value for
-<option>services.postgresql.package</option> such as the most recent
+<xref linkend="opt-services.postgresql.package"/> such as the most recent
 release of PostgreSQL.</para>
 
 <!--
@@ -49,10 +49,10 @@ alice=>
 
 <para>By default, PostgreSQL stores its databases in
 <filename>/var/db/postgresql</filename>. You can override this using
-<option>services.postgresql.dataDir</option>, e.g.
+<xref linkend="opt-services.postgresql.dataDir"/>, e.g.
 
 <programlisting>
-services.postgresql.dataDir = "/data/postgresql";
+<xref linkend="opt-services.postgresql.dataDir"/> = "/data/postgresql";
 </programlisting>
 
 </para>
@@ -69,7 +69,7 @@ services.postgresql.dataDir = "/data/postgresql";
 
 <section><title>Options</title>
 
-<para>FIXME: auto-generated list of module options.</para>
+  <para>A complete list of options for the PostgreSQL module may be found <link linkend="opt-services.postgresql.enable">here</link>.</para>
 
 </section>
 
diff --git a/nixos/modules/services/editors/emacs.xml b/nixos/modules/services/editors/emacs.xml
index dd66bac442c..dfab5ce4a79 100644
--- a/nixos/modules/services/editors/emacs.xml
+++ b/nixos/modules/services/editors/emacs.xml
@@ -404,10 +404,10 @@ in [...]
       user service for Emacs daemon, add the following to your
       <filename>configuration.nix</filename>:
 
-      <programlisting><![CDATA[
-services.emacs.enable = true;
-services.emacs.package = import /home/cassou/.emacs.d { pkgs = pkgs; };
-]]></programlisting>
+<programlisting>
+<xref linkend="opt-services.emacs.enable"/> = true;
+<xref linkend="opt-services.emacs.package"/> = import /home/cassou/.emacs.d { pkgs = pkgs; };
+</programlisting>
     </para>
 
     <para>
@@ -462,7 +462,7 @@ emacsclient --create-frame --tty  # opens a new frame on the current terminal
     <!--<title><command>emacsclient</command> as the Default Editor</title>-->
 
     <para>
-      If <varname>services.emacs.defaultEditor</varname> is
+      If <xref linkend="opt-services.emacs.defaultEditor"/> is
       <literal>true</literal>, the <varname>EDITOR</varname> variable
       will be set to a wrapper script which launches
       <command>emacsclient</command>.
@@ -497,10 +497,10 @@ emacsclient --create-frame --tty  # opens a new frame on the current terminal
       Emacs daemon is not wanted for all users, it is possible to
       install the service but not globally enable it:
 
-      <programlisting><![CDATA[
-services.emacs.enable = false;
-services.emacs.install = true;
-]]></programlisting>
+<programlisting>
+<xref linkend="opt-services.emacs.enable"/> = false;
+<xref linkend="opt-services.emacs.install"/> = true;
+</programlisting>
     </para>
 
     <para>
@@ -582,7 +582,7 @@ services.emacs.install = true;
     <para>
       To install the DocBook 5.0 schemas, either add
       <varname>pkgs.docbook5</varname> to
-      <varname>environment.systemPackages</varname> (<link
+      <xref linkend="opt-environment.systemPackages"/> (<link
       linkend="sec-declarative-package-mgmt">NixOS</link>), or run
       <literal>nix-env -i pkgs.docbook5</literal>
       (<link linkend="sec-ad-hoc-packages">Nix</link>).
diff --git a/nixos/modules/services/misc/gitlab.xml b/nixos/modules/services/misc/gitlab.xml
index 4b00f50abd6..3306ba8e9b1 100644
--- a/nixos/modules/services/misc/gitlab.xml
+++ b/nixos/modules/services/misc/gitlab.xml
@@ -18,19 +18,18 @@ webserver to proxy HTTP requests to the socket.</para>
     frontend proxy:
 
 <programlisting>
-    services.nginx = {
-      enable = true;
-      recommendedGzipSettings = true;
-      recommendedOptimisation = true;
-      recommendedProxySettings = true;
-      recommendedTlsSettings = true;
-      virtualHosts."git.example.com" = {
-        enableACME = true;
-        forceSSL = true;
-        locations."/".proxyPass = "http://unix:/run/gitlab/gitlab-workhorse.socket";
-      };
-    };
-'';
+<link linkend="opt-services.nginx.enable">services.nginx</link> = {
+  <link linkend="opt-services.nginx.enable">enable</link> = true;
+  <link linkend="opt-services.nginx.recommendedGzipSettings">recommendedGzipSettings</link> = true;
+  <link linkend="opt-services.nginx.recommendedOptimisation">recommendedOptimisation</link> = true;
+  <link linkend="opt-services.nginx.recommendedProxySettings">recommendedProxySettings</link> = true;
+  <link linkend="opt-services.nginx.recommendedTlsSettings">recommendedTlsSettings</link> = true;
+  <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link>."git.example.com" = {
+    <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;
+    <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
+    <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.proxyPass">locations."/".proxyPass</link> = "http://unix:/run/gitlab/gitlab-workhorse.socket";
+  };
+};
 </programlisting>
 </para>
 
@@ -49,24 +48,24 @@ all data like the repositories and uploads will be stored.</para>
 
 <programlisting>
 services.gitlab = {
-  enable = true;
-  databasePassword = "eXaMpl3";
-  initialRootPassword = "UseNixOS!";
-  https = true;
-  host = "git.example.com";
-  port = 443;
-  user = "git";
-  group = "git";
+  <link linkend="opt-services.gitlab.enable">enable</link> = true;
+  <link linkend="opt-services.gitlab.databasePassword">databasePassword</link> = "eXaMpl3";
+  <link linkend="opt-services.gitlab.initialRootPassword">initialRootPassword</link> = "UseNixOS!";
+  <link linkend="opt-services.gitlab.https">https</link> = true;
+  <link linkend="opt-services.gitlab.host">host</link> = "git.example.com";
+  <link linkend="opt-services.gitlab.port">port</link> = 443;
+  <link linkend="opt-services.gitlab.user">user</link> = "git";
+  <link linkend="opt-services.gitlab.group">group</link> = "git";
   smtp = {
-    enable = true;
-    address = "localhost";
-    port = 25;
+    <link linkend="opt-services.gitlab.smtp.enable">enable</link> = true;
+    <link linkend="opt-services.gitlab.smtp.address">address</link> = "localhost";
+    <link linkend="opt-services.gitlab.smtp.port">port</link> = 25;
   };
   secrets = {
-    db = "uPgq1gtwwHiatiuE0YHqbGa5lEIXH7fMsvuTNgdzJi8P0Dg12gibTzBQbq5LT7PNzcc3BP9P1snHVnduqtGF43PgrQtU7XL93ts6gqe9CBNhjtaqUwutQUDkygP5NrV6";
-    secret = "devzJ0Tz0POiDBlrpWmcsjjrLaltyiAdS8TtgT9YNBOoUcDsfppiY3IXZjMVtKgXrFImIennFGOpPN8IkP8ATXpRgDD5rxVnKuTTwYQaci2NtaV1XxOQGjdIE50VGsR3";
-    otp = "e1GATJVuS2sUh7jxiPzZPre4qtzGGaS22FR50Xs1TerRVdgI3CBVUi5XYtQ38W4xFeS4mDqi5cQjExE838iViSzCdcG19XSL6qNsfokQP9JugwiftmhmCadtsnHErBMI";
-    jws = ''
+    <link linkend="opt-services.gitlab.secrets.db">db</link> = "uPgq1gtwwHiatiuE0YHqbGa5lEIXH7fMsvuTNgdzJi8P0Dg12gibTzBQbq5LT7PNzcc3BP9P1snHVnduqtGF43PgrQtU7XL93ts6gqe9CBNhjtaqUwutQUDkygP5NrV6";
+    <link linkend="opt-services.gitlab.secrets.secret">secret</link> = "devzJ0Tz0POiDBlrpWmcsjjrLaltyiAdS8TtgT9YNBOoUcDsfppiY3IXZjMVtKgXrFImIennFGOpPN8IkP8ATXpRgDD5rxVnKuTTwYQaci2NtaV1XxOQGjdIE50VGsR3";
+    <link linkend="opt-services.gitlab.secrets.otp">otp</link> = "e1GATJVuS2sUh7jxiPzZPre4qtzGGaS22FR50Xs1TerRVdgI3CBVUi5XYtQ38W4xFeS4mDqi5cQjExE838iViSzCdcG19XSL6qNsfokQP9JugwiftmhmCadtsnHErBMI";
+    <link linkend="opt-services.gitlab.secrets.jws">jws</link> = ''
       -----BEGIN RSA PRIVATE KEY-----
       MIIEpAIBAAKCAQEArrtx4oHKwXoqUbMNqnHgAklnnuDon3XG5LJB35yPsXKv/8GK
       ke92wkI+s1Xkvsp8tg9BIY/7c6YK4SR07EWL+dB5qwctsWR2Q8z+/BKmTx9D99pm
@@ -96,7 +95,7 @@ services.gitlab = {
       -----END RSA PRIVATE KEY-----
     '';
   };
-  extraConfig = {
+  <link linkend="opt-services.gitlab.extraConfig">extraConfig</link> = {
     gitlab = {
       email_from = "gitlab-no-reply@example.com";
       email_display_name = "Example GitLab";
@@ -116,7 +115,7 @@ secret from <literal>config/secrets.yml</literal> located in your Gitlab state
 folder.</para>
 
 <para>Refer to <xref linkend="ch-options" /> for all available configuration
-options for the <literal>services.gitlab</literal> module.</para>
+options for the <link linkend="opt-services.gitlab.enable">services.gitlab</link> module.</para>
 
 </section>
 
diff --git a/nixos/modules/services/misc/taskserver/doc.xml b/nixos/modules/services/misc/taskserver/doc.xml
index 6d4d2a9b488..75493ac1394 100644
--- a/nixos/modules/services/misc/taskserver/doc.xml
+++ b/nixos/modules/services/misc/taskserver/doc.xml
@@ -55,7 +55,7 @@
       Because Taskserver by default only provides scripts to setup users
       imperatively, the <command>nixos-taskserver</command> tool is used for
       addition and deletion of organisations along with users and groups defined
-      by <option>services.taskserver.organisations</option> and as well for
+      by <xref linkend="opt-services.taskserver.organisations"/> and as well for
       imperative set up.
     </para>
 
@@ -99,10 +99,10 @@
       For example, let's say you have the following configuration:
 <screen>
 {
-  services.taskserver.enable = true;
-  services.taskserver.fqdn = "server";
-  services.taskserver.listenHost = "::";
-  services.taskserver.organisations.my-company.users = [ "alice" ];
+  <xref linkend="opt-services.taskserver.enable"/> = true;
+  <xref linkend="opt-services.taskserver.fqdn"/> = "server";
+  <xref linkend="opt-services.taskserver.listenHost"/> = "::";
+  <link linkend="opt-services.taskserver.organisations._name_.users">services.taskserver.organisations.my-company.users</link> = [ "alice" ];
 }
 </screen>
       This creates an organisation called <literal>my-company</literal> with the
@@ -136,7 +136,7 @@ $ ssh server nixos-taskserver user export my-company alice | sh
 
     <para>
       If you set any options within
-      <option>service.taskserver.pki.manual.*</option>,
+      <link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*,
       <command>nixos-taskserver</command> won't issue certificates, but you can
       still use it for adding or removing user accounts.
     </para>
diff --git a/nixos/modules/services/networking/dnscrypt-proxy.xml b/nixos/modules/services/networking/dnscrypt-proxy.xml
index 555c6df4d55..ff108869858 100644
--- a/nixos/modules/services/networking/dnscrypt-proxy.xml
+++ b/nixos/modules/services/networking/dnscrypt-proxy.xml
@@ -19,7 +19,7 @@
   <para>
     To enable the client proxy, set
     <programlisting>
-      services.dnscrypt-proxy.enable = true;
+<xref linkend="opt-services.dnscrypt-proxy.enable"/> = true;
     </programlisting>
   </para>
 
@@ -38,17 +38,17 @@
     DNS client, change the default proxy listening port to a
     non-standard value and point the other client to it:
     <programlisting>
-      services.dnscrypt-proxy.localPort = 43;
+<xref linkend="opt-services.dnscrypt-proxy.localPort"/> = 43;
     </programlisting>
   </para>
 
   <sect2><title>dnsmasq</title>
   <para>
     <programlisting>
-      {
-        services.dnsmasq.enable = true;
-        services.dnsmasq.servers = [ "127.0.0.1#43" ];
-      }
+{
+  <xref linkend="opt-services.dnsmasq.enable"/> = true;
+  <xref linkend="opt-services.dnsmasq.servers"/> = [ "127.0.0.1#43" ];
+}
     </programlisting>
   </para>
   </sect2>
@@ -56,10 +56,10 @@
   <sect2><title>unbound</title>
   <para>
     <programlisting>
-      {
-        services.unbound.enable = true;
-        services.unbound.forwardAddresses = [ "127.0.0.1@43" ];
-      }
+{
+  <xref linkend="opt-services.unbound.enable"/> = true;
+  <xref linkend="opt-services.unbound.forwardAddresses"/> = [ "127.0.0.1@43" ];
+}
     </programlisting>
   </para>
   </sect2>