From 65d544b1a631a139c369387618adbb2fe2fe9e1f Mon Sep 17 00:00:00 2001 From: eldritch horrors Date: Fri, 29 Mar 2024 20:06:55 +0100 Subject: [PATCH] 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 | 57 ++++++---------------------------- doc/manual/process-includes.sh | 12 +++++++ doc/manual/render-manpage.sh | 27 ++++++++++++++++ 3 files changed, 49 insertions(+), 47 deletions(-) create mode 100755 doc/manual/process-includes.sh create mode 100755 doc/manual/render-manpage.sh diff --git a/doc/manual/local.mk b/doc/manual/local.mk index b33a4f777..8899a671d 100644 --- a/doc/manual/local.mk +++ b/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 - $(render-subcommand) + $(trace-gen) doc/manual/render-manpage.sh \ + --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 - $(render-subcommand) - -# 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 + $(trace-gen) doc/manual/render-manpage.sh \ + --unescape-dashes "$(subst nix-store-,nix-store --,$$(basename "$@" .1))" 1 $^ $^.tmp $@ $(d)/%.1: $(d)/src/command-ref/%.md - @printf "Title: %s\n\n" "$$(basename $@ .1)" > $^.tmp - @cat $^ >> $^.tmp - @$(call process-includes,$^,$^.tmp) - $(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@ - @rm $^.tmp + $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .1)" 1 $^ $^.tmp $@ $(d)/%.8: $(d)/src/command-ref/%.md - @printf "Title: %s\n\n" "$$(basename $@ .8)" > $^.tmp - @cat $^ >> $^.tmp - $(trace-gen) lowdown -sT man --nroff-nolinks -M section=8 $^.tmp -o $@ - @rm $^.tmp + $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .8)" 8 $^ $^.tmp $@ $(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md - @printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp - @cat $^ >> $^.tmp - @$(call process-includes,$^,$^.tmp) - $(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@ - @rm $^.tmp + $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 $^ $^.tmp $@ $(d)/nix-profiles.5: $(d)/src/command-ref/files/profiles.md - @printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp - @cat $^ >> $^.tmp - $(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@ - @rm $^.tmp + $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 $^ $^.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)"; \ diff --git a/doc/manual/process-includes.sh b/doc/manual/process-includes.sh new file mode 100755 index 000000000..6d75710ad --- /dev/null +++ b/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 diff --git a/doc/manual/render-manpage.sh b/doc/manual/render-manpage.sh new file mode 100755 index 000000000..d89c29482 --- /dev/null +++ b/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"