Merge remote-tracking branch 'origin/master' into coerce-string

27 files changed, 1542 insertions, 554 deletions

diff --git a/doc/manual/book.toml b/doc/manual/book.toml
index 5f78a7614..46ced7ff7 100644
--- a/doc/manual/book.toml
+++ b/doc/manual/book.toml
@@ -1,6 +1,11 @@
+[book]
+title = "Nix Reference Manual"
+
 [output.html]
 additional-css = ["custom.css"]
 additional-js = ["redirects.js"]
+edit-url-template = "https://github.com/NixOS/nix/tree/master/doc/manual/{path}"
+git-repository-url = "https://github.com/NixOS/nix"
 
 [preprocessor.anchors]
 renderers = ["html"]
diff --git a/doc/manual/generate-builtins.nix b/doc/manual/generate-builtins.nix
index 6c8b88da2..115bb3f94 100644
--- a/doc/manual/generate-builtins.nix
+++ b/doc/manual/generate-builtins.nix
@@ -1,16 +1,20 @@
-with builtins;
-with import ./utils.nix;
+builtinsDump:
+let
+  showBuiltin = name:
+    let
+      inherit (builtinsDump.${name}) doc args;
+    in
+    ''
+      <dt id="builtins-${name}">
+        <a href="#builtins-${name}"><code>${name} ${listArgs args}</code></a>
+      </dt>
+      <dd>
 
-builtins:
+        ${doc}
+
+      </dd>
+    '';
+  listArgs = args: builtins.concatStringsSep " " (map (s: "<var>${s}</var>") args);
+in
+with builtins; concatStringsSep "\n" (map showBuiltin (attrNames builtinsDump))
 
-concatStrings (map
-  (name:
-    let builtin = builtins.${name}; in
-    "<dt id=\"builtins-${name}\"><a href=\"#builtins-${name}\"><code>${name} "
-    + concatStringsSep " " (map (s: "<var>${s}</var>") builtin.args)
-    + "</code></a></dt>"
-    + "<dd>\n\n"
-    + builtin.doc
-    + "\n\n</dd>"
-  )
-  (attrNames builtins))
diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
index 057719e34..8c7c4d358 100644
--- a/doc/manual/generate-manpage.nix
+++ b/doc/manual/generate-manpage.nix
@@ -99,6 +99,7 @@ let
     in [ cmd ] ++ concatMap subcommand (attrNames details.commands or {});
 
   parsedToplevel = builtins.fromJSON toplevel;
