Fix some dangling references

8 files changed, 66 insertions, 137 deletions

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