Fix some dangling references

23 files changed, 139 insertions, 235 deletions

diff --git a/doc/manual/src/advanced-topics/cores-vs-jobs.md b/doc/manual/src/advanced-topics/cores-vs-jobs.md
index 91e95d5b4..4a9058ca1 100644
--- a/doc/manual/src/advanced-topics/cores-vs-jobs.md
+++ b/doc/manual/src/advanced-topics/cores-vs-jobs.md
@@ -1,33 +1,32 @@
 # Tuning Cores and Jobs
 
-Nix has two relevant settings with regards to how your CPU cores will be
-utilized: [???](#conf-cores) and [???](#conf-max-jobs). This chapter
-will talk about what they are, how they interact, and their
-configuration trade-offs.
+Nix has two relevant settings with regards to how your CPU cores will
+be utilized: `cores` and `max-jobs`. This chapter will talk about what
+they are, how they interact, and their configuration trade-offs.
 
-  - [???](#conf-max-jobs)  
+  - `max-jobs`  
     Dictates how many separate derivations will be built at the same
-    time. If you set this to zero, the local machine will do no builds.
-    Nix will still substitute from binary caches, and build remotely if
-    remote builders are configured.
+    time. If you set this to zero, the local machine will do no
+    builds.  Nix will still substitute from binary caches, and build
+    remotely if remote builders are configured.
 
-  - [???](#conf-cores)  
-    Suggests how many cores each derivation should use. Similar to `make
-    -j`.
+  - `cores`  
+    Suggests how many cores each derivation should use. Similar to
+    `make -j`.
 
-The [???](#conf-cores) setting determines the value of
-`NIX_BUILD_CORES`. `NIX_BUILD_CORES` is equal to [???](#conf-cores),
-unless [???](#conf-cores) equals `0`, in which case `NIX_BUILD_CORES`
-will be the total number of cores in the system.
+The `cores` setting determines the value of
+`NIX_BUILD_CORES`. `NIX_BUILD_CORES` is equal to `cores`, unless
+`cores` equals `0`, in which case `NIX_BUILD_CORES` will be the total
+number of cores in the system.
 
 The maximum number of consumed cores is a simple multiplication,
-[???](#conf-max-jobs) \* `NIX_BUILD_CORES`.
+`max-jobs` \* `NIX_BUILD_CORES`.
 
 The balance on how to set these two independent variables depends upon
 each builder's workload and hardware. Here are a few example scenarios
 on a machine with 24 cores:
 
-| [???](#conf-max-jobs) | [???](#conf-cores) | `NIX_BUILD_CORES` | Maximum Processes | Result                                                                                                                                                                                                                                                                                 |
+| `max-jobs` | `cores` | `NIX_BUILD_CORES` | Maximum Processes | Result                                                                                                                                                                                                                                                                                 |
 | --------------------- | ------------------ | ----------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 1                     | 24                 | 24                | 24                | One derivation will be built at a time, each one can use 24 cores. Undersold if a job can’t use 24 cores.                                                                                                                                                                              |
 | 4                     | 6                  | 6                 | 24                | Four derivations will be built at once, each given access to six cores.                                                                                                                                                                                                                |
@@ -35,8 +34,6 @@ on a machine with 24 cores:
 | 24                    | 1                  | 1                 | 24                | 24 derivations can build at the same time, each using a single core. Never oversold, but derivations which require many cores will be very slow to compile.                                                                                                                            |
 | 24                    | 0                  | 24                | 576               | 24 derivations can build at the same time, each using all the available cores of the machine. Very likely to be oversold, and very likely to suffer context switches.                                                                                                                  |
 
-Balancing 24 Build Cores
-
 It is up to the derivations' build script to respect host's requested
 cores-per-build by following the value of the `NIX_BUILD_CORES`
 environment variable.
diff --git a/doc/manual/src/advanced-topics/diff-hook.md b/doc/manual/src/advanced-topics/diff-hook.md
index 2c9896fa5..e2234147f 100644
--- a/doc/manual/src/advanced-topics/diff-hook.md
+++ b/doc/manual/src/advanced-topics/diff-hook.md
@@ -1,9 +1,8 @@
 # Verifying Build Reproducibility
 
-Specify a program with Nix's [???](#conf-diff-hook) to compare build
-results when two builds produce different results. Note: this hook is
-only executed if the results are not the same, this hook is not used for
-determining if the results are the same.
+You can use Nix's `diff-hook` setting to compare build results. Note
+that this hook is only executed if the results differ; it is not used
+for determining if the results are the same.
 
 For purposes of demonstration, we'll use the following Nix file,
 `deterministic.nix` for testing:
@@ -93,7 +92,7 @@ has copied the build results to that directory where you can examine it.
 > path will be deleted on the next garbage collection.
 > 
 > The path is guaranteed to be alive for the duration of
-> [???](#conf-diff-hook)'s execution, but may be deleted any time after.
+> the `diff-hook`'s execution, but may be deleted any time after.
 > 
 > If the comparison is performed as part of automated tooling, please
 > use the diff-hook or author your tooling to handle the case where the
@@ -112,9 +111,8 @@ Run the build without `--check`, and then try with `--check` again.
 Automatically verify every build at build time by executing the build
 multiple times.
 
-Setting [???](#conf-repeat) and [???](#conf-enforce-determinism) in your
-`nix.conf` permits the automated verification of every build Nix
-performs.
+Setting `repeat` and `enforce-determinism` in your `nix.conf` permits
+the automated verification of every build Nix performs.
 
 The following configuration will run each build three times, and will
 require the build to be deterministic:
@@ -122,9 +120,9 @@ require the build to be deterministic:
     enforce-determinism = true
     repeat = 2
 
-Setting [???](#conf-enforce-determinism) to false as in the following
-configuration will run the build multiple times, execute the build hook,
-but will allow the build to succeed even if it does not build
+Setting `enforce-determinism` to false as in the following
+configuration will run the build multiple times, execute the build
+hook, but will allow the build to succeed even if it does not build
 reproducibly:
 
     enforce-determinism = false
diff --git a/doc/manual/src/advanced-topics/post-build-hook.md b/doc/manual/src/advanced-topics/post-build-hook.md
index 166b57da6..0d02a8ff3 100644
--- a/doc/manual/src/advanced-topics/post-build-hook.md
+++ b/doc/manual/src/advanced-topics/post-build-hook.md
@@ -17,9 +17,8 @@ the build loop.
 
 # Prerequisites
 
-This tutorial assumes you have configured an S3-compatible binary cache
-according to the instructions at
-[???](#ssec-s3-substituter-authenticated-writes), and that the `root`
+This tutorial assumes you have [configured an S3-compatible binary
+cache](../package-management/s3-substituter.md), and that the `root`
 user's default AWS profile can upload to the bucket.
 
 # Set up a Signing Key
@@ -33,7 +32,7 @@ distribute the public key for verifying the authenticity of the paths.
     example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM=
 
 Then, add the public key and the cache URL to your `nix.conf`'s
-[???](#conf-trusted-public-keys) and [???](#conf-substituters) like:
+`trusted-public-keys` and `substituters` options:
 
     substituters = https://cache.nixos.org/ s3://example-nix-cache
     trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM=
diff --git a/doc/manual/src/command-ref/conf-file.md b/doc/manual/src/command-ref/conf-file.md
index 4fa9cedfc..bedf1ec6b 100644
--- a/doc/manual/src/command-ref/conf-file.md
+++ b/doc/manual/src/command-ref/conf-file.md
@@ -77,8 +77,7 @@ The following settings are currently available:
                     --optimise` to get rid of duplicate files.
 
   - `builders`  
-    A list of machines on which to perform builds. See
-    [???](#chap-distributed-builds) for details.
+    A list of machines on which to perform builds.
 
   - `builders-use-substitutes`  
     If set to `true`, Nix will instruct remote build machines to use
@@ -140,8 +139,6 @@ The following settings are currently available:
     `-jN` flag to GNU Make. It can be overridden using the `--cores`
     command line switch and defaults to `1`. The value `0` means that
     the builder should use all available CPU cores in the system.
-    
-    See also [???](#chap-tuning-cores-and-jobs).
 
   - `diff-hook`  
     Absolute path to an executable capable of diffing build results. The
@@ -298,8 +295,6 @@ The following settings are currently available:
     `preferLocalBuild` derivation attribute which executes locally
     regardless). It can be overridden using the `--max-jobs` (`-j`)
     command line switch.
-    
-    See also [???](#chap-tuning-cores-and-jobs).
 
   - `max-silent-time`  
     This option defines the maximum number of seconds that a builder can
@@ -429,12 +424,10 @@ The following settings are currently available:
         
         Example:
         `/nix/store/zf5lbh336mnzf1nlswdn11g4n2m8zh3g-bash-4.4-p23-dev
-                                                                                                        /nix/store/rjxwxwv1fpn9wa2x5ssk5phzwlcv4mna-bash-4.4-p23-doc
-                                                                                                        /nix/store/6bqvbzjkcp9695dq0dpl5y43nvy37pq1-bash-4.4-p23-info
-                                                                                                        /nix/store/r7fng3kk3vlpdlh2idnrbn37vh4imlj2-bash-4.4-p23-man
-                                                                                                        /nix/store/xfghy8ixrhz3kyy6p724iv3cxji088dx-bash-4.4-p23`.
-    
-    See [???](#chap-post-build-hook) for an example implementation.
+        /nix/store/rjxwxwv1fpn9wa2x5ssk5phzwlcv4mna-bash-4.4-p23-doc
+        /nix/store/6bqvbzjkcp9695dq0dpl5y43nvy37pq1-bash-4.4-p23-info
+        /nix/store/r7fng3kk3vlpdlh2idnrbn37vh4imlj2-bash-4.4-p23-man
+        /nix/store/xfghy8ixrhz3kyy6p724iv3cxji088dx-bash-4.4-p23`.
 
   - `repeat`  
     How many times to repeat builds to check whether they are
@@ -459,8 +452,7 @@ The following settings are currently available:
     `allowed-uri`. The default is `false`.
 
   - `run-diff-hook`  
-    If true, enable the execution of
-    [varlistentry\_title](#conf-diff-hook).
+    If true, enable the execution of the `diff-hook` program.
     
     When using the Nix daemon, `run-diff-hook` must be set in the
     `nix.conf` configuration file, and cannot be passed at the command
@@ -595,15 +587,11 @@ The following settings are currently available:
     Nix will print a log message at the "vomit" level for every function
     entrance and function exit.
     
-    <div class="informalexample">
-    
         function-trace entered undefined position at 1565795816999559622
         function-trace exited undefined position at 1565795816999581277
         function-trace entered /nix/store/.../example.nix:226:41 at 1565795253249935150
         function-trace exited /nix/store/.../example.nix:226:41 at 1565795253249941684
     
-    </div>
-    
     The `undefined position` means the function call is a builtin.
     
     Use the `contrib/stack-collapse.py` script distributed with the Nix
diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md
index a65f53b4b..81dc26a39 100644
--- a/doc/manual/src/command-ref/nix-build.md
+++ b/doc/manual/src/command-ref/nix-build.md
@@ -46,7 +46,7 @@ expression to a low-level store derivation) and [`nix-store
 
 All options not listed here are passed to `nix-store
 --realise`, except for `--arg` and `--attr` / `-A` which are passed to
-`nix-instantiate`. See also [???](#sec-common-options).
+`nix-instantiate`.
 
   - `--no-out-link`  
     Do not create a symlink to the output path. Note that as a result
diff --git a/doc/manual/src/command-ref/nix-channel.md b/doc/manual/src/command-ref/nix-channel.md
index 6b4bd2459..ea3a57e69 100644
--- a/doc/manual/src/command-ref/nix-channel.md
+++ b/doc/manual/src/command-ref/nix-channel.md
@@ -13,7 +13,6 @@ Title: nix-channel
 A Nix channel is a mechanism that allows you to automatically stay
 up-to-date with a set of pre-built Nix expressions. A Nix channel is
 just a URL that points to a place containing a set of Nix expressions.
-See also [???](#sec-channels).
 
 To see the list of official NixOS channels, visit
 <https://nixos.org/channels>.
diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md
index cf688100e..ab1d10c08 100644
--- a/doc/manual/src/command-ref/nix-env.md
+++ b/doc/manual/src/command-ref/nix-env.md
@@ -66,7 +66,7 @@ match. Here are some examples:
 
 This section lists the options that are common to all operations. These
 options are allowed for every subcommand, though they may not always
-have an effect. See also [???](#sec-common-options).
+have an effect.
 
   - `--file` / `-f` *path*  
     Specifies the Nix expression (designated below as the *active Nix
diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md
index b6bbbe80a..ca9ef1fc9 100644
--- a/doc/manual/src/command-ref/nix-instantiate.md
+++ b/doc/manual/src/command-ref/nix-instantiate.md
@@ -30,8 +30,6 @@ the resulting store derivations are printed on standard output.
 If *files* is the character `-`, then a Nix expression will be read from
 standard input.
 
-See also [???](#sec-common-options) for a list of common options.
-
 # Options
 
   - `--add-root` *path*; `--indirect`  
diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md
index d6dbb6e26..492351867 100644
--- a/doc/manual/src/command-ref/nix-shell.md
+++ b/doc/manual/src/command-ref/nix-shell.md
@@ -50,7 +50,7 @@ will cause `nix-shell` to print `Hello shell`.
 
 All options not listed here are passed to `nix-store
 --realise`, except for `--arg` and `--attr` / `-A` which are passed to
-`nix-instantiate`. See also [???](#sec-common-options).
+`nix-instantiate`.
 
   - `--command` *cmd*  
     In the environment of the derivation, run the shell command *cmd*.
diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md
index a098beb1e..b15340fde 100644
--- a/doc/manual/src/command-ref/nix-store.md
+++ b/doc/manual/src/command-ref/nix-store.md
@@ -23,16 +23,15 @@ subcommand to be performed. These are documented below.
 
 This section lists the options that are common to all operations. These
 options are allowed for every subcommand, though they may not always
-have an effect. See also [???](#sec-common-options) for a list of common
-options.
+have an effect.
 
   - `--add-root` *path*  
     Causes the result of a realisation (`--realise` and
     `--force-realise`) to be registered as a root of the garbage
-    collector(see [???](#ssec-gc-roots)). The root is stored in *path*,
-    which must be inside a directory that is scanned for roots by the
-    garbage collector (i.e., typically in a subdirectory of
-    `/nix/var/nix/gcroots/`) *unless* the `--indirect` flag is used.
+    collector. The root is stored in *path*, which must be inside a
+    directory that is scanned for roots by the garbage collector
+    (i.e., typically in a subdirectory of `/nix/var/nix/gcroots/`)
+    *unless* the `--indirect` flag is used.
 
     If there are multiple results, then multiple symlinks will be
     created by sequentially numbering symlinks beyond the first one
@@ -209,8 +208,7 @@ The following suboperations may be specified:
 
   - `--print-roots`  
     This operation prints on standard output the set of roots used by
-    the garbage collector. What constitutes a root is described in
-    [???](#ssec-gc-roots).
+    the garbage collector.
 
   - `--print-live`  
     This operation prints on standard output the set of “live” store
diff --git a/doc/manual/src/expressions/arguments-variables.md b/doc/manual/src/expressions/arguments-variables.md
index 436ae559d..2956f98f1 100644
--- a/doc/manual/src/expressions/arguments-variables.md
+++ b/doc/manual/src/expressions/arguments-variables.md
@@ -1,11 +1,12 @@
 # Arguments and Variables
 
-The Nix expression in [???](#ex-hello-nix) is a function; it is missing
-some arguments that have to be filled in somewhere. In the Nix Packages
-collection this is done in the file `pkgs/top-level/all-packages.nix`,
-where all Nix expressions for packages are imported and called with the
-appropriate arguments. Here are some fragments of `all-packages.nix`,
-with annotations of what they mean:
+The [Nix expression for GNU Hello](expression-syntax.md) is a
+function; it is missing some arguments that have to be filled in
+somewhere. In the Nix Packages collection this is done in the file
+`pkgs/top-level/all-packages.nix`, where all Nix expressions for
+packages are imported and called with the appropriate arguments. Here
+are some fragments of `all-packages.nix`, with annotations of what
+they mean:
 
     ...
     
@@ -35,9 +36,10 @@ with annotations of what they mean:
 
 2.  Here we *import* the Nix expression for GNU Hello. The import
     operation just loads and returns the specified Nix expression. In
-    fact, we could just have put the contents of [???](#ex-hello-nix) in
-    `all-packages.nix` at this point. That would be completely
-    equivalent, but it would make the file rather bulky.
+    fact, we could just have put the contents of the Nix expression
+    for GNU Hello in `all-packages.nix` at this point. That would be
+    completely equivalent, but it would make `all-packages.nix` rather
+    bulky.
     
     Note that we refer to `../applications/misc/hello/ex-1`, not
     `../applications/misc/hello/ex-1/default.nix`. When you try to
@@ -54,7 +56,7 @@ with annotations of what they mean:
     The result of this function call is an actual derivation that can be
     built by Nix (since when we fill in the arguments of the function,
     what we get is its body, which is the call to `stdenv.mkDerivation`
-    in [???](#ex-hello-nix)).
+    in the [Nix expression for GNU Hello](expression-syntax.md)).
     
     > **Note**
     > 
diff --git a/doc/manual/src/expressions/build-script.md b/doc/manual/src/expressions/build-script.md
index 57222de85..e0dda56f8 100644
--- a/doc/manual/src/expressions/build-script.md
+++ b/doc/manual/src/expressions/build-script.md
@@ -25,10 +25,10 @@ steps to elucidate what a builder does. It performs the following steps:
     
     So the first step is to set up the environment. This is done by
     calling the `setup` script of the standard environment. The
-    environment variable `stdenv` points to the location of the standard
-    environment being used. (It wasn't specified explicitly as an
-    attribute in [???](#ex-hello-nix), but `mkDerivation` adds it
-    automatically.)
+    environment variable `stdenv` points to the location of the
+    standard environment being used. (It wasn't specified explicitly
+    as an attribute in Hello's Nix expression, but `mkDerivation` adds
+    it automatically.)
 
 2.  Since Hello needs Perl, we have to make sure that Perl is in the
     `PATH`. The `perl` environment variable points to the location of
diff --git a/doc/manual/src/expressions/builder-syntax.md b/doc/manual/src/expressions/builder-syntax.md
deleted file mode 100644
index 916159d40..000000000
--- a/doc/manual/src/expressions/builder-syntax.md
+++ /dev/null
@@ -1,72 +0,0 @@
-# Builder Syntax
-
-    source $stdenv/setup 
-    
-    PATH=$perl/bin:$PATH 
-    
-    tar xvfz $src 
-    cd hello-*
-    ./configure --prefix=$out 
-    make 
-    make install
-
-[example\_title](#ex-hello-builder) shows the builder referenced from
-Hello's Nix expression (stored in
-`pkgs/applications/misc/hello/ex-1/builder.sh`). The builder can
-actually be made a lot shorter by using the *generic builder* functions
-provided by `stdenv`, but here we write out the build steps to elucidate
-what a builder does. It performs the following steps:
-
-  - When Nix runs a builder, it initially completely clears the
-    environment (except for the attributes declared in the derivation).
-    For instance, the `PATH` variable is empty\[1\]. This is done to
-    prevent undeclared inputs from being used in the build process. If
-    for example the `PATH` contained `/usr/bin`, then you might
-    accidentally use `/usr/bin/gcc`.
-    
-    So the first step is to set up the environment. This is done by
-    calling the `setup` script of the standard environment. The
-    environment variable `stdenv` points to the location of the standard
-    environment being used. (It wasn't specified explicitly as an
-    attribute in [???](#ex-hello-nix), but `mkDerivation` adds it
-    automatically.)
-
-  - Since Hello needs Perl, we have to make sure that Perl is in the
-    `PATH`. The `perl` environment variable points to the location of
-    the Perl package (since it was passed in as an attribute to the
-    derivation), so `$perl/bin` is the directory containing the Perl
-    interpreter.
-
-  - Now we have to unpack the sources. The `src` attribute was bound to
-    the result of fetching the Hello source tarball from the network, so
-    the `src` environment variable points to the location in the Nix
-    store to which the tarball was downloaded. After unpacking, we `cd`
-    to the resulting source directory.
-    
-    The whole build is performed in a temporary directory created in
-    `/tmp`, by the way. This directory is removed after the builder
-    finishes, so there is no need to clean up the sources afterwards.
-    Also, the temporary directory is always newly created, so you don't
-    have to worry about files from previous builds interfering with the
-    current build.
-
-  - GNU Hello is a typical Autoconf-based package, so we first have to
-    run its `configure` script. In Nix every package is stored in a
-    separate location in the Nix store, for instance
-    `/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix
-    computes this path by cryptographically hashing all attributes of
-    the derivation. The path is passed to the builder through the `out`
-    environment variable. So here we give `configure` the parameter
-    `--prefix=$out` to cause Hello to be installed in the expected
-    location.
-
-  - Finally we build Hello (`make`) and install it into the location
-    specified by `out` (`make install`).
-
-If you are wondering about the absence of error checking on the result
-of various commands called in the builder: this is because the shell
-script is evaluated with Bash's `-e` option, which causes the script to
-be aborted if any command fails without an error check.
-
-1.  Actually, it's initialised to `/path-not-set` to prevent Bash from
-    setting it to a default value.
diff --git a/doc/manual/src/expressions/builtins.md b/doc/manual/src/expressions/builtins.md
index 8f19c692a..3c9bb4533 100644
--- a/doc/manual/src/expressions/builtins.md
+++ b/doc/manual/src/expressions/builtins.md
@@ -83,7 +83,7 @@ For instance, `derivation` is also available as `builtins.derivation`.
     its elements or attributes are also evaluated recursively.
 
   - `derivation` *attrs*; `builtins.derivation` *attrs*  
-    `derivation` is described in [???](#ssec-derivation).
+    `derivation` is described in [its own section](derivations.md).
 
   - `dirOf` *s*; `builtins.dirOf` *s*  
     Return the directory part of the string *s*, that is, everything
@@ -233,8 +233,8 @@ For instance, `derivation` is also available as `builtins.derivation`.
         
         > **Note**
         > 
-        > Nix will refetch the branch in accordance to
-        > [???](#conf-tarball-ttl).
+        > Nix will refetch the branch in accordance with
+        > the option `tarball-ttl`.
         
         > **Note**
         > 
@@ -351,19 +351,18 @@ For instance, `derivation` is also available as `builtins.derivation`.
 
   - `import` *path*; `builtins.import` *path*  
     Load, parse and return the Nix expression in the file *path*. If
-    *path* is a directory, the file ` default.nix
-                     ` in that directory is loaded. Evaluation aborts if the file
-    doesn’t exist or contains an incorrect Nix expression. `import`
-    implements Nix’s module system: you can put any Nix expression (such
-    as a set or a function) in a separate file, and use it from Nix
-    expressions in other files.
+    *path* is a directory, the file ` default.nix ` in that directory
+    is loaded. Evaluation aborts if the file doesn’t exist or contains
+    an incorrect Nix expression. `import` implements Nix’s module
+    system: you can put any Nix expression (such as a set or a
+    function) in a separate file, and use it from Nix expressions in
+    other files.
     
     > **Note**
     > 
     > Unlike some languages, `import` is a regular function in Nix.
-    > Paths using the angle bracket syntax (e.g., `
-    >     >     >     >     > import` *\<foo\>*) are normal path values (see
-    > [???](#ssec-values)).
+    > Paths using the angle bracket syntax (e.g., `import` *\<foo\>*)
+    > are [normal path values](language-values.md).
     
     A Nix expression loaded by `import` must not contain any *free
     variables* (identifiers that are not defined in the Nix expression
@@ -643,11 +642,12 @@ For instance, `derivation` is also available as `builtins.derivation`.
     (which is not the case for `abort`).
 
   - `builtins.toFile` *name* *s*  
-    Store the string *s* in a file in the Nix store and return its path.
-    The file has suffix *name*. This file can be used as an input to
-    derivations. One application is to write builders “inline”. For
-    instance, the following Nix expression combines [???](#ex-hello-nix)
-    and [???](#ex-hello-builder) into one file:
+    Store the string *s* in a file in the Nix store and return its
+    path.  The file has suffix *name*. This file can be used as an
+    input to derivations. One application is to write builders
+    “inline”. For instance, the following Nix expression combines the
+    [Nix expression for GNU Hello](expression-syntax.md) and its
+    [build script](build-script.md) into one file:
     
         { stdenv, fetchurl, perl }:
         
@@ -688,8 +688,9 @@ For instance, `derivation` is also available as `builtins.derivation`.
       ";
     ```
     
-    Note that `${configFile}` is an antiquotation (see
-    [???](#ssec-values)), so the result of the expression `configFile`
+    Note that `${configFile}` is an
+    [antiquotation](language-values.md), so the result of the
+    expression `configFile`
     (i.e., a path like `/nix/store/m7p7jfny445k...-foo.conf`) will be
     spliced into the resulting string.
     
@@ -786,17 +787,17 @@ For instance, `derivation` is also available as `builtins.derivation`.
     container contains a number of servlets (`*.war` files) each
     exported under a specific URI prefix. So the servlet configuration
     is a list of sets containing the `path` and `war` of the servlet
-    ([???](#ex-toxml-co-servlets)). This kind of information is
-    difficult to communicate with the normal method of passing
-    information through an environment variable, which just concatenates
-    everything together into a string (which might just work in this
-    case, but wouldn’t work if fields are optional or contain lists
-    themselves). Instead the Nix expression is converted to an XML
-    representation with `toXML`, which is unambiguous and can easily be
-    processed with the appropriate tools. For instance, in the example
-    an XSLT stylesheet (at point ②) is applied to it (at point ①) to
-    generate the XML configuration file for the Jetty server. The XML
-    representation produced at point ③ by `toXML` is as follows:
+    (①). This kind of information is difficult to communicate with the
+    normal method of passing information through an environment
+    variable, which just concatenates everything together into a
+    string (which might just work in this case, but wouldn’t work if
+    fields are optional or contain lists themselves). Instead the Nix
+    expression is converted to an XML representation with `toXML`,
+    which is unambiguous and can easily be processed with the
+    appropriate tools. For instance, in the example an XSLT stylesheet
+    (at point ②) is applied to it (at point ①) to generate the XML
+    configuration file for the Jetty server. The XML representation
+    produced at point ③ by `toXML` is as follows:
     
         <?xml version='1.0' encoding='utf-8'?>
         <expr>
@@ -820,10 +821,10 @@ For instance, `derivation` is also available as `builtins.derivation`.
           </list>
         </expr>
     
-    Note that [???](#ex-toxml) uses the `toFile` built-in to write the
-    builder and the stylesheet “inline” in the Nix expression. The path
-    of the stylesheet is spliced into the builder using the syntax
-    `xsltproc ${stylesheet}`.
+    Note that we used the `toFile` built-in to write the builder and
+    the stylesheet “inline” in the Nix expression. The path of the
+    stylesheet is spliced into the builder using the syntax `xsltproc
+    ${stylesheet}`.
 
   - `builtins.trace` *e1* *e2*  
     Evaluate *e1* and print its abstract syntax representation on
diff --git a/doc/manual/src/expressions/derivations.md b/doc/manual/src/expressions/derivations.md
index 4cb233e2e..0e5656b5b 100644
--- a/doc/manual/src/expressions/derivations.md
+++ b/doc/manual/src/expressions/derivations.md
@@ -9,8 +9,9 @@ the attributes of which specify the inputs of the build.
     `"x86_64-darwin"`. (To figure out your system type, run `nix -vv
     --version`.) The build can only be performed on a machine and
     operating system matching the system type. (Nix can automatically
-    forward builds for other platforms by forwarding them to other
-    machines; see [???](#chap-distributed-builds).)
+    [forward builds for other
+    platforms](../advanced-topics/distributed-builds.md) by forwarding
+    them to other machines.)
 
   - There must be an attribute named `name` whose value must be a
     string. This is used as a symbolic name for the package by
diff --git a/doc/manual/src/expressions/expression-syntax.md b/doc/manual/src/expressions/expression-syntax.md
index 2abe6ac6e..e3432b577 100644
--- a/doc/manual/src/expressions/expression-syntax.md
+++ b/doc/manual/src/expressions/expression-syntax.md
@@ -61,9 +61,10 @@ elements (referenced from the figure by number):
     sometimes be omitted, in which case `mkDerivation` will fill in a
     default builder (which does a `configure; make; make install`, in
     essence). Hello is sufficiently simple that the default builder
-    would suffice, but in this case, we will show an actual builder for
-    educational purposes. The value `./builder.sh` refers to the shell
-    script shown in [???](#ex-hello-builder), discussed below.
+    would suffice, but in this case, we will show an actual builder
+    for educational purposes. The value `./builder.sh` refers to the
+    shell script shown in the [next section](build-script.md),
+    discussed below.
 
 5.  The builder has to know what the sources of the package are. Here,
     the attribute `src` is bound to the result of a call to the
diff --git a/doc/manual/src/expressions/generic-builder.md b/doc/manual/src/expressions/generic-builder.md
index 6942abe70..43275dbf7 100644
--- a/doc/manual/src/expressions/generic-builder.md
+++ b/doc/manual/src/expressions/generic-builder.md
@@ -1,7 +1,7 @@
 # Generic Builder Syntax
 
-Recall from [???](#ex-hello-builder) that the builder looked something
-like this:
+Recall that the [build script for GNU Hello](build-script.md) looked
+something like this:
 
     PATH=$perl/bin:$PATH
     tar xvfz $src
@@ -37,11 +37,10 @@ Here is what each line means:
 2.  The function `genericBuild` is defined in the file `$stdenv/setup`.
 
 3.  The final step calls the shell function `genericBuild`, which
-    performs the steps that were done explicitly in
-    [???](#ex-hello-builder). The generic builder is smart enough to
-    figure out whether to unpack the sources using `gzip`, `bzip2`, etc.
-    It can be customised in many ways; see the Nixpkgs manual for
-    details.
+    performs the steps that were done explicitly in the previous build
+    script. The generic builder is smart enough to figure out whether
+    to unpack the sources using `gzip`, `bzip2`, etc.  It can be
+    customised in many ways; see the Nixpkgs manual for details.
 
 Discerning readers will note that the `buildInputs` could just as well
 have been set in the Nix expression, like this:
diff --git a/doc/manual/src/expressions/language-operators.md b/doc/manual/src/expressions/language-operators.md
index b124a2417..1d787ffe3 100644
--- a/doc/manual/src/expressions/language-operators.md
+++ b/doc/manual/src/expressions/language-operators.md
@@ -1,8 +1,7 @@
 # Operators
 
-[table\_title](#table-operators) lists the operators in the Nix
-expression language, in order of precedence (from strongest to weakest
-binding).
+The table below lists the operators in the Nix expression language, in
+order of precedence (from strongest to weakest binding).
 
 | Name                     | Syntax                              | Associativity | Description                                                                                                                                                                                                                   | Precedence |
 | ------------------------ | ----------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
@@ -28,5 +27,3 @@ binding).
 | Logical OR               | *e1* `\|\|` *e2*                    | left          | Logical OR.                                                                                                                                                                                                                   | 13         |
 | Logical Implication      | *e1* `->` *e2*                      | none          | Logical implication (equivalent to `!e1 \|\|
         e2`).                                                                                                                                                                    | 14         |
-
-Operators
diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index c8bdf4fd2..56af9cd85 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -3,7 +3,7 @@
   - derivation  
     A description of a build action. The result of a derivation is a
     store object. Derivations are typically specified in Nix expressions
-    using the [`derivation` primitive](#ssec-derivation). These are
+    using the [`derivation` primitive](expressions/derivations.md). These are
     translated into low-level *store derivations* (implicitly by
     `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
 
@@ -53,20 +53,19 @@
     paths.
 
   - reachable  
-    A store path `Q` is reachable from another store path `P` if `Q` is
-    in the [closure](#gloss-closure) of the
-    [references](#gloss-reference) relation.
+    A store path `Q` is reachable from another store path `P` if `Q`
+    is in the *closure* of the *references* relation.
 
   - closure  
     The closure of a store path is the set of store paths that are
     directly or indirectly “reachable” from that store path; that is,
-    it’s the closure of the path under the
-    [references](#gloss-reference) relation. For a package, the closure
-    of its derivation is equivalent to the build-time dependencies,
-    while the closure of its output path is equivalent to its runtime
-    dependencies. For correct deployment it is necessary to deploy whole
-    closures, since otherwise at runtime files could be missing. The
-    command `nix-store -qR` prints out closures of store paths.
+    it’s the closure of the path under the *references* relation. For
+    a package, the closure of its derivation is equivalent to the
+    build-time dependencies, while the closure of its output path is
+    equivalent to its runtime dependencies. For correct deployment it
+    is necessary to deploy whole closures, since otherwise at runtime
+    files could be missing. The command `nix-store -qR` prints out
+    closures of store paths.
     
     As an example, if the store object at path `P` contains a reference
     to path `Q`, then `Q` is in the closure of `P`. Further, if `Q`
@@ -76,7 +75,7 @@
     A store path produced by a derivation.
 
   - deriver  
-    The deriver of an [output path](#gloss-output-path) is the store
+    The deriver of an *output path* is the store
     derivation that built it.
 
   - validity  
@@ -87,16 +86,15 @@
   - user environment  
     An automatically generated store object that consists of a set of
     symlinks to “active” applications, i.e., other store paths. These
-    are generated automatically by [`nix-env`](#sec-nix-env). See
-    [???](#sec-profiles).
+    are generated automatically by
+    [`nix-env`](command-ref/nix-env.md). See *profiles*.
 
   - profile  
-    A symlink to the current [user environment](#gloss-user-env) of a
-    user, e.g., `/nix/var/nix/profiles/default`.
+    A symlink to the current *user environment* of a user, e.g.,
+    `/nix/var/nix/profiles/default`.
 
   - NAR  
     A *N*ix *AR*chive. This is a serialisation of a path in the Nix
-    store. It can contain regular files, directories and symbolic links.
-    NARs are generated and unpacked using `nix-store --dump` and
-    `nix-store
-            --restore`.
+    store. It can contain regular files, directories and symbolic
+    links.  NARs are generated and unpacked using `nix-store --dump`
+    and `nix-store --restore`.
diff --git a/doc/manual/src/package-management/basic-package-mgmt.md b/doc/manual/src/package-management/basic-package-mgmt.md
index d9c34afc6..8edaca6b0 100644
--- a/doc/manual/src/package-management/basic-package-mgmt.md
+++ b/doc/manual/src/package-management/basic-package-mgmt.md
@@ -24,11 +24,11 @@ or completely new ones.)
 
 You can manually download the latest version of Nixpkgs from
 <http://nixos.org/nixpkgs/download.html>. However, it’s much more
-convenient to use the Nixpkgs *channel*, since it makes it easy to stay
-up to date with new versions of Nixpkgs. (Channels are described in more
-detail in [???](#sec-channels).) Nixpkgs is automatically added to your
-list of “subscribed” channels when you install Nix. If this is not the
-case for some reason, you can add it as follows:
+convenient to use the Nixpkgs [*channel*](channels.md), since it makes
+it easy to stay up to date with new versions of Nixpkgs. Nixpkgs is
+automatically added to your list of “subscribed” channels when you
+install Nix. If this is not the case for some reason, you can add it
+as follows:
 
     $ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
     $ nix-channel --update
diff --git a/doc/manual/src/package-management/copy-closure.md b/doc/manual/src/package-management/copy-closure.md
index d78b77e36..d3fac4d76 100644
--- a/doc/manual/src/package-management/copy-closure.md
+++ b/doc/manual/src/package-management/copy-closure.md
@@ -8,7 +8,7 @@ dependencies:
 
     $ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)
 
-See [???](#sec-nix-copy-closure) for details.
+See the [manpage for `nix-copy-closure`](../command-ref/nix-copy-closure.md) for details.
 
 With `nix-store
 --export` and `nix-store --import` you can write the closure of a store
diff --git a/doc/manual/src/package-management/package-management.md b/doc/manual/src/package-management/package-management.md
index a2d078c16..bd26a09ab 100644
--- a/doc/manual/src/package-management/package-management.md
+++ b/doc/manual/src/package-management/package-management.md
@@ -1,4 +1,5 @@
-This chapter discusses how to do package management with Nix, i.e., how
-to obtain, install, upgrade, and erase packages. This is the “user’s”
-perspective of the Nix system — people who want to *create* packages
-should consult [???](#chap-writing-nix-expressions).
+This chapter discusses how to do package management with Nix, i.e.,
+how to obtain, install, upgrade, and erase packages. This is the
+“user’s” perspective of the Nix system — people who want to *create*
+packages should consult the [chapter on writing Nix
+expressions](../expressions/writing-nix-expressions.md).
diff --git a/doc/manual/src/package-management/profiles.md b/doc/manual/src/package-management/profiles.md
index 1950c3121..f3786072d 100644
--- a/doc/manual/src/package-management/profiles.md
+++ b/doc/manual/src/package-management/profiles.md
@@ -104,8 +104,7 @@ These commands switch to the `my-profile` and default profile,
 respectively. If the profile doesn’t exist, it will be created
 automatically. You should be careful about storing a profile in another
 location than the `profiles` directory, since otherwise it might not be
-used as a root of the garbage collector (see
-[???](#sec-garbage-collection)).
+used as a root of the [garbage collector](garbage-collection.md).
 
 All `nix-env` operations work on the profile pointed to by
 `~/.nix-profile`, but you can override this using the `--profile` option