+  
   manpages = processCommand {
     command = "nix";
     details = parsedToplevel;
diff --git a/doc/manual/generate-options.nix b/doc/manual/generate-options.nix
index 2d586fa1b..a4ec36477 100644
--- a/doc/manual/generate-options.nix
+++ b/doc/manual/generate-options.nix
@@ -1,29 +1,41 @@
-with builtins;
-with import ./utils.nix;
+let
+  inherit (builtins) attrNames concatStringsSep isAttrs isBool;
+  inherit (import ./utils.nix) concatStrings squash splitLines;
+in
 
-options:
+optionsInfo:
+let
+  showOption = name:
+    let
+      inherit (optionsInfo.${name}) description documentDefault defaultValue aliases;
+      result = squash ''
+          - <span id="conf-${name}">[`${name}`](#conf-${name})</span>
 
-concatStrings (map
-  (name:
-    let option = options.${name}; in
-    "  - [`${name}`](#conf-${name})"
-    + "<p id=\"conf-${name}\"></p>\n\n"
-    + concatStrings (map (s: "    ${s}\n") (splitLines option.description)) + "\n\n"
-    + (if option.documentDefault
-       then "    **Default:** " + (
-       if option.value == "" || option.value == []
-       then "*empty*"
-       else if isBool option.value
-       then (if option.value then "`true`" else "`false`")
-       else
-         # n.b. a StringMap value type is specified as a string, but
-         # this shows the value type.  The empty stringmap is "null" in
-         # JSON, but that converts to "{ }" here.
-         (if isAttrs option.value then "`\"\"`"
-          else "`" + toString option.value + "`")) + "\n\n"
-       else "    **Default:** *machine-specific*\n")
-    + (if option.aliases != []
-       then "    **Deprecated alias:** " + (concatStringsSep ", " (map (s: "`${s}`") option.aliases)) + "\n\n"
-       else "")
-    )
-  (attrNames options))
+          ${indent "  " body}
+        '';
+      # separate body to cleanly handle indentation
+      body = ''
+          ${description}
+
+          **Default:** ${showDefault documentDefault defaultValue}
+
+          ${showAliases aliases}
+        '';
+      showDefault = documentDefault: defaultValue:
+        if documentDefault then
+          # a StringMap value type is specified as a string, but
+          # this shows the value type. The empty stringmap is `null` in
+          # JSON, but that converts to `{ }` here.
+          if defaultValue == "" || defaultValue == [] || isAttrs defaultValue
+            then "*empty*"
+            else if isBool defaultValue then
+              if defaultValue then "`true`" else "`false`"
+            else "`${toString defaultValue}`"
+        else "*machine-specific*";
+      showAliases = aliases:
+          if aliases == [] then "" else
+            "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
+      indent = prefix: s:
+        concatStringsSep "\n" (map (x: if x == "" then x else "${prefix}${x}") (splitLines s));
+      in result;
+in concatStrings (map showOption (attrNames optionsInfo))
diff --git a/doc/manual/local.mk b/doc/manual/local.mk
index 486dbd7a2..c0f69e00f 100644
--- a/doc/manual/local.mk
+++ b/doc/manual/local.mk
@@ -29,19 +29,19 @@ nix-eval = $(dummy-env) $(bindir)/nix eval --experimental-features nix-command -
 $(d)/%.1: $(d)/src/command-ref/%.md
 	@printf "Title: %s\n\n" "$$(basename $@ .1)" > $^.tmp
 	@cat $^ >> $^.tmp
-	$(trace-gen) lowdown -sT man -M section=1 $^.tmp -o $@
+	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@
 	@rm $^.tmp
 
 $(d)/%.8: $(d)/src/command-ref/%.md
 	@printf "Title: %s\n\n" "$$(basename $@ .8)" > $^.tmp
 	@cat $^ >> $^.tmp
-	$(trace-gen) lowdown -sT man -M section=8 $^.tmp -o $@
+	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=8 $^.tmp -o $@
 	@rm $^.tmp
 
 $(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md
 	@printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp
 	@cat $^ >> $^.tmp
-	$(trace-gen) lowdown -sT man -M section=5 $^.tmp -o $@
+	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
 	@rm $^.tmp
 
 $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli
diff --git a/doc/manual/redirects.js b/doc/manual/redirects.js
index 167e221b8..69f75d3a0 100644
--- a/doc/manual/redirects.js
+++ b/doc/manual/redirects.js
@@ -1,330 +1,421 @@
-// Redirects from old DocBook manual.
-var redirects = {
-  "#part-advanced-topics": "advanced-topics/advanced-topics.html",
-  "#chap-tuning-cores-and-jobs": "advanced-topics/cores-vs-jobs.html",
-  "#chap-diff-hook": "advanced-topics/diff-hook.html",
-  "#check-dirs-are-unregistered": "advanced-topics/diff-hook.html#check-dirs-are-unregistered",
-  "#chap-distributed-builds": "advanced-topics/distributed-builds.html",
-  "#chap-post-build-hook": "advanced-topics/post-build-hook.html",
-  "#chap-post-build-hook-caveats": "advanced-topics/post-build-hook.html#implementation-caveats",
-  "#part-command-ref": "command-ref/command-ref.html",
-  "#conf-allow-import-from-derivation": "command-ref/conf-file.html#conf-allow-import-from-derivation",
-  "#conf-allow-new-privileges": "command-ref/conf-file.html#conf-allow-new-privileges",
-  "#conf-allowed-uris": "command-ref/conf-file.html#conf-allowed-uris",
-  "#conf-allowed-users": "command-ref/conf-file.html#conf-allowed-users",
-  "#conf-auto-optimise-store": "command-ref/conf-file.html#conf-auto-optimise-store",
-  "#conf-binary-cache-public-keys": "command-ref/conf-file.html#conf-binary-cache-public-keys",
-  "#conf-binary-caches": "command-ref/conf-file.html#conf-binary-caches",
-  "#conf-build-compress-log": "command-ref/conf-file.html#conf-build-compress-log",
-  "#conf-build-cores": "command-ref/conf-file.html#conf-build-cores",
-  "#conf-build-extra-chroot-dirs": "command-ref/conf-file.html#conf-build-extra-chroot-dirs",
-  "#conf-build-extra-sandbox-paths": "command-ref/conf-file.html#conf-build-extra-sandbox-paths",
-  "#conf-build-fallback": "command-ref/conf-file.html#conf-build-fallback",
-  "#conf-build-max-jobs": "command-ref/conf-file.html#conf-build-max-jobs",
-  "#conf-build-max-log-size": "command-ref/conf-file.html#conf-build-max-log-size",
-  "#conf-build-max-silent-time": "command-ref/conf-file.html#conf-build-max-silent-time",
-  "#conf-build-repeat": "command-ref/conf-file.html#conf-build-repeat",
-  "#conf-build-timeout": "command-ref/conf-file.html#conf-build-timeout",
-  "#conf-build-use-chroot": "command-ref/conf-file.html#conf-build-use-chroot",
-  "#conf-build-use-sandbox": "command-ref/conf-file.html#conf-build-use-sandbox",
-  "#conf-build-use-substitutes": "command-ref/conf-file.html#conf-build-use-substitutes",
-  "#conf-build-users-group": "command-ref/conf-file.html#conf-build-users-group",
-  "#conf-builders": "command-ref/conf-file.html#conf-builders",
-  "#conf-builders-use-substitutes": "command-ref/conf-file.html#conf-builders-use-substitutes",
-  "#conf-compress-build-log": "command-ref/conf-file.html#conf-compress-build-log",
-  "#conf-connect-timeout": "command-ref/conf-file.html#conf-connect-timeout",
-  "#conf-cores": "command-ref/conf-file.html#conf-cores",
-  "#conf-diff-hook": "command-ref/conf-file.html#conf-diff-hook",
-  "#conf-enforce-determinism": "command-ref/conf-file.html#conf-enforce-determinism",
-  "#conf-env-keep-derivations": "command-ref/conf-file.html#conf-env-keep-derivations",
-  "#conf-extra-binary-caches": "command-ref/conf-file.html#conf-extra-binary-caches",
-  "#conf-extra-platforms": "command-ref/conf-file.html#conf-extra-platforms",
-  "#conf-extra-sandbox-paths": "command-ref/conf-file.html#conf-extra-sandbox-paths",
-  "#conf-extra-substituters": "command-ref/conf-file.html#conf-extra-substituters",
-  "#conf-fallback": "command-ref/conf-file.html#conf-fallback",
-  "#conf-fsync-metadata": "command-ref/conf-file.html#conf-fsync-metadata",
-  "#conf-gc-keep-derivations": "command-ref/conf-file.html#conf-gc-keep-derivations",
-  "#conf-gc-keep-outputs": "command-ref/conf-file.html#conf-gc-keep-outputs",
-  "#conf-hashed-mirrors": "command-ref/conf-file.html#conf-hashed-mirrors",
-  "#conf-http-connections": "command-ref/conf-file.html#conf-http-connections",
-  "#conf-keep-build-log": "command-ref/conf-file.html#conf-keep-build-log",
-  "#conf-keep-derivations": "command-ref/conf-file.html#conf-keep-derivations",
-  "#conf-keep-env-derivations": "command-ref/conf-file.html#conf-keep-env-derivations",
-  "#conf-keep-outputs": "command-ref/conf-file.html#conf-keep-outputs",
-  "#conf-max-build-log-size": "command-ref/conf-file.html#conf-max-build-log-size",
-  "#conf-max-free": "command-ref/conf-file.html#conf-max-free",
-  "#conf-max-jobs": "command-ref/conf-file.html#conf-max-jobs",
-  "#conf-max-silent-time": "command-ref/conf-file.html#conf-max-silent-time",
-  "#conf-min-free": "command-ref/conf-file.html#conf-min-free",
-  "#conf-narinfo-cache-negative-ttl": "command-ref/conf-file.html#conf-narinfo-cache-negative-ttl",
-  "#conf-narinfo-cache-positive-ttl": "command-ref/conf-file.html#conf-narinfo-cache-positive-ttl",
-  "#conf-netrc-file": "command-ref/conf-file.html#conf-netrc-file",
-  "#conf-plugin-files": "command-ref/conf-file.html#conf-plugin-files",
-  "#conf-post-build-hook": "command-ref/conf-file.html#conf-post-build-hook",
-  "#conf-pre-build-hook": "command-ref/conf-file.html#conf-pre-build-hook",
-  "#conf-repeat": "command-ref/conf-file.html#conf-repeat",
-  "#conf-require-sigs": "command-ref/conf-file.html#conf-require-sigs",
-  "#conf-restrict-eval": "command-ref/conf-file.html#conf-restrict-eval",
-  "#conf-run-diff-hook": "command-ref/conf-file.html#conf-run-diff-hook",
-  "#conf-sandbox": "command-ref/conf-file.html#conf-sandbox",
-  "#conf-sandbox-dev-shm-size": "command-ref/conf-file.html#conf-sandbox-dev-shm-size",
-  "#conf-sandbox-paths": "command-ref/conf-file.html#conf-sandbox-paths",
-  "#conf-secret-key-files": "command-ref/conf-file.html#conf-secret-key-files",
-  "#conf-show-trace": "command-ref/conf-file.html#conf-show-trace",
-  "#conf-stalled-download-timeout": "command-ref/conf-file.html#conf-stalled-download-timeout",
-  "#conf-substitute": "command-ref/conf-file.html#conf-substitute",
-  "#conf-substituters": "command-ref/conf-file.html#conf-substituters",
-  "#conf-system": "command-ref/conf-file.html#conf-system",
-  "#conf-system-features": "command-ref/conf-file.html#conf-system-features",
-  "#conf-tarball-ttl": "command-ref/conf-file.html#conf-tarball-ttl",
-  "#conf-timeout": "command-ref/conf-file.html#conf-timeout",
-  "#conf-trace-function-calls": "command-ref/conf-file.html#conf-trace-function-calls",
-  "#conf-trusted-binary-caches": "command-ref/conf-file.html#conf-trusted-binary-caches",
-  "#conf-trusted-public-keys": "command-ref/conf-file.html#conf-trusted-public-keys",
-  "#conf-trusted-substituters": "command-ref/conf-file.html#conf-trusted-substituters",
-  "#conf-trusted-users": "command-ref/conf-file.html#conf-trusted-users",
-  "#extra-sandbox-paths": "command-ref/conf-file.html#extra-sandbox-paths",
-  "#sec-conf-file": "command-ref/conf-file.html",
-  "#env-NIX_PATH": "command-ref/env-common.html#env-NIX_PATH",
-  "#env-common": "command-ref/env-common.html",
-  "#envar-remote": "command-ref/env-common.html#env-NIX_REMOTE",
-  "#sec-common-env": "command-ref/env-common.html",
-  "#ch-files": "command-ref/files.html",
-  "#ch-main-commands": "command-ref/main-commands.html",
-  "#opt-out-link": "command-ref/nix-build.html#opt-out-link",
-  "#sec-nix-build": "command-ref/nix-build.html",
-  "#sec-nix-channel": "command-ref/nix-channel.html",
-  "#sec-nix-collect-garbage": "command-ref/nix-collect-garbage.html",
-  "#sec-nix-copy-closure": "command-ref/nix-copy-closure.html",
-  "#sec-nix-daemon": "command-ref/nix-daemon.html",
-  "#refsec-nix-env-install-examples": "command-ref/nix-env.html#examples",
-  "#rsec-nix-env-install": "command-ref/nix-env.html#operation---install",
-  "#rsec-nix-env-set": "command-ref/nix-env.html#operation---set",
-  "#rsec-nix-env-set-flag": "command-ref/nix-env.html#operation---set-flag",
-  "#rsec-nix-env-upgrade": "command-ref/nix-env.html#operation---upgrade",
-  "#sec-nix-env": "command-ref/nix-env.html",
-  "#ssec-version-comparisons": "command-ref/nix-env.html#versions",
-  "#sec-nix-hash": "command-ref/nix-hash.html",
-  "#sec-nix-instantiate": "command-ref/nix-instantiate.html",
-  "#sec-nix-prefetch-url": "command-ref/nix-prefetch-url.html",
-  "#sec-nix-shell": "command-ref/nix-shell.html",
-  "#ssec-nix-shell-shebang": "command-ref/nix-shell.html#use-as-a--interpreter",
-  "#nixref-queries": "command-ref/nix-store.html#queries",
-  "#opt-add-root": "command-ref/nix-store.html#opt-add-root",
-  "#refsec-nix-store-dump": "command-ref/nix-store.html#operation---dump",
-  "#refsec-nix-store-export": "command-ref/nix-store.html#operation---export",
-  "#refsec-nix-store-import": "command-ref/nix-store.html#operation---import",
-  "#refsec-nix-store-query": "command-ref/nix-store.html#operation---query",
-  "#refsec-nix-store-verify": "command-ref/nix-store.html#operation---verify",
-  "#rsec-nix-store-gc": "command-ref/nix-store.html#operation---gc",
-  "#rsec-nix-store-generate-binary-cache-key": "command-ref/nix-store.html#operation---generate-binary-cache-key",
-  "#rsec-nix-store-realise": "command-ref/nix-store.html#operation---realise",
-  "#rsec-nix-store-serve": "command-ref/nix-store.html#operation---serve",
-  "#sec-nix-store": "command-ref/nix-store.html",
-  "#opt-I": "command-ref/opt-common.html#opt-I",
-  "#opt-attr": "command-ref/opt-common.html#opt-attr",
-  "#opt-common": "command-ref/opt-common.html",
-  "#opt-cores": "command-ref/opt-common.html#opt-cores",
-  "#opt-log-format": "command-ref/opt-common.html#opt-log-format",
-  "#opt-max-jobs": "command-ref/opt-common.html#opt-max-jobs",
-  "#opt-max-silent-time": "command-ref/opt-common.html#opt-max-silent-time",
-  "#opt-timeout": "command-ref/opt-common.html#opt-timeout",
-  "#sec-common-options": "command-ref/opt-common.html",
-  "#ch-utilities": "command-ref/utilities.html",
-  "#chap-hacking": "contributing/hacking.html",
-  "#adv-attr-allowSubstitutes": "language/advanced-attributes.html#adv-attr-allowSubstitutes",
-  "#adv-attr-allowedReferences": "language/advanced-attributes.html#adv-attr-allowedReferences",
-  "#adv-attr-allowedRequisites": "language/advanced-attributes.html#adv-attr-allowedRequisites",
-  "#adv-attr-disallowedReferences": "language/advanced-attributes.html#adv-attr-disallowedReferences",
-  "#adv-attr-disallowedRequisites": "language/advanced-attributes.html#adv-attr-disallowedRequisites",
-  "#adv-attr-exportReferencesGraph": "language/advanced-attributes.html#adv-attr-exportReferencesGraph",
-  "#adv-attr-impureEnvVars": "language/advanced-attributes.html#adv-attr-impureEnvVars",
-  "#adv-attr-outputHash": "language/advanced-attributes.html#adv-attr-outputHash",
-  "#adv-attr-outputHashAlgo": "language/advanced-attributes.html#adv-attr-outputHashAlgo",
-  "#adv-attr-outputHashMode": "language/advanced-attributes.html#adv-attr-outputHashMode",
-  "#adv-attr-passAsFile": "language/advanced-attributes.html#adv-attr-passAsFile",
-  "#adv-attr-preferLocalBuild": "language/advanced-attributes.html#adv-attr-preferLocalBuild",
-  "#fixed-output-drvs": "language/advanced-attributes.html#adv-attr-outputHash",
-  "#sec-advanced-attributes": "language/advanced-attributes.html",
-  "#builtin-abort": "language/builtins.html#builtins-abort",
-  "#builtin-add": "language/builtins.html#builtins-add",
-  "#builtin-all": "language/builtins.html#builtins-all",
-  "#builtin-any": "language/builtins.html#builtins-any",
-  "#builtin-attrNames": "language/builtins.html#builtins-attrNames",
-  "#builtin-attrValues": "language/builtins.html#builtins-attrValues",
-  "#builtin-baseNameOf": "language/builtins.html#builtins-baseNameOf",
-  "#builtin-bitAnd": "language/builtins.html#builtins-bitAnd",
-  "#builtin-bitOr": "language/builtins.html#builtins-bitOr",
-  "#builtin-bitXor": "language/builtins.html#builtins-bitXor",
-  "#builtin-builtins": "language/builtins.html#builtins-builtins",
-  "#builtin-compareVersions": "language/builtins.html#builtins-compareVersions",
-  "#builtin-concatLists": "language/builtins.html#builtins-concatLists",
-  "#builtin-concatStringsSep": "language/builtins.html#builtins-concatStringsSep",
-  "#builtin-currentSystem": "language/builtins.html#builtins-currentSystem",
-  "#builtin-deepSeq": "language/builtins.html#builtins-deepSeq",
-  "#builtin-derivation": "language/builtins.html#builtins-derivation",
-  "#builtin-dirOf": "language/builtins.html#builtins-dirOf",
-  "#builtin-div": "language/builtins.html#builtins-div",
-  "#builtin-elem": "language/builtins.html#builtins-elem",
-  "#builtin-elemAt": "language/builtins.html#builtins-elemAt",
-  "#builtin-fetchGit": "language/builtins.html#builtins-fetchGit",
-  "#builtin-fetchTarball": "language/builtins.html#builtins-fetchTarball",
-  "#builtin-fetchurl": "language/builtins.html#builtins-fetchurl",
-  "#builtin-filterSource": "language/builtins.html#builtins-filterSource",
-  "#builtin-foldl-prime": "language/builtins.html#builtins-foldl-prime",
-  "#builtin-fromJSON": "language/builtins.html#builtins-fromJSON",
-  "#builtin-functionArgs": "language/builtins.html#builtins-functionArgs",
-  "#builtin-genList": "language/builtins.html#builtins-genList",
-  "#builtin-getAttr": "language/builtins.html#builtins-getAttr",
-  "#builtin-getEnv": "language/builtins.html#builtins-getEnv",
-  "#builtin-hasAttr": "language/builtins.html#builtins-hasAttr",
-  "#builtin-hashFile": "language/builtins.html#builtins-hashFile",
-  "#builtin-hashString": "language/builtins.html#builtins-hashString",
-  "#builtin-head": "language/builtins.html#builtins-head",
-  "#builtin-import": "language/builtins.html#builtins-import",
-  "#builtin-intersectAttrs": "language/builtins.html#builtins-intersectAttrs",
-  "#builtin-isAttrs": "language/builtins.html#builtins-isAttrs",
-  "#builtin-isBool": "language/builtins.html#builtins-isBool",
-  "#builtin-isFloat": "language/builtins.html#builtins-isFloat",
-  "#builtin-isFunction": "language/builtins.html#builtins-isFunction",
-  "#builtin-isInt": "language/builtins.html#builtins-isInt",
-  "#builtin-isList": "language/builtins.html#builtins-isList",
-  "#builtin-isNull": "language/builtins.html#builtins-isNull",
-  "#builtin-isString": "language/builtins.html#builtins-isString",
-  "#builtin-length": "language/builtins.html#builtins-length",
-  "#builtin-lessThan": "language/builtins.html#builtins-lessThan",
-  "#builtin-listToAttrs": "language/builtins.html#builtins-listToAttrs",
-  "#builtin-map": "language/builtins.html#builtins-map",
-  "#builtin-match": "language/builtins.html#builtins-match",
-  "#builtin-mul": "language/builtins.html#builtins-mul",
-  "#builtin-parseDrvName": "language/builtins.html#builtins-parseDrvName",
-  "#builtin-path": "language/builtins.html#builtins-path",
-  "#builtin-pathExists": "language/builtins.html#builtins-pathExists",
-  "#builtin-placeholder": "language/builtins.html#builtins-placeholder",
-  "#builtin-readDir": "language/builtins.html#builtins-readDir",
-  "#builtin-readFile": "language/builtins.html#builtins-readFile",
-  "#builtin-removeAttrs": "language/builtins.html#builtins-removeAttrs",
-  "#builtin-replaceStrings": "language/builtins.html#builtins-replaceStrings",
-  "#builtin-seq": "language/builtins.html#builtins-seq",
-  "#builtin-sort": "language/builtins.html#builtins-sort",
-  "#builtin-split": "language/builtins.html#builtins-split",
-  "#builtin-splitVersion": "language/builtins.html#builtins-splitVersion",
-  "#builtin-stringLength": "language/builtins.html#builtins-stringLength",
-  "#builtin-sub": "language/builtins.html#builtins-sub",
-  "#builtin-substring": "language/builtins.html#builtins-substring",
-  "#builtin-tail": "language/builtins.html#builtins-tail",
-  "#builtin-throw": "language/builtins.html#builtins-throw",
-  "#builtin-toFile": "language/builtins.html#builtins-toFile",
-  "#builtin-toJSON": "language/builtins.html#builtins-toJSON",
-  "#builtin-toPath": "language/builtins.html#builtins-toPath",
-  "#builtin-toString": "language/builtins.html#builtins-toString",
-  "#builtin-toXML": "language/builtins.html#builtins-toXML",
-  "#builtin-trace": "language/builtins.html#builtins-trace",
-  "#builtin-tryEval": "language/builtins.html#builtins-tryEval",
-  "#builtin-typeOf": "language/builtins.html#builtins-typeOf",
-  "#ssec-builtins": "language/builtins.html",
-  "#attr-system": "language/derivations.html#attr-system",
-  "#ssec-derivation": "language/derivations.html",
-  "#ch-expression-language": "language/index.html",
-  "#sec-constructs": "language/constructs.html",
-  "#sect-let-language": "language/constructs.html#let-language",
-  "#ss-functions": "language/constructs.html#functions",
-  "#sec-language-operators": "language/operators.html",
-  "#table-operators": "language/operators.html",
-  "#ssec-values": "language/values.html",
-  "#gloss-closure": "glossary.html#gloss-closure",
-  "#gloss-derivation": "glossary.html#gloss-derivation",
-  "#gloss-deriver": "glossary.html#gloss-deriver",
-  "#gloss-nar": "glossary.html#gloss-nar",
-  "#gloss-output-path": "glossary.html#gloss-output-path",
-  "#gloss-profile": "glossary.html#gloss-profile",
-  "#gloss-reachable": "glossary.html#gloss-reachable",
-  "#gloss-reference": "glossary.html#gloss-reference",
-  "#gloss-substitute": "glossary.html#gloss-substitute",
-  "#gloss-user-env": "glossary.html#gloss-user-env",
-  "#gloss-validity": "glossary.html#gloss-validity",
-  "#part-glossary": "glossary.html",
-  "#sec-building-source": "installation/building-source.html",
-  "#ch-env-variables": "installation/env-variables.html",
-  "#sec-installer-proxy-settings": "installation/env-variables.html#proxy-environment-variables",
-  "#sec-nix-ssl-cert-file": "installation/env-variables.html#nix_ssl_cert_file",
-  "#sec-nix-ssl-cert-file-with-nix-daemon-and-macos": "installation/env-variables.html#nix_ssl_cert_file-with-macos-and-the-nix-daemon",
-  "#chap-installation": "installation/installation.html",
-  "#ch-installing-binary": "installation/installing-binary.html",
-  "#sect-macos-installation": "installation/installing-binary.html#macos-installation",
-  "#sect-macos-installation-change-store-prefix": "installation/installing-binary.html#macos-installation",
-  "#sect-macos-installation-encrypted-volume": "installation/installing-binary.html#macos-installation",
-  "#sect-macos-installation-recommended-notes": "installation/installing-binary.html#macos-installation",
-  "#sect-macos-installation-symlink": "installation/installing-binary.html#macos-installation",
-  "#sect-multi-user-installation": "installation/installing-binary.html#multi-user-installation",
-  "#sect-nix-install-binary-tarball": "installation/installing-binary.html#installing-from-a-binary-tarball",
-  "#sect-nix-install-pinned-version-url": "installation/installing-binary.html#installing-a-pinned-nix-version-from-a-url",
-  "#sect-single-user-installation": "installation/installing-binary.html#single-user-installation",
-  "#ch-installing-source": "installation/installing-source.html",
-  "#ssec-multi-user": "installation/multi-user.html",
-  "#ch-nix-security": "installation/nix-security.html",
-  "#sec-obtaining-source": "installation/obtaining-source.html",
-  "#sec-prerequisites-source": "installation/prerequisites-source.html",
-  "#sec-single-user": "installation/single-user.html",
-  "#ch-supported-platforms": "installation/supported-platforms.html",
-  "#ch-upgrading-nix": "installation/upgrading.html",
-  "#ch-about-nix": "introduction.html",
-  "#chap-introduction": "introduction.html",
-  "#ch-basic-package-mgmt": "package-management/basic-package-mgmt.html",
-  "#ssec-binary-cache-substituter": "package-management/binary-cache-substituter.html",
-  "#sec-channels": "package-management/channels.html",
-  "#ssec-copy-closure": "package-management/copy-closure.html",
-  "#sec-garbage-collection": "package-management/garbage-collection.html",
-  "#ssec-gc-roots": "package-management/garbage-collector-roots.html",
-  "#chap-package-management": "package-management/package-management.html",
-  "#sec-profiles": "package-management/profiles.html",
-  "#ssec-s3-substituter": "package-management/s3-substituter.html",
-  "#ssec-s3-substituter-anonymous-reads": "package-management/s3-substituter.html#anonymous-reads-to-your-s3-compatible-binary-cache",
-  "#ssec-s3-substituter-authenticated-reads": "package-management/s3-substituter.html#authenticated-reads-to-your-s3-binary-cache",
-  "#ssec-s3-substituter-authenticated-writes": "package-management/s3-substituter.html#authenticated-writes-to-your-s3-compatible-binary-cache",
-  "#sec-sharing-packages": "package-management/sharing-packages.html",
-  "#ssec-ssh-substituter": "package-management/ssh-substituter.html",
-  "#chap-quick-start": "quick-start.html",
-  "#sec-relnotes": "release-notes/release-notes.html",
-  "#ch-relnotes-0.10.1": "release-notes/rl-0.10.1.html",
-  "#ch-relnotes-0.10": "release-notes/rl-0.10.html",
-  "#ssec-relnotes-0.11": "release-notes/rl-0.11.html",
-  "#ssec-relnotes-0.12": "release-notes/rl-0.12.html",
-  "#ssec-relnotes-0.13": "release-notes/rl-0.13.html",
-  "#ssec-relnotes-0.14": "release-notes/rl-0.14.html",
-  "#ssec-relnotes-0.15": "release-notes/rl-0.15.html",
-  "#ssec-relnotes-0.16": "release-notes/rl-0.16.html",
-  "#ch-relnotes-0.5": "release-notes/rl-0.5.html",
-  "#ch-relnotes-0.6": "release-notes/rl-0.6.html",
-  "#ch-relnotes-0.7": "release-notes/rl-0.7.html",
-  "#ch-relnotes-0.8.1": "release-notes/rl-0.8.1.html",
-  "#ch-relnotes-0.8": "release-notes/rl-0.8.html",
-  "#ch-relnotes-0.9.1": "release-notes/rl-0.9.1.html",
-  "#ch-relnotes-0.9.2": "release-notes/rl-0.9.2.html",
-  "#ch-relnotes-0.9": "release-notes/rl-0.9.html",
-  "#ssec-relnotes-1.0": "release-notes/rl-1.0.html",
-  "#ssec-relnotes-1.1": "release-notes/rl-1.1.html",
-  "#ssec-relnotes-1.10": "release-notes/rl-1.10.html",
-  "#ssec-relnotes-1.11.10": "release-notes/rl-1.11.10.html",
-  "#ssec-relnotes-1.11": "release-notes/rl-1.11.html",
-  "#ssec-relnotes-1.2": "release-notes/rl-1.2.html",
-  "#ssec-relnotes-1.3": "release-notes/rl-1.3.html",
-  "#ssec-relnotes-1.4": "release-notes/rl-1.4.html",
-  "#ssec-relnotes-1.5.1": "release-notes/rl-1.5.1.html",
-  "#ssec-relnotes-1.5.2": "release-notes/rl-1.5.2.html",
-  "#ssec-relnotes-1.5": "release-notes/rl-1.5.html",
-  "#ssec-relnotes-1.6.1": "release-notes/rl-1.6.1.html",
-  "#ssec-relnotes-1.6.0": "release-notes/rl-1.6.html",
-  "#ssec-relnotes-1.7": "release-notes/rl-1.7.html",
-  "#ssec-relnotes-1.8": "release-notes/rl-1.8.html",
-  "#ssec-relnotes-1.9": "release-notes/rl-1.9.html",
-  "#ssec-relnotes-2.0": "release-notes/rl-2.0.html",
-  "#ssec-relnotes-2.1": "release-notes/rl-2.1.html",
-  "#ssec-relnotes-2.2": "release-notes/rl-2.2.html",
-  "#ssec-relnotes-2.3": "release-notes/rl-2.3.html"
+// redirect rules for anchors ensure backwards compatibility of URLs.
+// this must be done on the client side, as web servers do not see the anchor part of the URL.
+
+// redirections are declared as follows:
+// each entry has as its key a path matching the requested URL path, relative to the mdBook document root.
+//
+//     IMPORTANT: it must specify the full path with file name and suffix
+//
+// each entry is itself a set of key-value pairs, where
+// - keys are anchors on the matched path.
+// - values are redirection targets relative to the current path.
+
+const redirects = {
+ "index.html": {
+    "part-advanced-topics": "advanced-topics/advanced-topics.html",
+    "chap-tuning-cores-and-jobs": "advanced-topics/cores-vs-jobs.html",
+    "chap-diff-hook": "advanced-topics/diff-hook.html",
+    "check-dirs-are-unregistered": "advanced-topics/diff-hook.html#check-dirs-are-unregistered",
+    "chap-distributed-builds": "advanced-topics/distributed-builds.html",
+    "chap-post-build-hook": "advanced-topics/post-build-hook.html",
+    "chap-post-build-hook-caveats": "advanced-topics/post-build-hook.html#implementation-caveats",
+    "part-command-ref": "command-ref/command-ref.html",
+    "conf-allow-import-from-derivation": "command-ref/conf-file.html#conf-allow-import-from-derivation",
+    "conf-allow-new-privileges": "command-ref/conf-file.html#conf-allow-new-privileges",
+    "conf-allowed-uris": "command-ref/conf-file.html#conf-allowed-uris",
+    "conf-allowed-users": "command-ref/conf-file.html#conf-allowed-users",
+    "conf-auto-optimise-store": "command-ref/conf-file.html#conf-auto-optimise-store",
+    "conf-binary-cache-public-keys": "command-ref/conf-file.html#conf-binary-cache-public-keys",
+    "conf-binary-caches": "command-ref/conf-file.html#conf-binary-caches",
+    "conf-build-compress-log": "command-ref/conf-file.html#conf-build-compress-log",
+    "conf-build-cores": "command-ref/conf-file.html#conf-build-cores",
+    "conf-build-extra-chroot-dirs": "command-ref/conf-file.html#conf-build-extra-chroot-dirs",
+    "conf-build-extra-sandbox-paths": "command-ref/conf-file.html#conf-build-extra-sandbox-paths",
+    "conf-build-fallback": "command-ref/conf-file.html#conf-build-fallback",
+    "conf-build-max-jobs": "command-ref/conf-file.html#conf-build-max-jobs",
+    "conf-build-max-log-size": "command-ref/conf-file.html#conf-build-max-log-size",
+    "conf-build-max-silent-time": "command-ref/conf-file.html#conf-build-max-silent-time",
+    "conf-build-timeout": "command-ref/conf-file.html#conf-build-timeout",
+    "conf-build-use-chroot": "command-ref/conf-file.html#conf-build-use-chroot",
+    "conf-build-use-sandbox": "command-ref/conf-file.html#conf-build-use-sandbox",
+    "conf-build-use-substitutes": "command-ref/conf-file.html#conf-build-use-substitutes",
+    "conf-build-users-group": "command-ref/conf-file.html#conf-build-users-group",
+    "conf-builders": "command-ref/conf-file.html#conf-builders",
+    "conf-builders-use-substitutes": "command-ref/conf-file.html#conf-builders-use-substitutes",
+    "conf-compress-build-log": "command-ref/conf-file.html#conf-compress-build-log",
+    "conf-connect-timeout": "command-ref/conf-file.html#conf-connect-timeout",
+    "conf-cores": "command-ref/conf-file.html#conf-cores",
+    "conf-diff-hook": "command-ref/conf-file.html#conf-diff-hook",
+    "conf-env-keep-derivations": "command-ref/conf-file.html#conf-env-keep-derivations",
+    "conf-extra-binary-caches": "command-ref/conf-file.html#conf-extra-binary-caches",
+    "conf-extra-platforms": "command-ref/conf-file.html#conf-extra-platforms",
+    "conf-extra-sandbox-paths": "command-ref/conf-file.html#conf-extra-sandbox-paths",
+    "conf-extra-substituters": "command-ref/conf-file.html#conf-extra-substituters",
+    "conf-fallback": "command-ref/conf-file.html#conf-fallback",
+    "conf-fsync-metadata": "command-ref/conf-file.html#conf-fsync-metadata",
+    "conf-gc-keep-derivations": "command-ref/conf-file.html#conf-gc-keep-derivations",
+    "conf-gc-keep-outputs": "command-ref/conf-file.html#conf-gc-keep-outputs",
+    "conf-hashed-mirrors": "command-ref/conf-file.html#conf-hashed-mirrors",
+    "conf-http-connections": "command-ref/conf-file.html#conf-http-connections",
+    "conf-keep-build-log": "command-ref/conf-file.html#conf-keep-build-log",
+    "conf-keep-derivations": "command-ref/conf-file.html#conf-keep-derivations",
+    "conf-keep-env-derivations": "command-ref/conf-file.html#conf-keep-env-derivations",
+    "conf-keep-outputs": "command-ref/conf-file.html#conf-keep-outputs",
+    "conf-max-build-log-size": "command-ref/conf-file.html#conf-max-build-log-size",
+    "conf-max-free": "command-ref/conf-file.html#conf-max-free",
+    "conf-max-jobs": "command-ref/conf-file.html#conf-max-jobs",
+    "conf-max-silent-time": "command-ref/conf-file.html#conf-max-silent-time",
+    "conf-min-free": "command-ref/conf-file.html#conf-min-free",
+    "conf-narinfo-cache-negative-ttl": "command-ref/conf-file.html#conf-narinfo-cache-negative-ttl",
+    "conf-narinfo-cache-positive-ttl": "command-ref/conf-file.html#conf-narinfo-cache-positive-ttl",
+    "conf-netrc-file": "command-ref/conf-file.html#conf-netrc-file",
+    "conf-plugin-files": "command-ref/conf-file.html#conf-plugin-files",
+    "conf-post-build-hook": "command-ref/conf-file.html#conf-post-build-hook",
+    "conf-pre-build-hook": "command-ref/conf-file.html#conf-pre-build-hook",
+    "conf-require-sigs": "command-ref/conf-file.html#conf-require-sigs",
+    "conf-restrict-eval": "command-ref/conf-file.html#conf-restrict-eval",
+    "conf-run-diff-hook": "command-ref/conf-file.html#conf-run-diff-hook",
+    "conf-sandbox": "command-ref/conf-file.html#conf-sandbox",
+    "conf-sandbox-dev-shm-size": "command-ref/conf-file.html#conf-sandbox-dev-shm-size",
+    "conf-sandbox-paths": "command-ref/conf-file.html#conf-sandbox-paths",
+    "conf-secret-key-files": "command-ref/conf-file.html#conf-secret-key-files",
+    "conf-show-trace": "command-ref/conf-file.html#conf-show-trace",
+    "conf-stalled-download-timeout": "command-ref/conf-file.html#conf-stalled-download-timeout",
+    "conf-substitute": "command-ref/conf-file.html#conf-substitute",
+    "conf-substituters": "command-ref/conf-file.html#conf-substituters",
+    "conf-system": "command-ref/conf-file.html#conf-system",
+    "conf-system-features": "command-ref/conf-file.html#conf-system-features",
+    "conf-tarball-ttl": "command-ref/conf-file.html#conf-tarball-ttl",
+    "conf-timeout": "command-ref/conf-file.html#conf-timeout",
+    "conf-trace-function-calls": "command-ref/conf-file.html#conf-trace-function-calls",
+    "conf-trusted-binary-caches": "command-ref/conf-file.html#conf-trusted-binary-caches",
+    "conf-trusted-public-keys": "command-ref/conf-file.html#conf-trusted-public-keys",
+    "conf-trusted-substituters": "command-ref/conf-file.html#conf-trusted-substituters",
+    "conf-trusted-users": "command-ref/conf-file.html#conf-trusted-users",
+    "extra-sandbox-paths": "command-ref/conf-file.html#extra-sandbox-paths",
+    "sec-conf-file": "command-ref/conf-file.html",
+    "env-NIX_PATH": "command-ref/env-common.html#env-NIX_PATH",
+    "env-common": "command-ref/env-common.html",
+    "envar-remote": "command-ref/env-common.html#env-NIX_REMOTE",
+    "sec-common-env": "command-ref/env-common.html",
+    "ch-files": "command-ref/files.html",
+    "ch-main-commands": "command-ref/main-commands.html",
+    "opt-out-link": "command-ref/nix-build.html#opt-out-link",
+    "sec-nix-build": "command-ref/nix-build.html",
+    "sec-nix-channel": "command-ref/nix-channel.html",
+    "sec-nix-collect-garbage": "command-ref/nix-collect-garbage.html",
+    "sec-nix-copy-closure": "command-ref/nix-copy-closure.html",
+    "sec-nix-daemon": "command-ref/nix-daemon.html",
+    "refsec-nix-env-install-examples": "command-ref/nix-env.html#examples",
+    "rsec-nix-env-install": "command-ref/nix-env.html#operation---install",
+    "rsec-nix-env-set": "command-ref/nix-env.html#operation---set",
+    "rsec-nix-env-set-flag": "command-ref/nix-env.html#operation---set-flag",
+    "rsec-nix-env-upgrade": "command-ref/nix-env.html#operation---upgrade",
+    "sec-nix-env": "command-ref/nix-env.html",
+    "ssec-version-comparisons": "command-ref/nix-env.html#versions",
+    "sec-nix-hash": "command-ref/nix-hash.html",
+    "sec-nix-instantiate": "command-ref/nix-instantiate.html",
+    "sec-nix-prefetch-url": "command-ref/nix-prefetch-url.html",
+    "sec-nix-shell": "command-ref/nix-shell.html",
+    "ssec-nix-shell-shebang": "command-ref/nix-shell.html#use-as-a--interpreter",
+    "nixref-queries": "command-ref/nix-store.html#queries",
+    "opt-add-root": "command-ref/nix-store.html#opt-add-root",
+    "refsec-nix-store-dump": "command-ref/nix-store.html#operation---dump",
+    "refsec-nix-store-export": "command-ref/nix-store.html#operation---export",
+    "refsec-nix-store-import": "command-ref/nix-store.html#operation---import",
+    "refsec-nix-store-query": "command-ref/nix-store.html#operation---query",
+    "refsec-nix-store-verify": "command-ref/nix-store.html#operation---verify",
+    "rsec-nix-store-gc": "command-ref/nix-store.html#operation---gc",
+    "rsec-nix-store-generate-binary-cache-key": "command-ref/nix-store.html#operation---generate-binary-cache-key",
+    "rsec-nix-store-realise": "command-ref/nix-store.html#operation---realise",
+    "rsec-nix-store-serve": "command-ref/nix-store.html#operation---serve",
+    "sec-nix-store": "command-ref/nix-store.html",
+    "opt-I": "command-ref/opt-common.html#opt-I",
+    "opt-attr": "command-ref/opt-common.html#opt-attr",
+    "opt-common": "command-ref/opt-common.html",
+    "opt-cores": "command-ref/opt-common.html#opt-cores",
+    "opt-log-format": "command-ref/opt-common.html#opt-log-format",
+    "opt-max-jobs": "command-ref/opt-common.html#opt-max-jobs",
+    "opt-max-silent-time": "command-ref/opt-common.html#opt-max-silent-time",
+    "opt-timeout": "command-ref/opt-common.html#opt-timeout",
+    "sec-common-options": "command-ref/opt-common.html",
+    "ch-utilities": "command-ref/utilities.html",
+    "chap-hacking": "contributing/hacking.html",
+    "adv-attr-allowSubstitutes": "language/advanced-attributes.html#adv-attr-allowSubstitutes",
+    "adv-attr-allowedReferences": "language/advanced-attributes.html#adv-attr-allowedReferences",
+    "adv-attr-allowedRequisites": "language/advanced-attributes.html#adv-attr-allowedRequisites",
+    "adv-attr-disallowedReferences": "language/advanced-attributes.html#adv-attr-disallowedReferences",
+    "adv-attr-disallowedRequisites": "language/advanced-attributes.html#adv-attr-disallowedRequisites",
+    "adv-attr-exportReferencesGraph": "language/advanced-attributes.html#adv-attr-exportReferencesGraph",
+    "adv-attr-impureEnvVars": "language/advanced-attributes.html#adv-attr-impureEnvVars",
+    "adv-attr-outputHash": "language/advanced-attributes.html#adv-attr-outputHash",
+    "adv-attr-outputHashAlgo": "language/advanced-attributes.html#adv-attr-outputHashAlgo",
+    "adv-attr-outputHashMode": "language/advanced-attributes.html#adv-attr-outputHashMode",
+    "adv-attr-passAsFile": "language/advanced-attributes.html#adv-attr-passAsFile",
+    "adv-attr-preferLocalBuild": "language/advanced-attributes.html#adv-attr-preferLocalBuild",
+    "fixed-output-drvs": "language/advanced-attributes.html#adv-attr-outputHash",
+    "sec-advanced-attributes": "language/advanced-attributes.html",
+    "builtin-abort": "language/builtins.html#builtins-abort",
+    "builtin-add": "language/builtins.html#builtins-add",
+    "builtin-all": "language/builtins.html#builtins-all",
+    "builtin-any": "language/builtins.html#builtins-any",
+    "builtin-attrNames": "language/builtins.html#builtins-attrNames",
+    "builtin-attrValues": "language/builtins.html#builtins-attrValues",
+    "builtin-baseNameOf": "language/builtins.html#builtins-baseNameOf",
+    "builtin-bitAnd": "language/builtins.html#builtins-bitAnd",
+    "builtin-bitOr": "language/builtins.html#builtins-bitOr",
+    "builtin-bitXor": "language/builtins.html#builtins-bitXor",
+    "builtin-builtins": "language/builtins.html#builtins-builtins",
+    "builtin-compareVersions": "language/builtins.html#builtins-compareVersions",
+    "builtin-concatLists": "language/builtins.html#builtins-concatLists",
+    "builtin-concatStringsSep": "language/builtins.html#builtins-concatStringsSep",
+    "builtin-currentSystem": "language/builtins.html#builtins-currentSystem",
+    "builtin-deepSeq": "language/builtins.html#builtins-deepSeq",
+    "builtin-derivation": "language/builtins.html#builtins-derivation",
+    "builtin-dirOf": "language/builtins.html#builtins-dirOf",
+    "builtin-div": "language/builtins.html#builtins-div",
+    "builtin-elem": "language/builtins.html#builtins-elem",
+    "builtin-elemAt": "language/builtins.html#builtins-elemAt",
+    "builtin-fetchGit": "language/builtins.html#builtins-fetchGit",
+    "builtin-fetchTarball": "language/builtins.html#builtins-fetchTarball",
+    "builtin-fetchurl": "language/builtins.html#builtins-fetchurl",
+    "builtin-filterSource": "language/builtins.html#builtins-filterSource",
+    "builtin-foldl-prime": "language/builtins.html#builtins-foldl-prime",
+    "builtin-fromJSON": "language/builtins.html#builtins-fromJSON",
+    "builtin-functionArgs": "language/builtins.html#builtins-functionArgs",
+    "builtin-genList": "language/builtins.html#builtins-genList",
+    "builtin-getAttr": "language/builtins.html#builtins-getAttr",
+    "builtin-getEnv": "language/builtins.html#builtins-getEnv",
+    "builtin-hasAttr": "language/builtins.html#builtins-hasAttr",
+    "builtin-hashFile": "language/builtins.html#builtins-hashFile",
+    "builtin-hashString": "language/builtins.html#builtins-hashString",
+    "builtin-head": "language/builtins.html#builtins-head",
+    "builtin-import": "language/builtins.html#builtins-import",
+    "builtin-intersectAttrs": "language/builtins.html#builtins-intersectAttrs",
+    "builtin-isAttrs": "language/builtins.html#builtins-isAttrs",
+    "builtin-isBool": "language/builtins.html#builtins-isBool",
+    "builtin-isFloat": "language/builtins.html#builtins-isFloat",
+    "builtin-isFunction": "language/builtins.html#builtins-isFunction",
+    "builtin-isInt": "language/builtins.html#builtins-isInt",
+    "builtin-isList": "language/builtins.html#builtins-isList",
+    "builtin-isNull": "language/builtins.html#builtins-isNull",
+    "builtin-isString": "language/builtins.html#builtins-isString",
+    "builtin-length": "language/builtins.html#builtins-length",
+    "builtin-lessThan": "language/builtins.html#builtins-lessThan",
+    "builtin-listToAttrs": "language/builtins.html#builtins-listToAttrs",
+    "builtin-map": "language/builtins.html#builtins-map",
+    "builtin-match": "language/builtins.html#builtins-match",
+    "builtin-mul": "language/builtins.html#builtins-mul",
+    "builtin-parseDrvName": "language/builtins.html#builtins-parseDrvName",
+    "builtin-path": "language/builtins.html#builtins-path",
+    "builtin-pathExists": "language/builtins.html#builtins-pathExists",
+    "builtin-placeholder": "language/builtins.html#builtins-placeholder",
+    "builtin-readDir": "language/builtins.html#builtins-readDir",
+    "builtin-readFile": "language/builtins.html#builtins-readFile",
+    "builtin-removeAttrs": "language/builtins.html#builtins-removeAttrs",
+    "builtin-replaceStrings": "language/builtins.html#builtins-replaceStrings",
+    "builtin-seq": "language/builtins.html#builtins-seq",
+    "builtin-sort": "language/builtins.html#builtins-sort",
+    "builtin-split": "language/builtins.html#builtins-split",
+    "builtin-splitVersion": "language/builtins.html#builtins-splitVersion",
+    "builtin-stringLength": "language/builtins.html#builtins-stringLength",
+    "builtin-sub": "language/builtins.html#builtins-sub",
+    "builtin-substring": "language/builtins.html#builtins-substring",
+    "builtin-tail": "language/builtins.html#builtins-tail",
+    "builtin-throw": "language/builtins.html#builtins-throw",
+    "builtin-toFile": "language/builtins.html#builtins-toFile",
+    "builtin-toJSON": "language/builtins.html#builtins-toJSON",
+    "builtin-toPath": "language/builtins.html#builtins-toPath",
+    "builtin-toString": "language/builtins.html#builtins-toString",
+    "builtin-toXML": "language/builtins.html#builtins-toXML",
+    "builtin-trace": "language/builtins.html#builtins-trace",
+    "builtin-tryEval": "language/builtins.html#builtins-tryEval",
+    "builtin-typeOf": "language/builtins.html#builtins-typeOf",
+    "ssec-builtins": "language/builtins.html",
+    "attr-system": "language/derivations.html#attr-system",
+    "ssec-derivation": "language/derivations.html",
+    "ch-expression-language": "language/index.html",
+    "sec-constructs": "language/constructs.html",
+    "sect-let-language": "language/constructs.html#let-language",
+    "ss-functions": "language/constructs.html#functions",
+    "sec-language-operators": "language/operators.html",
+    "table-operators": "language/operators.html",
+    "ssec-values": "language/values.html",
+    "gloss-closure": "glossary.html#gloss-closure",
+    "gloss-derivation": "glossary.html#gloss-derivation",
+    "gloss-deriver": "glossary.html#gloss-deriver",
+    "gloss-nar": "glossary.html#gloss-nar",
+    "gloss-output-path": "glossary.html#gloss-output-path",
+    "gloss-profile": "glossary.html#gloss-profile",
+    "gloss-reachable": "glossary.html#gloss-reachable",
+    "gloss-reference": "glossary.html#gloss-reference",
+    "gloss-substitute": "glossary.html#gloss-substitute",
+    "gloss-user-env": "glossary.html#gloss-user-env",
+    "gloss-validity": "glossary.html#gloss-validity",
+    "part-glossary": "glossary.html",
+    "sec-building-source": "installation/building-source.html",
+    "ch-env-variables": "installation/env-variables.html",
+    "sec-installer-proxy-settings": "installation/env-variables.html#proxy-environment-variables",
+    "sec-nix-ssl-cert-file": "installation/env-variables.html#nix_ssl_cert_file",
+    "sec-nix-ssl-cert-file-with-nix-daemon-and-macos": "installation/env-variables.html#nix_ssl_cert_file-with-macos-and-the-nix-daemon",
+    "chap-installation": "installation/installation.html",
+    "ch-installing-binary": "installation/installing-binary.html",
+    "sect-macos-installation": "installation/installing-binary.html#macos-installation",
+    "sect-macos-installation-change-store-prefix": "installation/installing-binary.html#macos-installation",
+    "sect-macos-installation-encrypted-volume": "installation/installing-binary.html#macos-installation",
+    "sect-macos-installation-recommended-notes": "installation/installing-binary.html#macos-installation",
+    "sect-macos-installation-symlink": "installation/installing-binary.html#macos-installation",
+    "sect-multi-user-installation": "installation/installing-binary.html#multi-user-installation",
+    "sect-nix-install-binary-tarball": "installation/installing-binary.html#installing-from-a-binary-tarball",
+    "sect-nix-install-pinned-version-url": "installation/installing-binary.html#installing-a-pinned-nix-version-from-a-url",
+    "sect-single-user-installation": "installation/installing-binary.html#single-user-installation",
+    "ch-installing-source": "installation/installing-source.html",
+    "ssec-multi-user": "installation/multi-user.html",
+    "ch-nix-security": "installation/nix-security.html",
+    "sec-obtaining-source": "installation/obtaining-source.html",
+    "sec-prerequisites-source": "installation/prerequisites-source.html",
+    "sec-single-user": "installation/single-user.html",
+    "ch-supported-platforms": "installation/supported-platforms.html",
+    "ch-upgrading-nix": "installation/upgrading.html",
+    "ch-about-nix": "introduction.html",
+    "chap-introduction": "introduction.html",
+    "ch-basic-package-mgmt": "package-management/basic-package-mgmt.html",
+    "ssec-binary-cache-substituter": "package-management/binary-cache-substituter.html",
+    "sec-channels": "package-management/channels.html",
+    "ssec-copy-closure": "package-management/copy-closure.html",
+    "sec-garbage-collection": "package-management/garbage-collection.html",
+    "ssec-gc-roots": "package-management/garbage-collector-roots.html",
+    "chap-package-management": "package-management/package-management.html",
+    "sec-profiles": "package-management/profiles.html",
+    "ssec-s3-substituter": "package-management/s3-substituter.html",
+    "ssec-s3-substituter-anonymous-reads": "package-management/s3-substituter.html#anonymous-reads-to-your-s3-compatible-binary-cache",
+    "ssec-s3-substituter-authenticated-reads": "package-management/s3-substituter.html#authenticated-reads-to-your-s3-binary-cache",
+    "ssec-s3-substituter-authenticated-writes": "package-management/s3-substituter.html#authenticated-writes-to-your-s3-compatible-binary-cache",
+    "sec-sharing-packages": "package-management/sharing-packages.html",
+    "ssec-ssh-substituter": "package-management/ssh-substituter.html",
+    "chap-quick-start": "quick-start.html",
+    "sec-relnotes": "release-notes/release-notes.html",
+    "ch-relnotes-0.10.1": "release-notes/rl-0.10.1.html",
+    "ch-relnotes-0.10": "release-notes/rl-0.10.html",
+    "ssec-relnotes-0.11": "release-notes/rl-0.11.html",
+    "ssec-relnotes-0.12": "release-notes/rl-0.12.html",
+    "ssec-relnotes-0.13": "release-notes/rl-0.13.html",
+    "ssec-relnotes-0.14": "release-notes/rl-0.14.html",
+    "ssec-relnotes-0.15": "release-notes/rl-0.15.html",
+    "ssec-relnotes-0.16": "release-notes/rl-0.16.html",
+    "ch-relnotes-0.5": "release-notes/rl-0.5.html",
+    "ch-relnotes-0.6": "release-notes/rl-0.6.html",
+    "ch-relnotes-0.7": "release-notes/rl-0.7.html",
+    "ch-relnotes-0.8.1": "release-notes/rl-0.8.1.html",
+    "ch-relnotes-0.8": "release-notes/rl-0.8.html",
+    "ch-relnotes-0.9.1": "release-notes/rl-0.9.1.html",
+    "ch-relnotes-0.9.2": "release-notes/rl-0.9.2.html",
+    "ch-relnotes-0.9": "release-notes/rl-0.9.html",
+    "ssec-relnotes-1.0": "release-notes/rl-1.0.html",
+    "ssec-relnotes-1.1": "release-notes/rl-1.1.html",
+    "ssec-relnotes-1.10": "release-notes/rl-1.10.html",
+    "ssec-relnotes-1.11.10": "release-notes/rl-1.11.10.html",
+    "ssec-relnotes-1.11": "release-notes/rl-1.11.html",
+    "ssec-relnotes-1.2": "release-notes/rl-1.2.html",
+    "ssec-relnotes-1.3": "release-notes/rl-1.3.html",
+    "ssec-relnotes-1.4": "release-notes/rl-1.4.html",
+    "ssec-relnotes-1.5.1": "release-notes/rl-1.5.1.html",
+    "ssec-relnotes-1.5.2": "release-notes/rl-1.5.2.html",
+    "ssec-relnotes-1.5": "release-notes/rl-1.5.html",
+    "ssec-relnotes-1.6.1": "release-notes/rl-1.6.1.html",
+    "ssec-relnotes-1.6.0": "release-notes/rl-1.6.html",
+    "ssec-relnotes-1.7": "release-notes/rl-1.7.html",
+    "ssec-relnotes-1.8": "release-notes/rl-1.8.html",
+    "ssec-relnotes-1.9": "release-notes/rl-1.9.html",
+    "ssec-relnotes-2.0": "release-notes/rl-2.0.html",
+    "ssec-relnotes-2.1": "release-notes/rl-2.1.html",
+    "ssec-relnotes-2.2": "release-notes/rl-2.2.html",
+    "ssec-relnotes-2.3": "release-notes/rl-2.3.html"
+  },
+  "language/values.html": {
+    "simple-values": "#primitives",
+    "lists": "#list",
+    "strings": "#string",
+    "lists": "#list",
+    "attribute-sets": "#attribute-set"
+  }
 };
 
-var isRoot = (document.location.pathname.endsWith('/') || document.location.pathname.endsWith('/index.html')) && path_to_root === '';
-if (isRoot && redirects[document.location.hash]) {
-  document.location.href = path_to_root + redirects[document.location.hash];
+// the following code matches the current page's URL against the set of redirects.
+//
+// it is written to minimize the latency between page load and redirect.
+// therefore we avoid function calls, copying data, and unnecessary loops.
+// IMPORTANT: we use stateful array operations and their order matters!
+//
+// matching URLs is more involved than it should be:
+//
+// 1. `document.location.pathname` can have an arbitrary prefix.
+//
+// 2. `path_to_root` is set by mdBook. it consists only of `../`s and
+//    determines the depth of `<path>` relative to the prefix:
+//
+//          `document.location.pathname`
+//        |------------------------------|
+//        /<prefix>/<path>/[<file>[.html]][#<anchor>]
+//                  |----|
+//              `path_to_root` has same number of path segments
+//
+//    source: https://phaiax.github.io/mdBook/format/theme/index-hbs.html#data
+//
+// 3. the following paths are equivalent:
+//
+//        /foo/bar/
+//        /foo/bar/index.html
+//        /foo/bar/index
+//
+//  4. the following paths are also equivalent:
+//
+//        /foo/bar/baz
+//        /foo/bar/baz.html
+//
+
+let segments = document.location.pathname.split('/');
+
+let file = segments.pop();
+
+// normalize file name
+if (file === '') { file = "index.html"; }
+else if (!file.endsWith('.html')) { file = file + '.html'; }
+
+segments.push(file);
+
+// use `path_to_root` to discern prefix from path.
+const depth = path_to_root.split('/').length;
+
+// remove segments containing prefix. the following works because
+// 1. the original `document.location.pathname` is absolute,
+//    hence first element of `segments` is always empty.
+// 2. last element of splitting `path_to_root` is also always empty.
+// 3. last element of `segments` is the file name.
+//
+// visual example:
+//
+//     '/foo/bar/baz.html'.split('/') -> [ '', 'foo', 'bar', 'baz.html' ]
+//          '../'.split('/')          -> [ '..', '' ]
+//
+// the following operations will then result in
+//
+//     path = 'bar/baz.html'
+//
+segments.splice(0, segments.length - depth);
+const path = segments.join('/');
+
+// anchor starts with the hash character (`#`),
+// but our redirect declarations don't, so we strip it.
+// example:
+//     document.location.hash -> '#foo'
+//     document.location.hash.substring(1) -> 'foo'
+const anchor = document.location.hash.substring(1);
+
+const redirect = redirects[path];
+if (redirect) {
+  const target = redirect[anchor];
+  if (target) {
+    document.location.href = target;
+  }
 }
diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 908e7e3d9..4f1fc34ce 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -29,6 +29,7 @@
 - [Nix Language](language/index.md)
   - [Data Types](language/values.md)
   - [Language Constructs](language/constructs.md)
+    - [String interpolation](language/string-interpolation.md)
   - [Operators](language/operators.md)
   - [Derivations](language/derivations.md)
     - [Advanced Attributes](language/advanced-attributes.md)
@@ -59,12 +60,14 @@
 @manpages@
   - [Files](command-ref/files.md)
     - [nix.conf](command-ref/conf-file.md)
+- [Architecture](architecture/architecture.md)
 - [Glossary](glossary.md)
 - [Contributing](contributing/contributing.md)
   - [Hacking](contributing/hacking.md)
   - [CLI guideline](contributing/cli-guideline.md)
 - [Release Notes](release-notes/release-notes.md)
   - [Release X.Y (202?-??-??)](release-notes/rl-next.md)
+  - [Release 2.12 (2022-12-06)](release-notes/rl-2.12.md)
   - [Release 2.11 (2022-08-25)](release-notes/rl-2.11.md)
   - [Release 2.10 (2022-07-11)](release-notes/rl-2.10.md)
   - [Release 2.9 (2022-05-30)](release-notes/rl-2.9.md)
diff --git a/doc/manual/src/advanced-topics/diff-hook.md b/doc/manual/src/advanced-topics/diff-hook.md
index 161e64b2a..4a742c160 100644
--- a/doc/manual/src/advanced-topics/diff-hook.md
+++ b/doc/manual/src/advanced-topics/diff-hook.md
@@ -121,37 +121,3 @@ error:
     are not valid, so checking is not possible
 
 Run the build without `--check`, and then try with `--check` again.
-
-# Automatic and Optionally Enforced Determinism Verification
-
-Automatically verify every build at build time by executing the build
-multiple times.
-
-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:
-
-    enforce-determinism = true
-    repeat = 2
-
-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
-    repeat = 1
-
-An example output of this configuration:
-
-```console
-$ nix-build ./test.nix -A unstable
-this derivation will be built:
-  /nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv
-building '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' (round 1/2)...
-building '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' (round 2/2)...
-output '/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable' of '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' differs from '/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable.check' from previous round
-/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable
-```
diff --git a/doc/manual/src/advanced-topics/post-build-hook.md b/doc/manual/src/advanced-topics/post-build-hook.md
index fcb52d878..1479cc3a4 100644
--- a/doc/manual/src/advanced-topics/post-build-hook.md
+++ b/doc/manual/src/advanced-topics/post-build-hook.md
@@ -33,12 +33,17 @@ 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
-`trusted-public-keys` and `substituters` options:
+Then update [`nix.conf`](../command-ref/conf-file.md) on any machine that will access the cache.
+Add the cache URL to [`substituters`](../command-ref/conf-file.md#conf-substituters) and the public key to [`trusted-public-keys`](../command-ref/conf-file.md#conf-trusted-public-keys):
 
     substituters = https://cache.nixos.org/ s3://example-nix-cache
     trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM=
 
+Machines that build for the cache must sign derivations using the private key.
+On those machines, add the path to the key file to the [`secret-key-files`](../command-ref/conf-file.md#conf-secret-key-files) field in their [`nix.conf`](../command-ref/conf-file.md):
+
+    secret-key-files = /etc/nix/key.private
+
 We will restart the Nix daemon in a later step.
 
 # Implementing the build hook
@@ -52,14 +57,12 @@ set -eu
 set -f # disable globbing
 export IFS=' '
 
-echo "Signing paths" $OUT_PATHS
-nix store sign --key-file /etc/nix/key.private $OUT_PATHS
 echo "Uploading paths" $OUT_PATHS
-exec nix copy --to 's3://example-nix-cache' $OUT_PATHS
+exec nix copy --to "s3://example-nix-cache" $OUT_PATHS
 ```
 
 > **Note**
-> 
+>
 > The `$OUT_PATHS` variable is a space-separated list of Nix store
 > paths. In this case, we expect and want the shell to perform word
 > splitting to make each output path its own argument to `nix
diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
new file mode 100644
index 000000000..2d1b26558
--- /dev/null
+++ b/doc/manual/src/architecture/architecture.md
@@ -0,0 +1,115 @@
+# Architecture
+
+This chapter describes how Nix works.
+It should help users understand why Nix behaves as it does, and it should help developers understand how to modify Nix and how to write similar tools.
+
+## Overview
+
+Nix consists of [hierarchical layers].
+
+[hierarchical layers]: https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers
+
+The following [concept map] shows its main components (rectangles), the objects they operate on (rounded rectangles), and their interactions (connecting phrases):
+
+[concept map]: https://en.m.wikipedia.org/wiki/Concept_map
+
+```
+
+   .----------------.
+   | Nix expression |----------.
+   '----------------'          |
+           |              passed to
+           |                   |
++----------|-------------------|--------------------------------+
+| Nix      |                   V                                |
+|          |      +-------------------------+                   |
+|          |      | commmand line interface |------.            |
+|          |      +-------------------------+      |            |
+|          |                   |                   |            |
+|    evaluated by            calls              manages         |
+|          |                   |                   |            |
+|          |                   V                   |            |
+|          |         +--------------------+        |            |
+|          '-------->| language evaluator |        |            |
+|                    +--------------------+        |            |
+|                              |                   |            |
+|                           produces               |            |
+|                              |                   V            |
+| +----------------------------|------------------------------+ |
+| | store                      |                              | |
+| |            referenced by   V       builds                 | |
+| | .-------------.      .------------.      .--------------. | |
+| | | build input |----->| build plan |----->| build result | | |
+| | '-------------'      '------------'      '--------------' | |
+| +-------------------------------------------------|---------+ |
++---------------------------------------------------|-----------+
+                                                    |
+                                              represented as
+                                                    |
+                                                    V
+                                            .---------------.
+                                            |     file      |
+                                            '---------------'
+```
+
+At the top is the [command line interface](../command-ref/command-ref.md) that drives the underlying layers.
+
+The [Nix language](../language/index.md) evaluator transforms Nix expressions into self-contained *build plans*, which are used to derive *build results* from referenced *build inputs*.
+
+The command line interface and Nix expressions are what users deal with most.
+
+> **Note**
+> The Nix language itself does not have a notion of *packages* or *configurations*.
+> As far as we are concerned here, the inputs and results of a build plan are just data.
+
+Underlying the command line interface and the Nix language evaluator is the [Nix store](../glossary.md#gloss-store), a mechanism to keep track of build plans, data, and references between them.
+It can also execute build plans to produce new data, which are made available to the operating system as files.
+
+A build plan itself is a series of *build tasks*, together with their build inputs.
+
+> **Important**
+> A build task in Nix is called [derivation](../glossary#gloss-derivation).
+
+Each build task has a special build input executed as *build instructions* in order to perform the build.
+The result of a build task can be input to another build task.
+
+The following [data flow diagram] shows a build plan for illustration.
+Build inputs used as instructions to a build task are marked accordingly:
+
+[data flow diagram]: https://en.m.wikipedia.org/wiki/Data-flow_diagram
+
+```
++--------------------------------------------------------------------+
+| build plan                                                         |
+|                                                                    |
+| .-------------.                                                    |
+| | build input |---------.                                          |
+| '-------------'         |                                          |
+|                    instructions                                    |
+|                         |                                          |
+|                         v                                          |
+| .-------------.    .----------.                                    |
+| | build input |-->( build task )-------.                           |
+| '-------------'    '----------'        |                           |
+|                                  instructions                      |
+|                                        |                           |
+|                                        v                           |
+| .-------------.                  .----------.     .--------------. |
+| | build input |---------.       ( build task )--->| build result | |
+| '-------------'         |        '----------'     '--------------' |
+|                    instructions        ^                           |
+|                         |              |                           |
+|                         v              |                           |
+| .-------------.    .----------.        |                           |
+| | build input |-->( build task )-------'                           |
+| '-------------'    '----------'                                    |
+|                         ^                                          |
+|                         |                                          |
+|                         |                                          |
+| .-------------.         |                                          |
+| | build input |---------'                                          |
+| '-------------'                                                    |
+|                                                                    |
++--------------------------------------------------------------------+
+```
+
diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md
index 3f3eb6915..5845bdc43 100644
--- a/doc/manual/src/command-ref/env-common.md
+++ b/doc/manual/src/command-ref/env-common.md
@@ -7,42 +7,11 @@ Most Nix commands interpret the following environment variables:
     `nix-shell`. It can have the values `pure` or `impure`.
 
   - [`NIX_PATH`]{#env-NIX_PATH}\
-    A colon-separated list of directories used to look up Nix
-    expressions enclosed in angle brackets (i.e., `<path>`). For
-    instance, the value
-
-        /home/eelco/Dev:/etc/nixos
-
-    will cause Nix to look for paths relative to `/home/eelco/Dev` and
-    `/etc/nixos`, in this order. It is also possible to match paths
-    against a prefix. For example, the value
-
-        nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos
-
-    will cause Nix to search for `<nixpkgs/path>` in
-    `/home/eelco/Dev/nixpkgs-branch/path` and `/etc/nixos/nixpkgs/path`.
-
-    If a path in the Nix search path starts with `http://` or
-    `https://`, it is interpreted as the URL of a tarball that will be
-    downloaded and unpacked to a temporary location. The tarball must
-    consist of a single top-level directory. For example, setting
-    `NIX_PATH` to
-
-        nixpkgs=https://github.com/NixOS/nixpkgs/archive/master.tar.gz
-
-    tells Nix to download and use the current contents of the
-    `master` branch in the `nixpkgs` repository.
-
-    The URLs of the tarballs from the official nixos.org channels (see
-    [the manual for `nix-channel`](nix-channel.md)) can be abbreviated
-    as `channel:<channel-name>`.  For instance, the following two
-    values of `NIX_PATH` are equivalent:
-
-        nixpkgs=channel:nixos-21.05
-        nixpkgs=https://nixos.org/channels/nixos-21.05/nixexprs.tar.xz
-
-    The Nix search path can also be extended using the `-I` option to
-    many Nix commands, which takes precedence over `NIX_PATH`.
+    A colon-separated list of directories used to look up the location of Nix
+    expressions using [paths](../language/values.md#type-path)
+    enclosed in angle brackets (i.e., `<path>`),
+    e.g. `/home/eelco/Dev:/etc/nixos`. It can be extended using the
+    [`-I` option](./opt-common#opt-I).
 
   - [`NIX_IGNORE_SYMLINK_STORE`]{#env-NIX_IGNORE_SYMLINK_STORE}\
     Normally, the Nix store directory (typically `/nix/store`) is not
diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md
index 49c6f3f55..937b046b8 100644
--- a/doc/manual/src/command-ref/nix-build.md
+++ b/doc/manual/src/command-ref/nix-build.md
@@ -37,10 +37,12 @@ directory containing at least a file named `default.nix`.
 
 `nix-build` is essentially a wrapper around
 [`nix-instantiate`](nix-instantiate.md) (to translate a high-level Nix
-expression to a low-level store derivation) and [`nix-store
+expression to a low-level [store derivation]) and [`nix-store
 --realise`](nix-store.md#operation---realise) (to build the store
 derivation).
 
+[store derivation]: ../glossary.md#gloss-store-derivation
+
 > **Warning**
 >
 > The result of the build is automatically registered as a root of the
@@ -53,16 +55,18 @@ All options not listed here are passed to `nix-store
 --realise`, except for `--arg` and `--attr` / `-A` which are passed to
 `nix-instantiate`.
 
-  - [`--no-out-link`]{#opt-no-out-link}\
+  - <span id="opt-no-out-link">[`--no-out-link`](#opt-no-out-link)<span>
+
     Do not create a symlink to the output path. Note that as a result
     the output does not become a root of the garbage collector, and so
-    might be deleted by `nix-store
-                    --gc`.
+    might be deleted by `nix-store --gc`.
+
+  - <span id="opt-dry-run">[`--dry-run`](#opt-dry-run)</span>
 
-  - [`--dry-run`]{#opt-dry-run}\
     Show what store paths would be built or downloaded.
 
-  - [`--out-link`]{#opt-out-link} / `-o` *outlink*\
+  - <span id="opt-out-link">[`--out-link`](#opt-out-link)</span> / `-o` *outlink*
+
     Change the name of the symlink to the output path created from
     `result` to *outlink*.
 
diff --git a/doc/manual/src/command-ref/nix-copy-closure.md b/doc/manual/src/command-ref/nix-copy-closure.md
index 9a29030bd..83e8a2936 100644
--- a/doc/manual/src/command-ref/nix-copy-closure.md
+++ b/doc/manual/src/command-ref/nix-copy-closure.md
@@ -47,7 +47,9 @@ authentication, you can avoid typing the passphrase with `ssh-agent`.
     Enable compression of the SSH connection.
 
   - `--include-outputs`\
-    Also copy the outputs of store derivations included in the closure.
+    Also copy the outputs of [store derivation]s included in the closure.
+
+    [store derivation]: ../../glossary.md#gloss-store-derivation
 
   - `--use-substitutes` / `-s`\
     Attempt to download missing paths on the target machine using Nix’s
diff --git a/doc/manual/src/command-ref/nix-daemon.md b/doc/manual/src/command-ref/nix-daemon.md
index e91cb01dd..04b483be3 100644
--- a/doc/manual/src/command-ref/nix-daemon.md
+++ b/doc/manual/src/command-ref/nix-daemon.md
@@ -8,6 +8,6 @@
 
 # Description
 
-The Nix daemon is necessary in multi-user Nix installations. It performs
-build actions and other operations on the Nix store on behalf of
+The Nix daemon is necessary in multi-user Nix installations. It runs
+build tasks and other operations on the Nix store on behalf of
 unprivileged users.
diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md
index a5df35d77..f4fa5b50c 100644
--- a/doc/manual/src/command-ref/nix-env.md
+++ b/doc/manual/src/command-ref/nix-env.md
@@ -205,10 +205,12 @@ a number of possible ways:
     unambiguous way, which is necessary if there are multiple
     derivations with the same name.
 
-  - If *args* are store derivations, then these are
+  - If *args* are [store derivation]s, then these are
     [realised](nix-store.md#operation---realise), and the resulting output paths
     are installed.
 
+    [store derivation]: ../glossary.md#gloss-store-derivation
+
   - If *args* are store paths that are not store derivations, then these
     are [realised](nix-store.md#operation---realise) and installed.
 
@@ -280,7 +282,7 @@ To copy the store path with symbolic name `gcc` from another profile:
 $ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc
 ```
 
-To install a specific store derivation (typically created by
+To install a specific [store derivation] (typically created by
 `nix-instantiate`):
 
 ```console
@@ -665,7 +667,7 @@ derivation is shown unless `--no-name` is specified.
     Print the `system` attribute of the derivation.
 
   - `--drv-path`\
-    Print the path of the store derivation.
+    Print the path of the [store derivation].
 
   - `--out-path`\
     Print the output path of the derivation.
diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md
index 8f143729e..432fb2608 100644
--- a/doc/manual/src/command-ref/nix-instantiate.md
+++ b/doc/manual/src/command-ref/nix-instantiate.md
@@ -17,13 +17,14 @@
 
 # Description
 
-The command `nix-instantiate` generates [store
-derivations](../glossary.md) from (high-level) Nix expressions. It
-evaluates the Nix expressions in each of *files* (which defaults to
+The command `nix-instantiate` produces [store derivation]s from (high-level) Nix expressions.
+It evaluates the Nix expressions in each of *files* (which defaults to
 *./default.nix*). Each top-level expression should evaluate to a
 derivation, a list of derivations, or a set of derivations. The paths
 of the resulting store derivations are printed on standard output.
 
+[store derivation]: ../glossary.md#gloss-store-derivation
+
 If *files* is the character `-`, then a Nix expression will be read from
 standard input.
 
@@ -79,8 +80,7 @@ standard input.
 
 # Examples
 
-Instantiating store derivations from a Nix expression, and building them
-using `nix-store`:
+Instantiate [store derivation]s from a Nix expression, and build them using `nix-store`:
 
 ```console
 $ nix-instantiate test.nix (instantiate)
diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md
index ecd838e8d..acf29e4aa 100644
--- a/doc/manual/src/command-ref/nix-store.md
+++ b/doc/manual/src/command-ref/nix-store.md
@@ -22,7 +22,8 @@ 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.
 
-  - [`--add-root`]{#opt-add-root} *path*\
+  - <span id="opt-add-root">[`--add-root`](#opt-add-root)</span> *path*
+
     Causes the result of a realisation (`--realise` and
     `--force-realise`) to be registered as a root of the garbage
     collector. *path* will be created as a symlink to the resulting
@@ -71,7 +72,7 @@ paths. Realisation is a somewhat overloaded term:
     outputs are already valid, in which case we are done
     immediately. Otherwise, there may be [substitutes](../glossary.md)
     that produce the outputs (e.g., by downloading them). Finally, the
-    outputs can be produced by performing the build action described
+    outputs can be produced by running the build task described
     by the derivation.
 
   - If the store path is not a derivation, realisation ensures that the
@@ -104,10 +105,6 @@ The following flags are available:
     previous build, the new output path is left in
     `/nix/store/name.check.`
 
-    See also the `build-repeat` configuration option, which repeats a
-    derivation a number of times and prevents its outputs from being
-    registered as “valid” in the Nix store unless they are identical.
-
 Special exit codes:
 
   - `100`\
@@ -140,8 +137,10 @@ or.
 
 ## Examples
 
-This operation is typically used to build store derivations produced by
-[`nix-instantiate`](nix-instantiate.md):
+This operation is typically used to build [store derivation]s produced by
+[`nix-instantiate`](./nix-instantiate.md):
+
+[store derivation]: ../glossary.md#gloss-store-derivation
 
 ```console
 $ nix-store -r $(nix-instantiate ./test.nix)
@@ -301,7 +300,7 @@ symlink.
 ## Common query options
 
   - `--use-output`; `-u`\
-    For each argument to the query that is a store derivation, apply the
+    For each argument to the query that is a [store derivation], apply the
     query to the output path of the derivation instead.
 
   - `--force-realise`; `-f`\
@@ -321,7 +320,7 @@ symlink.
     This query has one option:
 
       - `--include-outputs`
-        Also include the existing output paths of store derivations,
+        Also include the existing output paths of [store derivation]s,
         and their closures.
 
     This query can be used to implement various kinds of deployment. A
@@ -375,12 +374,12 @@ symlink.
     Prints the references graph of the store paths *paths* in the
     [GraphML](http://graphml.graphdrawing.org/) file format. This can be
     used to visualise dependency graphs. To obtain a build-time
-    dependency graph, apply this to a store derivation. To obtain a
+    dependency graph, apply this to a [store derivation]. To obtain a
     runtime dependency graph, apply it to an output path.
 
   - `--binding` *name*; `-b` *name*\
     Prints the value of the attribute *name* (i.e., environment
-    variable) of the store derivations *paths*. It is an error for a
+    variable) of the [store derivation]s *paths*. It is an error for a
     derivation to not have the specified attribute.
 
   - `--hash`\
diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index 9f7d5057b..c9da1962f 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -99,8 +99,79 @@ You can run the whole testsuite with `make check`, or the tests for a specific c
 ### Functional tests
 
 The functional tests reside under the `tests` directory and are listed in `tests/local.mk`.
-The whole testsuite can be run with `make install && make installcheck`.
-Individual tests can be run with `make tests/{testName}.sh.test`.
+Each test is a bash script.
+
+The whole test suite can be run with:
+
+```shell-session
+$ make install && make installcheck
+ran test tests/foo.sh... [PASS]
+ran test tests/bar.sh... [PASS]
+...
+```
+
+Individual tests can be run with `make`:
+
+```shell-session
+$ make tests/${testName}.sh.test
+ran test tests/${testName}.sh... [PASS]
+```
+
+or without `make`:
+
+```shell-session
+$ ./mk/run-test.sh tests/${testName}.sh
+ran test tests/${testName}.sh... [PASS]
+```
+
+To see the complete output, one can also run:
+
+```shell-session
+$ ./mk/debug-test.sh tests/${testName}.sh
++ foo
+output from foo
++ bar
+output from bar
+...
+```
+
+The test script will then be traced with `set -x` and the output displayed as it happens, regardless of whether the test succeeds or fails.
+
+#### Debugging failing functional tests
+
+When a functional test fails, it usually does so somewhere in the middle of the script.
+
+To figure out what's wrong, it is convenient to run the test regularly up to the failing `nix` command, and then run that command with a debugger like GDB.
+
+For example, if the script looks like:
+
+```bash
+foo
+nix blah blub
+bar
+```
+edit it like so:
+
+```diff
+ foo
+-nix blah blub
++gdb --args nix blah blub
+ bar
+```
+
+Then, running the test with `./mk/debug-test.sh` will drop you into GDB once the script reaches that point:
+
+```shell-session
+$ ./mk/debug-test.sh tests/${testName}.sh
+...
++ gdb blash blub
+GNU gdb (GDB) 12.1
+...
+(gdb)
+```
+
+One can debug the Nix invocation in all the usual ways.
+For example, enter `run` to start the Nix invocation.
 
 ### Integration tests
 
diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 70a0eb994..e63f6becc 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -1,20 +1,32 @@
 # Glossary
 
   - [derivation]{#gloss-derivation}\
-    A description of a build action. The result of a derivation is a
+    A description of a build task. The result of a derivation is a
     store object. Derivations are typically specified in Nix expressions
-    using the [`derivation` primitive](language/derivations.md). These are
+    using the [`derivation` primitive](./language/derivations.md). These are
     translated into low-level *store derivations* (implicitly by
     `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
 
+    [derivation]: #gloss-derivation
+
+  - [store derivation]{#gloss-store-derivation}\
+    A [derivation] represented as a `.drv` file in the [store].
+    It has a [store path], like any [store object].
+
+    Example: `/nix/store/g946hcz4c8mdvq2g8vxx42z51qb71rvp-git-2.38.1.drv`
+
+    See [`nix show-derivation`](./command-ref/new-cli/nix3-show-derivation.md) (experimental) for displaying the contents of store derivations.
+
+    [store derivation]: #gloss-store-derivation
+
   - [content-addressed derivation]{#gloss-content-addressed-derivation}\
     A derivation which has the
-    [`__contentAddressed`](language/advanced-attributes.md#adv-attr-__contentAddressed)
+    [`__contentAddressed`](./language/advanced-attributes.md#adv-attr-__contentAddressed)
     attribute set to `true`.
 
   - [fixed-output derivation]{#gloss-fixed-output-derivation}\
     A derivation which includes the
-    [`outputHash`](language/advanced-attributes.md#adv-attr-outputHash) attribute.
+    [`outputHash`](./language/advanced-attributes.md#adv-attr-outputHash) attribute.
 
   - [store]{#gloss-store}\
     The location in the file system where store objects live. Typically
@@ -34,6 +46,8 @@
       directory on another machine,  accessed via `ssh` or
       served by the `nix-serve` Perl script.
 
+    [store]: #gloss-store
+
   - [chroot store]{#gloss-chroot-store}\
     A local store whose canonical path is anything other than `/nix/store`.
 
@@ -46,15 +60,21 @@
     cache](https://cache.nixos.org).
 
   - [store path]{#gloss-store-path}\
-    The location in the file system of a store object, i.e., an
+    The location of a [store object] in the file system, i.e., an
     immediate child of the Nix store directory.
 
+    Example: `/nix/store/a040m110amc4h71lds2jmr8qrkj2jhxd-git-2.38.1`
+
+    [store path]: #gloss-store-path
+
   - [store object]{#gloss-store-object}\
     A file that is an immediate child of the Nix store directory. These
     can be regular files, but also entire directory trees. Store objects
     can be sources (objects copied from outside of the store),
-    derivation outputs (objects produced by running a build action), or
-    derivations (files describing a build action).
+    derivation outputs (objects produced by running a build task), or
+    derivations (files describing a build task).
+
+    [store object]: #gloss-store-object
 
   - [input-addressed store object]{#gloss-input-addressed-store-object}\
     A store object produced by building a
@@ -79,7 +99,7 @@
   - [substituter]{#gloss-substituter}\
     A *substituter* is an additional store from which Nix will
     copy store objects it doesn't have.  For details, see the
-    [`substituters` option](command-ref/conf-file.html#conf-substituters).
+    [`substituters` option](./command-ref/conf-file.md#conf-substituters).
 
   - [purity]{#gloss-purity}\
     The assumption that equal Nix derivations when run always produce
@@ -124,7 +144,9 @@
     references `R` then `R` is also in the closure of `P`.
 
   - [output path]{#gloss-output-path}\
-    A store path produced by a derivation.
+    A [store path] produced by a [derivation].
+
+    [output path]: #gloss-output-path
 
   - [deriver]{#gloss-deriver}\
     The deriver of an *output path* is the store
@@ -139,7 +161,7 @@
     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`](command-ref/nix-env.md). See *profiles*.
+    [`nix-env`](./command-ref/nix-env.md). See *profiles*.
 
   - [profile]{#gloss-profile}\
     A symlink to the current *user environment* of a user, e.g.,
@@ -150,7 +172,18 @@
     store. It can contain regular files, directories and symbolic
     links.  NARs are generated and unpacked using `nix-store --dump`
     and `nix-store --restore`.
+
   - [`∅`]{#gloss-emtpy-set}\
     The empty set symbol. In the context of profile history, this denotes a package is not present in a particular version of the profile.
+
   - [`ε`]{#gloss-epsilon}\
     The epsilon symbol. In the context of a package, this means the version is empty. More precisely, the derivation does not have a version attribute.
+
+  - [string interpolation]{#gloss-string-interpolation}\
+    Expanding expressions enclosed in `${ }` within a [string], [path], or [attribute name].
+
+    See [String interpolation](./language/string-interpolation.md) for details.
+
+    [string]: ./language/values.md#type-string
+    [path]: ./language/values.md#type-path
+    [attribute name]: ./language/values.md#attribute-set
diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index 2d007ca1b..a9378681d 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -88,19 +88,51 @@ extension. The installer will also create `/etc/profile.d/nix.sh`.
 
 ### Linux
 
+If you are on Linux with systemd:
+
+1. Remove the Nix daemon service:
+
+   ```console
+   sudo systemctl stop nix-daemon.service
+   sudo systemctl disable nix-daemon.socket nix-daemon.service
+   sudo systemctl daemon-reload
+   ```
+
+1. Remove systemd service files:
+
+   ```console
+   sudo rm /etc/systemd/system/nix-daemon.service /etc/systemd/system/nix-daemon.socket
+   ```
+
+1. The installer script uses systemd-tmpfiles to create the socket directory.
+    You may also want to remove the configuration for that:
+
+   ```console
+   sudo rm /etc/tmpfiles.d/nix-daemon.conf
+   ```
+
+Remove files created by Nix:
+
+```console
+sudo rm -rf /nix /etc/nix /etc/profile/nix.sh ~root/.nix-profile ~root/.nix-defexpr ~root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels
+```
+
+Remove build users and their group:
+
 ```console
-sudo rm -rf /etc/profile/nix.sh /etc/nix /nix ~root/.nix-profile ~root/.nix-defexpr ~root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels
-
-# If you are on Linux with systemd, you will need to run:
-sudo systemctl stop nix-daemon.socket
-sudo systemctl stop nix-daemon.service
-sudo systemctl disable nix-daemon.socket
-sudo systemctl disable nix-daemon.service
-sudo systemctl daemon-reload
+for i in $(seq 30001 30032); do
+  sudo userdel $i
+done
+sudo groupdel 30000
 ```
 
-There may also be references to Nix in `/etc/profile`, `/etc/bashrc`,
-and `/etc/zshrc` which you may remove.
+There may also be references to Nix in
+
+- `/etc/profile`
+- `/etc/bashrc`
+- `/etc/zshrc`
+
+which you may remove.
 
 ### macOS
 
diff --git a/doc/manual/src/introduction.md b/doc/manual/src/introduction.md
index d87487a07..b54346db8 100644
--- a/doc/manual/src/introduction.md
+++ b/doc/manual/src/introduction.md
@@ -104,7 +104,7 @@ a currently running program.
 
 Packages are built from _Nix expressions_, which is a simple
 functional language.  A Nix expression describes everything that goes
-into a package build action (a “derivation”): other packages, sources,
+into a package build task (a “derivation”): other packages, sources,
 the build script, environment variables for the build script, etc.
 Nix tries very hard to ensure that Nix expressions are
 _deterministic_: building a Nix expression twice should yield the same
diff --git a/doc/manual/src/language/derivations.md b/doc/manual/src/language/derivations.md
index 3391ec0d8..043a38191 100644
--- a/doc/manual/src/language/derivations.md
+++ b/doc/manual/src/language/derivations.md
@@ -1,7 +1,7 @@
 # Derivations
 
 The most important built-in function is `derivation`, which is used to
-describe a single derivation (a build action). It takes as input a set,
+describe a single derivation (a build task). It takes as input a set,
 the attributes of which specify the inputs of the build.
 
   - There must be an attribute named [`system`]{#attr-system} whose value must be a
diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index a4b402f8b..db34fde75 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -31,3 +31,551 @@ The Nix language is
 
   Type errors are only detected when expressions are evaluated.
 
+# Overview
+
+This is an incomplete overview of language features, by example.
+
+<table>
+ <tr>
+  <th>
+   Example
+  </th>
+  <th>
+   Description
+  </th>
+ </tr>
+ <tr>
+  <td>
+
+
+   *Basic values*
+
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `"hello world"`
+
+  </td>
+  <td>
+
+   A string
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   ```
+   ''
+     multi
+      line
+       string
+   ''
+   ```
+
+  </td>
+  <td>
+
+   A multi-line string. Strips common prefixed whitespace. Evaluates to `"multi\n line\n  string"`.
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `"hello ${ { a = "world" }.a }"`
+
+   `"1 2 ${toString 3}"`
+
+   `"${pkgs.bash}/bin/sh"`
+
+  </td>
+  <td>
+
+   String interpolation (expands to `"hello world"`, `"1 2 3"`, `"/nix/store/<hash>-bash-<version>/bin/sh"`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `true`, `false`
+
+  </td>
+  <td>
+
+   Booleans
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `null`
+
+  </td>
+  <td>
+
+   Null value
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `123`
+
+  </td>
+  <td>
+
+   An integer
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `3.141`
+
+  </td>
+  <td>
+
+   A floating point number
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `/etc`
+
+  </td>
+  <td>
+
+   An absolute path
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `./foo.png`
+
+  </td>
+  <td>
+
+   A path relative to the file containing this Nix expression
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `~/.config`
+
+  </td>
+  <td>
+
+   A home path. Evaluates to the `"<user's home directory>/.config"`.
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   <nixpkgs>
+
+  </td>
+  <td>
+
+   Search path. Value determined by [`$NIX_PATH` environment variable](../command-ref/env-common.md#env-NIX_PATH).
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   *Compound values*
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x = 1; y = 2; }`
+
+  </td>
+  <td>
+
+   A set with attributes named `x` and `y`
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ foo.bar = 1; }`
+
+  </td>
+  <td>
+
+   A nested set, equivalent to `{ foo = { bar = 1; }; }`
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `rec { x = "foo"; y = x + "bar"; }`
+
+  </td>
+  <td>
+
+   A recursive set, equivalent to `{ x = "foo"; y = "foobar"; }`
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `[ "foo" "bar" "baz" ]`
+
+   `[ 1 2 3 ]`
+
+   `[ (f 1) { a = 1; b = 2; } [ "c" ] ]`
+
+  </td>
+  <td>
+
+   Lists with three elements.
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   *Operators*
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `"foo" + "bar"`
+
+  </td>
+  <td>
+
+   String concatenation
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `1 + 2`
+
+  </td>
+  <td>
+
+   Integer addition
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `"foo" == "f" + "oo"`
+
+  </td>
+  <td>
+
+   Equality test (evaluates to `true`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `"foo" != "bar"`
+
+  </td>
+  <td>
+
+   Inequality test (evaluates to `true`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `!true`
+
+  </td>
+  <td>
+
+   Boolean negation
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x = 1; y = 2; }.x`
+
+  </td>
+  <td>
+
+   Attribute selection (evaluates to `1`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x = 1; y = 2; }.z or 3`
+
+  </td>
+  <td>
+
+   Attribute selection with default (evaluates to `3`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x = 1; y = 2; } // { z = 3; }`
+
+  </td>
+  <td>
+
+   Merge two sets (attributes in the right-hand set taking precedence)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   *Control structures*
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `if 1 + 1 == 2 then "yes!" else "no!"`
+
+  </td>
+  <td>
+
+   Conditional expression
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `assert 1 + 1 == 2; "yes!"`
+
+  </td>
+  <td>
+
+   Assertion check (evaluates to `"yes!"`).
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `let x = "foo"; y = "bar"; in x + y`
+
+  </td>
+  <td>
+
+   Variable definition
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `with builtins; head [ 1 2 3 ]`
+
+  </td>
+  <td>
+
+   Add all attributes from the given set to the scope (evaluates to `1`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   *Functions (lambdas)*
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `x: x + 1`
+
+  </td>
+  <td>
+
+   A function that expects an integer and returns it increased by 1
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `x: y: x + y`
+
+  </td>
+  <td>
+
+   Curried function, equivalent to `x: (y: x + y)`. Can be used like a function that takes two arguments and returns their sum.
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `(x: x + 1) 100`
+
+  </td>
+  <td>
+
+   A function call (evaluates to 101)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `let inc = x: x + 1; in inc (inc (inc 100))`
+
+  </td>
+  <td>
+
+   A function bound to a variable and subsequently called by name (evaluates to 103)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x, y }: x + y`
+
+  </td>
+  <td>
+
+   A function that expects a set with required attributes `x` and `y` and concatenates them
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x, y ? "bar" }: x + y`
+
+  </td>
+  <td>
+
+   A function that expects a set with required attribute `x` and optional `y`, using `"bar"` as default value for `y`
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x, y, ... }: x + y`
+
+  </td>
+  <td>
+
+   A function that expects a set with required attributes `x` and `y` and ignores any other attributes
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x, y } @ args: x + y`
+
+   `args @ { x, y }: x + y`
+
+  </td>
+  <td>
+
+   A function that expects a set with required attributes `x` and `y`, and binds the whole set to `args`
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   *Built-in functions*
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `import ./foo.nix`
+
+  </td>
+  <td>
+
+   Load and return Nix expression in given file
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `map (x: x + x) [ 1 2 3 ]`
+
+  </td>
+  <td>
+
+   Apply a function to every element of a list (evaluates to `[ 2 4 6 ]`)
+
+  </td>
+ </tr>
+</table>
diff --git a/doc/manual/src/language/string-interpolation.md b/doc/manual/src/language/string-interpolation.md
new file mode 100644
index 000000000..ddc6b8230
--- /dev/null
+++ b/doc/manual/src/language/string-interpolation.md
@@ -0,0 +1,82 @@
+# String interpolation
+
+String interpolation is a language feature where a [string], [path], or [attribute name] can contain expressions enclosed in `${ }` (dollar-sign with curly brackets).
+
+Such a string is an *interpolated string*, and an expression inside is an *interpolated expression*.
+
+Interpolated expressions must evaluate to one of the following:
+
+- a [string]
+- a [path]
+- a [derivation]
+
+[string]: ./values.md#type-string
+[path]: ./values.md#type-path
+[attribute name]: ./values.md#attribute-set
+[derivation]: ../glossary.md#gloss-derivation
+
+## Examples
+
+### String
+
+Rather than writing
+
+```nix
+"--with-freetype2-library=" + freetype + "/lib"
+```
+
+(where `freetype` is a [derivation]), you can instead write
+
+```nix
+"--with-freetype2-library=${freetype}/lib"
+```
+
+The latter is automatically translated to the former.
+
+A more complicated example (from the Nix expression for [Qt](http://www.trolltech.com/products/qt)):
+
+```nix
+configureFlags = "
+  -system-zlib -system-libpng -system-libjpeg
+  ${if openglSupport then "-dlopen-opengl
+    -L${mesa}/lib -I${mesa}/include
+    -L${libXmu}/lib -I${libXmu}/include" else ""}
+  ${if threadSupport then "-thread" else "-no-thread"}
+";
+```
+
+Note that Nix expressions and strings can be arbitrarily nested;
+in this case the outer string contains various interpolated expressions that themselves contain strings (e.g., `"-thread"`), some of which in turn contain interpolated expressions (e.g., `${mesa}`).
+
+### Path
+
+Rather than writing
+
+```nix
+./. + "/" + foo + "-" + bar + ".nix"
+```
+
+or
+
+```nix
+./. + "/${foo}-${bar}.nix"
+```
+
+you can instead write
+
+```nix
+./${foo}-${bar}.nix
+```
+
+### Attribute name
+
+Attribute names can be created dynamically with string interpolation:
+
+```nix
+let name = "foo"; in
+{
+  ${name} = "bar";
+}
+```
+
+    { foo = "bar"; }
diff --git a/doc/manual/src/language/values.md b/doc/manual/src/language/values.md
index f09400d02..08baa8f95 100644
--- a/doc/manual/src/language/values.md
+++ b/doc/manual/src/language/values.md
@@ -13,41 +13,9 @@
   returns and tabs can be written as `\n`, `\r` and `\t`,
   respectively.
 
-  You can include the result of an expression into a string by
-  enclosing it in `${...}`, a feature known as *antiquotation*. The
-  enclosed expression must evaluate to something that can be coerced
-  into a string (meaning that it must be a string, a path, or a
-  derivation). For instance, rather than writing
+  You can include the results of other expressions into a string by enclosing them in `${ }`, a feature known as [string interpolation].
 
-  ```nix
-  "--with-freetype2-library=" + freetype + "/lib"
-  ```
-
-  (where `freetype` is a derivation), you can instead write the more
-  natural
-
-  ```nix
-  "--with-freetype2-library=${freetype}/lib"
-  ```
-
-  The latter is automatically translated to the former. A more
-  complicated example (from the Nix expression for
-  [Qt](http://www.trolltech.com/products/qt)):
-
-  ```nix
-  configureFlags = "
-    -system-zlib -system-libpng -system-libjpeg
-    ${if openglSupport then "-dlopen-opengl
-      -L${mesa}/lib -I${mesa}/include
-      -L${libXmu}/lib -I${libXmu}/include" else ""}
-    ${if threadSupport then "-thread" else "-no-thread"}
-  ";
-  ```
-
-  Note that Nix expressions and strings can be arbitrarily nested; in
-  this case the outer string contains various antiquotations that
-  themselves contain strings (e.g., `"-thread"`), some of which in
-  turn contain expressions (e.g., `${mesa}`).
+  [string interpolation]: ./string-interpolation.md
 
   The second way to write string literals is as an *indented string*,
   which is enclosed between pairs of *double single-quotes*, like so:
@@ -75,7 +43,7 @@
   Note that the whitespace and newline following the opening `''` is
   ignored if there is no non-whitespace text on the initial line.
 
-  Antiquotation (`${expr}`) is supported in indented strings.
+  Indented strings support [string interpolation].
 
   Since `${` and `''` have special meaning in indented strings, you
   need a way to quote them. `$` can be escaped by prefixing it with
@@ -143,12 +111,23 @@
   environment variable `NIX_PATH` will be searched for the given file
   or directory name.
 
-  Antiquotation is supported in any paths except those in angle brackets.
-  `./${foo}-${bar}.nix` is a more convenient way of writing
-  `./. + "/" + foo + "-" + bar + ".nix"` or `./. + "/${foo}-${bar}.nix"`. At
-  least one slash must appear *before* any antiquotations for this to be
-  recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
-  operation. `./a.${foo}/b.${bar}` is a path.
+  When an [interpolated string][string interpolation] evaluates to a path, the path is first copied into the Nix store and the resulting string is the [store path] of the newly created [store object].
+
+  [store path]: ../glossary.md#gloss-store-path
+  [store object]: ../glossary.md#gloss-store-object
+
+  For instance, evaluating `"${./foo.txt}"` will cause `foo.txt` in the current directory to be copied into the Nix store and result in the string `"/nix/store/<hash>-foo.txt"`.
+
+  Note that the Nix language assumes that all input files will remain _unchanged_ while  evaluating a Nix expression.
+  For example, assume you used a file path in an interpolated string during a `nix repl` session.
+  Later in the same session, after having changed the file contents, evaluating the interpolated string with the file path again might not return a new store path, since Nix might not re-read the file contents.
+
+  Paths themselves, except those in angle brackets (`< >`), support [string interpolation].
+
+  At least one slash (`/`) must appear *before* any interpolated expression for the result to be recognized as a path.
+
+  `a.${foo}/b.${bar}` is a syntactically valid division operation.
+  `./a.${foo}/b.${bar}` is a path.
 
 - <a id="type-boolean" href="#type-boolean">Boolean</a>
 
@@ -221,23 +200,33 @@ will evaluate to `"Xyzzy"` because there is no `c` attribute in the set.
 You can use arbitrary double-quoted strings as attribute names:
 
 ```nix
-{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}"
+{ "$!@#?" = 123; }."$!@#?"
+```
+
+```nix
+let bar = "bar";
+{ "foo ${bar}" = 123; }."foo ${bar}"
 ```
 
-This will evaluate to `123` (Assuming `bar` is antiquotable). In the
-case where an attribute name is just a single antiquotation, the quotes
-can be dropped:
+Both will evaluate to `123`.
+
+Attribute names support [string interpolation]:
+
+```nix
+let bar = "foo"; in
+{ foo = 123; }.${bar}
+```
 
 ```nix
-{ foo = 123; }.${bar} or 456
+let bar = "foo"; in
+{ ${bar} = 123; }.foo
 ```
 
-This will evaluate to `123` if `bar` evaluates to `"foo"` when coerced
-to a string and `456` otherwise (again assuming `bar` is antiquotable).
+Both will evaluate to `123`.
 
 In the special case where an attribute name inside of a set declaration
-evaluates to `null` (which is normally an error, as `null` is not
-antiquotable), that attribute is simply not added to the set:
+evaluates to `null` (which is normally an error, as `null` cannot be coerced to
+a string), that attribute is simply not added to the set:
 
 ```nix
 { ${if foo then "bar" else null} = true; }
diff --git a/doc/manual/src/release-notes/rl-2.12.md b/doc/manual/src/release-notes/rl-2.12.md
new file mode 100644
index 000000000..e2045d7bf
--- /dev/null
+++ b/doc/manual/src/release-notes/rl-2.12.md
@@ -0,0 +1,43 @@
+# Release 2.12 (2022-12-06)
+
+* On Linux, Nix can now run builds in a user namespace where they run
+  as root (UID 0) and have 65,536 UIDs available.
+  <!-- FIXME: move this to its own section about system features -->
+  This is primarily useful for running containers such as `systemd-nspawn`
+  inside a Nix build. For an example, see [`tests/systemd-nspawn/nix`][nspawn].
+
+  [nspawn]: https://github.com/NixOS/nix/blob/67bcb99700a0da1395fa063d7c6586740b304598/tests/systemd-nspawn.nix.
+
+  A build can enable this by setting the derivation attribute:
+
+  ```
+  requiredSystemFeatures = [ "uid-range" ];
+  ```
+
+  The `uid-range` [system feature] requires the [`auto-allocate-uids`]
+  setting to be enabled.
+
+  [system feature]: ../command-ref/conf-file.md#conf-system-features
+
+* Nix can now automatically pick UIDs for builds, removing the need to
+  create `nixbld*` user accounts. See [`auto-allocate-uids`].
+
+  [`auto-allocate-uids`]: ../command-ref/conf-file.md#conf-auto-allocate-uids
+
+* On Linux, Nix has experimental support for running builds inside a
+  cgroup. See
+  [`use-cgroups`](../command-ref/conf-file.md#conf-use-cgroups).
+
+* `<nix/fetchurl.nix>` now accepts an additional argument `impure` which
+  defaults to `false`.  If it is set to `true`, the `hash` and `sha256`
+  arguments will be ignored and the resulting derivation will have
+  `__impure` set to `true`, making it an impure derivation.
+
+* If `builtins.readFile` is called on a file with context, then only
+  the parts of the context that appear in the content of the file are
+  retained.  This avoids a lot of spurious errors where strings end up
+  having a context just because they are read from a store path
+  ([#7260](https://github.com/NixOS/nix/pull/7260)).
+
+* `nix build --json` now prints some statistics about top-level
+  derivations, such as CPU statistics when cgroups are enabled.
diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index a08dc9c9b..9f491efc8 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -1,9 +1,23 @@
 # Release X.Y (202?-??-??)
 
-* `<nix/fetchurl.nix>` now accepts an additional argument `impure` which
-  defaults to `false`.  If it is set to `true`, the `hash` and `sha256`
-  arguments will be ignored and the resulting derivation will have
-  `__impure` set to `true`, making it an impure derivation.
+* The `repeat` and `enforce-determinism` options have been removed
+  since they had been broken under many circumstances for a long time.
+
+* You can now use [flake references] in the [old command line interface], e.g.
+
+   [flake references]: ../command-ref/new-cli/nix3-flake.md#flake-references
+   [old command line interface]: ../command-ref/main-commands.md
+
+  ```
+  # nix-build flake:nixpkgs -A hello
+  # nix-build -I nixpkgs=flake:github:NixOS/nixpkgs/nixos-22.05 \
+      '<nixpkgs>' -A hello
+  # NIX_PATH=nixpkgs=flake:nixpkgs nix-build '<nixpkgs>' -A hello
+  ```
+
+* Instead of "antiquotation", the more common term [string interpolation](../language/string-interpolation.md) is now used consistently.
+  Historical release notes were not changed.
+
 * Error traces have been reworked to provide detailed explanations and more
   accurate error locations. A short excerpt of the trace is now shown by
   default when an error occurs.