From ceed38372a66580ec584db10db79cf311c6da9ef Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Wed, 19 Aug 2026 22:00:09 +0200 Subject: docs(templates): document the ordo booklet's required two-pass build A LaTeX table of contents needs two pdflatex passes -- the first pass leaves every entry showing '??', the second resolves the \pageref values. A user hit exactly this and reported it as a bug; the template was fine, the instructions were not. README's rendering example now runs pdflatex twice for ordo.tex (or names latexmk -pdf as the one-shot alternative) and notes the wall calendar needs only one pass, having no cross-references of its own. make check-templates now runs pdflatex twice per LaTeX template too, so the target exercises what a user actually has to do rather than silently passing on a single, incomplete pass. --- Makefile | 6 ++++-- README.md | 10 +++++++++- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index 80a69fa..3f534c3 100644 --- a/Makefile +++ b/Makefile @@ -58,8 +58,10 @@ check-templates: build ## typeset every shipped template (needs pdflatex/groff; if command -v pdflatex >/dev/null 2>&1; then \ for t in ordo grid; do \ opam exec -- dune exec colitur -- table --year 2027 --template templates/ef/$$t.tex > /tmp/$$t.tex && \ - (cd /tmp && pdflatex -halt-on-error -interaction=nonstopmode $$t.tex >/dev/null) && \ - echo "pdflatex: $$t.tex OK" || { echo "pdflatex: $$t.tex FAILED"; ok=0; }; \ + (cd /tmp && pdflatex -halt-on-error -interaction=nonstopmode $$t.tex >/dev/null && \ + pdflatex -halt-on-error -interaction=nonstopmode $$t.tex >/dev/null) && \ + echo "pdflatex: $$t.tex OK (two passes, so a TOC's own \\pageref settles)" || \ + { echo "pdflatex: $$t.tex FAILED"; ok=0; }; \ done; \ else echo "SKIPPED: pdflatex not installed -- LaTeX templates render but are NOT typeset"; fi; \ if command -v groff >/dev/null 2>&1; then \ diff --git a/README.md b/README.md index aafde4e..5914734 100644 --- a/README.md +++ b/README.md @@ -24,8 +24,16 @@ dune exec colitur -- day 2026 # the full resolved EF calendar (temporal + ## Rendering ```sh -dune exec colitur -- table --year 2027 --template templates/ef/ordo.tex > ordo.tex && pdflatex ordo.tex +# The ordo booklet has a table of contents (page numbers via \pageref), so +# it needs TWO pdflatex passes -- the first pass leaves every entry showing +# "??"; the second resolves them. A single pass is not a bug in the +# template, it is just an unfinished build. Either form works: +dune exec colitur -- table --year 2027 --template templates/ef/ordo.tex > ordo.tex && pdflatex ordo.tex && pdflatex ordo.tex +# or: latexmk -pdf ordo.tex + +# The wall calendar has no cross-references, so one pass is enough: dune exec colitur -- table --year 2027 --template templates/ef/grid.tex > grid.tex && pdflatex grid.tex + dune exec colitur -- publish --from 2027 --to 2027 --out ./public ``` -- cgit v1.3