Fix some dangling references

3 files changed, 28 insertions, 34 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=