Merge remote-tracking branch 'upstream/master' into path-info

5 files changed, 42 insertions, 3 deletions

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 2d1b26558..e51958052 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -68,7 +68,7 @@ It can also execute build plans to produce new data, which are made available to
 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).
+> A build task in Nix is called [derivation](../glossary.md#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.
diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md
index 5845bdc43..bb85a6b07 100644
--- a/doc/manual/src/command-ref/env-common.md
+++ b/doc/manual/src/command-ref/env-common.md
@@ -11,7 +11,7 @@ Most Nix commands interpret the following environment variables:
     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).
+    [`-I` option](./opt-common.md#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-copy-closure.md b/doc/manual/src/command-ref/nix-copy-closure.md
index 83e8a2936..cd8e351bb 100644
--- a/doc/manual/src/command-ref/nix-copy-closure.md
+++ b/doc/manual/src/command-ref/nix-copy-closure.md
@@ -49,7 +49,7 @@ authentication, you can avoid typing the passphrase with `ssh-agent`.
   - `--include-outputs`\
     Also copy the outputs of [store derivation]s included in the closure.
 
-    [store derivation]: ../../glossary.md#gloss-store-derivation
+    [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-store.md b/doc/manual/src/command-ref/nix-store.md
index acf29e4aa..6d0e02ca5 100644
--- a/doc/manual/src/command-ref/nix-store.md
+++ b/doc/manual/src/command-ref/nix-store.md
@@ -155,6 +155,12 @@ To test whether a previously-built derivation is deterministic:
 $ nix-build '<nixpkgs>' -A hello --check -K
 ```
 
+Use [`--read-log`](#operation---read-log) to show the stderr and stdout of a build:
+
+```console
+$ nix-store --read-log $(nix-instantiate ./test.nix)
+```
+
 # Operation `--serve`
 
 ## Synopsis
diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index c9da1962f..aeb0d41b3 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -249,3 +249,36 @@ search/replaced in it for each new build.
 The installer now supports a `--tarball-url-prefix` flag which _may_ have
 solved this need?
 -->
+
+### Checking links in the manual
+
+The build checks for broken internal links.
+This happens late in the process, so `nix build` is not suitable for iterating.
+To build the manual incrementally, run:
+
+```console
+make html -j $NIX_BUILD_CORES
+```
+
+In order to reflect changes to the [Makefile], clear all generated files before re-building:
+
+[Makefile]: https://github.com/NixOS/nix/blob/master/doc/manual/local.mk
+
+```console
+rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/src/command-ref/new-cli && make html -j $NIX_BUILD_CORES
+```
+
+[`mdbook-linkcheck`] does not implement checking [URI fragments] yet.
+
+[`mdbook-linkcheck`]: https://github.com/Michael-F-Bryan/mdbook-linkcheck
+[URI fragments]: https://en.m.wikipedia.org/wiki/URI_fragment
+
+#### `@docroot@` variable
+
+`@docroot@` provides a base path for links that occur in reusable snippets or other documentation that doesn't have a base path of its own.
+
+If a broken link occurs in a snippet that was inserted into multiple generated files in different directories, use `@docroot@` to reference the `doc/manual/src` directory.
+
+If the `@docroot@` literal appears in an error message from the `mdbook-linkcheck` tool, the `@docroot@` replacement needs to be applied to the generated source file that mentions it.
+See existing `@docroot@` logic in the [Makefile].
+Regular markdown files used for the manual have a base path of their own and they can use relative paths instead of `@docroot@`.