docs: The Book of Fabric -- the FABRIC design record as one book, built and published with every release (#138) [skip ci]

`make fabric` -> build/docs/BookOfFabric.pdf (722 pages): Part I the living
record (FABRIC-3), Part II the closed documents in the order written, Part
III the forward-looking notes; its title page carries the version (git
describe --tags: a release's tag) and the commit. Built from the same pandoc
fragments as the book; the book's preamble moved into docs/book/preamble.tex,
shared by both (the book builds as before, 821 pages).

scripts/nightly.sh: the docs stage builds it ($DOCS/fabric.pdf); publish
sends it as classifier `fabric`; gitea-release attaches every PDF in $DOCS,
so every release carries it. Progress for the rest of alpha.4's documents:
docs/v4.0.0/plans/2026-11-10-alpha4-documents.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GE3SDvQn5EoxdGufk84zz2
This commit is contained in:
Claude
2026-11-10 11:21:32 +00:00
parent 836b4423e1
commit 41abad0159
7 changed files with 234 additions and 102 deletions
+30 -5
View File
@@ -57,8 +57,15 @@ chapter_name = $(word 1,$(subst :, ,$(1)))
chapter_src = $(word 2,$(subst :, ,$(1)))
FRAGMENTS := $(foreach c,$(CHAPTERS),$(GEN)/$(call chapter_name,$(c)).tex)
.PHONY: all tools FORCE
# The Book of Fabric (#138): the FABRIC design record alone, as one book, from
# the same fragments -- `make fabric` -> build/docs/BookOfFabric.pdf.
FABRIC_DIR := $(OUT)/fabric
FABRIC_PDF := $(OUT)/BookOfFabric.pdf
FABRIC_FRAGS := $(foreach n,fabric-0 fabric-1 fabric-2 fabric-3 fabric-3-5 fabric-3-6 fabric-3-7 fabric-4,$(GEN)/$(n).tex)
.PHONY: all fabric tools FORCE
all: $(PDF)
fabric: $(FABRIC_PDF)
tools:
@missing=""; \
@@ -86,25 +93,32 @@ $(GEN)/pandoc-highlighting.tex: $(BOOK_DIR)/pandoc/highlighting.latex | tools
@mkdir -p $(GEN)
@printf '```c\nx\n```\n' | $(PANDOC) -f gfm -t latex -s --template=$< -o $@
# Per-build facts the book prints: the commit every \datasource refers to,
# Per-build facts the books print: the commit every \datasource refers to,
# the version (git describe: a release's tag, or the tag and the commits since),
# and which board appendix (if any) is included.
$(VAR_DIR)/meta.tex: FORCE
@mkdir -p $(VAR_DIR)
define meta_cmds
@mkdir -p $(dir $@)
@{ \
c=$$(git rev-parse --short=12 HEAD 2>/dev/null || echo unknown); \
git diff --quiet HEAD -- 2>/dev/null || c="$$c (+ uncommitted changes)"; \
printf '\\newcommand{\\bookcommit}{%s}\n' "$$c"; \
printf '\\newcommand{\\bookdate}{%s}\n' "$$(date -u +%Y-%m-%d)"; \
printf '\\newcommand{\\bookversion}{%s}\n' "$$(git describe --tags --always 2>/dev/null || echo unknown)"; \
printf '\\def\\bookboard{%s}\n' "$(BOARD_NAME)"; \
$(if $(BOARD),printf '\\newcommand{\\bookboardappendix}{board-%s}\n' "$(BOARD)";) \
} > $@.tmp
@cmp -s $@.tmp $@ && rm -f $@.tmp || mv $@.tmp $@
endef
$(VAR_DIR)/meta.tex: FORCE
$(meta_cmds)
$(FABRIC_DIR)/meta.tex: FORCE
$(meta_cmds)
FORCE:
TEXINPUTS_BOOK := $(abspath $(VAR_DIR)):$(abspath $(GEN)):$(abspath $(BOOK_DIR)):
$(PDF): $(BOOK_DIR)/main.tex $(FRAGMENTS) $(GEN)/pandoc-highlighting.tex $(VAR_DIR)/meta.tex | tools
$(PDF): $(BOOK_DIR)/main.tex $(BOOK_DIR)/preamble.tex $(FRAGMENTS) $(GEN)/pandoc-highlighting.tex $(VAR_DIR)/meta.tex | tools
@echo " LATEXMK $(BOOK_DIR)/main.tex -> $@"
@TEXINPUTS=$(TEXINPUTS_BOOK) $(LATEXMK) -xelatex -interaction=nonstopmode -halt-on-error \
-file-line-error -outdir=$(VAR_DIR) $(BOOK_DIR)/main.tex > $(VAR_DIR)/latexmk.log 2>&1 || { \
@@ -112,3 +126,14 @@ $(PDF): $(BOOK_DIR)/main.tex $(FRAGMENTS) $(GEN)/pandoc-highlighting.tex $(VAR_D
echo "Error: LaTeX failed; full log: $(VAR_DIR)/main.log"; exit 1; }
@cp $(VAR_DIR)/main.pdf $@
@echo " PDF $@"
TEXINPUTS_FABRIC := $(abspath $(FABRIC_DIR)):$(abspath $(GEN)):$(abspath $(BOOK_DIR)):
$(FABRIC_PDF): $(BOOK_DIR)/fabric.tex $(BOOK_DIR)/preamble.tex $(FABRIC_FRAGS) $(GEN)/pandoc-highlighting.tex $(FABRIC_DIR)/meta.tex | tools
@echo " LATEXMK $(BOOK_DIR)/fabric.tex -> $@"
@TEXINPUTS=$(TEXINPUTS_FABRIC) $(LATEXMK) -xelatex -interaction=nonstopmode -halt-on-error \
-file-line-error -outdir=$(FABRIC_DIR) $(BOOK_DIR)/fabric.tex > $(FABRIC_DIR)/latexmk.log 2>&1 || { \
grep -A4 -E '^(.*:[0-9]+:|!)' $(FABRIC_DIR)/fabric.log | head -40; \
echo "Error: LaTeX failed; full log: $(FABRIC_DIR)/fabric.log"; exit 1; }
@cp $(FABRIC_DIR)/fabric.pdf $@
@echo " PDF $@"