build: extract make "functions" into scripts

we'll want to use these for the meson builds, and probably eventually
rewrite them in something that isn't plain shell. diffoscope confirms
that out/share and doc/share are equal before and after these changes

Change-Id: I49aa418fc8615cad86d67328e08c28a7405ec952

doc/manual/local.mk

@@ -39,67 +39,30 @@ dummy-env = env -i \
 
 nix-eval = $(dummy-env) $(doc_nix) eval --experimental-features nix-command -I nix/corepkgs=corepkgs --store dummy:// --impure --raw
 
-# re-implement mdBook's include directive to make it usable for terminal output and for proper @docroot@ substitution
-define process-includes
-	while read -r line; do \
-		set -euo pipefail; \
-		filename="$$(dirname $(1))/$$(sed 's/{{#include \(.*\)}}/\1/'<<< $$line)"; \
-		test -f "$$filename" || ( echo "#include-d file '$$filename' does not exist." >&2; exit 1; ); \
-		matchline="$$(sed 's|/|\\/|g' <<< $$line)"; \
-		sed -i "/$$matchline/r $$filename" $(2); \
-		sed -i "s/$$matchline//" $(2); \
-	done < <(grep '{{#include' $(1))
-endef
-
 $(d)/nix-env-%.1: $(d)/src/command-ref/nix-env/%.md
-	@printf "Title: %s\n\n" "$(subst nix-env-,nix-env --,$$(basename "$@" .1))" > $^.tmp
+	$(trace-gen) doc/manual/render-manpage.sh \
-	$(render-subcommand)
+		--unescape-dashes "$(subst nix-env-,nix-env --,$$(basename "$@" .1))" 1 $^ $^.tmp $@
 
 $(d)/nix-store-%.1: $(d)/src/command-ref/nix-store/%.md
-	@printf -- 'Title: %s\n\n' "$(subst nix-store-,nix-store --,$$(basename "$@" .1))" > $^.tmp
+	$(trace-gen) doc/manual/render-manpage.sh \
-	$(render-subcommand)
+		--unescape-dashes "$(subst nix-store-,nix-store --,$$(basename "$@" .1))" 1 $^ $^.tmp $@
-
-# FIXME: there surely is some more deduplication to be achieved here with even darker Make magic
-define render-subcommand
-  @cat $^ >> $^.tmp
-	@$(call process-includes,$^,$^.tmp)
-	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@
-	@# fix up `lowdown`'s automatic escaping of `--`
-	@# https://github.com/kristapsdz/lowdown/blob/edca6ce6d5336efb147321a43c47a698de41bb7c/entity.c#L202
-	@sed -i 's/\e\[u2013\]/--/' $@
-	@rm $^.tmp
-endef
 
 
 $(d)/%.1: $(d)/src/command-ref/%.md
-	@printf "Title: %s\n\n" "$$(basename $@ .1)" > $^.tmp
+	$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .1)" 1 $^ $^.tmp $@
-	@cat $^ >> $^.tmp
-	@$(call process-includes,$^,$^.tmp)
-	$(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
+	$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .8)" 8 $^ $^.tmp $@
-	@cat $^ >> $^.tmp
-	$(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
+	$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 $^ $^.tmp $@
-	@cat $^ >> $^.tmp
-	@$(call process-includes,$^,$^.tmp)
-	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
-	@rm $^.tmp
 
 $(d)/nix-profiles.5: $(d)/src/command-ref/files/profiles.md
-	@printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp
+	$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 $^ $^.tmp $@
-	@cat $^ >> $^.tmp
-	$(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/SUMMARY-rl-next.md $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md
 	@cp $< $@
-	@$(call process-includes,$@,$@)
+	@doc/manual/process-includes.sh $@ $@
 
 $(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(doc_nix)
 	@rm -rf $@ $@.tmp
@@ -201,7 +164,7 @@ $(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/
 		tmp="$$(mktemp -d)"; \
 		cp -r doc/manual "$$tmp"; \
 		find "$$tmp" -name '*.md' | while read -r file; do \
-			$(call process-includes,$$file,$$file); \
+			doc/manual/process-includes.sh $$file $$file; \
 		done; \
 		find "$$tmp" -name '*.md' | while read -r file; do \
 			docroot="$$(realpath --relative-to="$$(dirname "$$file")" $$tmp/manual/src)"; \

doc/manual/process-includes.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+
+set -euo pipefail
+
+# re-implement mdBook's include directive to make it usable for terminal output and for proper @docroot@ substitution
+(grep '{{#include' "$1" || true) | while read -r line; do
+    filename="$(dirname "$1")/$(printf "$line" | sed 's/{{#include \(.*\)}}/\1/')"
+    test -f "$filename" || ( echo "#include-d file '$filename' does not exist." >&2; exit 1; )
+    matchline="$(printf "$line" | sed 's|/|\\/|g')"
+    sed -i "/$matchline/r $filename" "$2"
+    sed -i "s/$matchline//" "$2"
+done

doc/manual/render-manpage.sh

@@ -0,0 +1,27 @@
+#!/bin/sh
+
+set -euo pipefail
+
+unescape_dashes=
+
+if [ "$1" = --unescape-dashes ]; then
+    unescape_dashes=yes
+    shift
+fi
+
+title="$1"
+section="$2"
+infile="$3"
+tmpfile="$4"
+outfile="$5"
+
+printf "Title: %s\n\n" "$title" > "$tmpfile"
+cat "$infile" >> "$tmpfile"
+"$(dirname "$0")"/process-includes.sh "$infile" "$tmpfile"
+lowdown -sT man --nroff-nolinks -M section="$section" "$tmpfile" -o "$outfile"
+if [ -n "$unescape_dashes" ]; then
+    # fix up `lowdown`'s automatic escaping of `--`
+    # https://github.com/kristapsdz/lowdown/blob/edca6ce6d5336efb147321a43c47a698de41bb7c/entity.c#L202
+    sed -i 's/\e\[u2013\]/--/' "$outfile"
+fi
+rm "$tmpfile"