From da4d4feacf76a829ee7929c3d69f6f3d6ba86f1f Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Tue, 3 Jan 2023 11:36:01 +0100
Subject: [PATCH] doc/manual/hacking: Document @docroot@ variable

---
 doc/manual/local.mk                    |  3 +++
 doc/manual/src/contributing/hacking.md | 10 ++++++++--
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/doc/manual/local.mk b/doc/manual/local.mk
index 7639f510a..190f0258a 100644
--- a/doc/manual/local.mk
+++ b/doc/manual/local.mk
@@ -51,11 +51,13 @@ $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli
 $(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/generate-manpage.nix $(bindir)/nix
 	@rm -rf $@
 	$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix { toplevel = builtins.readFile $<; }'
+	# @docroot@: https://nixos.org/manual/nix/unstable/contributing/hacking.html#docroot-variable
 	$(trace-gen) sed -i $@.tmp/*.md -e 's^@docroot@^../..^g'
 	@mv $@.tmp $@
 
 $(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/generate-options.nix $(d)/src/command-ref/conf-file-prefix.md $(bindir)/nix
 	@cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp
+	# @docroot@: https://nixos.org/manual/nix/unstable/contributing/hacking.html#docroot-variable
 	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-options.nix (builtins.fromJSON (builtins.readFile $<))' \
 	  | sed -e 's^@docroot@^..^g'>> $@.tmp
 	@mv $@.tmp $@
@@ -70,6 +72,7 @@ $(d)/conf-file.json: $(bindir)/nix
 
 $(d)/src/language/builtins.md: $(d)/builtins.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(bindir)/nix
 	@cat doc/manual/src/language/builtins-prefix.md > $@.tmp
+	# @docroot@: https://nixos.org/manual/nix/unstable/contributing/hacking.html#docroot-variable
 	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' \
 	  | sed -e 's^@docroot@^..^g' >> $@.tmp
 	@cat doc/manual/src/language/builtins-suffix.md >> $@.tmp
diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index fe24294f8..b9b327fba 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -268,9 +268,15 @@ In order to reflect changes to the [Makefile], clear all generated files before
 rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/src/command-ref/new-cli && make html -j $NIX_BUILD_CORES
 ```
 
-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.
-
 [`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 (probably) generated source file that mentions it. See existing `@docroot@` logic in the [Makefile]. Regular markdown files that are not copied to other markdown files do have a base path of their own and they can use relative paths instead of `@docroot@`.