docs(render): template reference, install rules, typesetting check

colitur-templates.5 documents the four syntax forms, the six flavours
and their escaping, and the full view-model field reference. It states
plainly that there are no partials, no raw form and no expression
evaluation -- a template is data, never a program. It documents two
real hazards found during this build, not theoretical ones: the
outward scope fallback silently shadowing an inner name/num key with
an outer one of the same name (with the safe {{#name}}...{{^la}}
idiom), and the engine's lack of host-comment awareness (a {{...}}
inside a LaTeX %, groff .\" or HTML <!-- --> comment is still parsed
as a tag).

It also states the limitation rather than hiding it: AsciiDoc and
Markdown are not escaped, so a feast name containing * or _ renders as
emphasis.

templates/ and schema/ now install into <prefix>/share/colitur/,
matching data/ef/, via new install stanzas; colitur-templates.5
installs to man5 beside colitur-overlay.5. Verified against a scratch
prefix: the installed binary resolves both from the prefix, not the
source tree, when run from an unrelated working directory.

make check-templates typesets every shipped template through pdflatex
and groff when they are installed, and prints SKIPPED loudly when they
are not. Golden tests prove templates render; only this proves they
typeset. A silent skip would read as a pass.

Fixed a real doc/help drift while here: bin/main.ml's --help still said
--overlay was accepted on day and readings only, three commands out of
date (emit, table/render and publish all accept it too), disagreeing
with the man page's own OVERLAYS section, which carried the identical
stale line. Both are corrected; --overlay's own behaviour is unchanged.

1 files changed, 39 insertions, 4 deletions

diff --git a/Makefile b/Makefile
index 0d4d1d5..aa4bce6 100644
--- a/Makefile
+++ b/Makefile
@@ -10,6 +10,11 @@ MAN5DIR  := $(PREFIX)/share/man/man5
 # (<prefix>/share/colitur/ef), so `dune install` -- not a hand-rolled copy --
 # is what places the four .sexp files where a running colitur will look for
 # them. See bin/main.ml's own [data_dir] for the full resolution order.
+# Task 13 (schema/dune, templates/dune) extends the same `dune install`
+# mechanism to <prefix>/share/colitur/schema/ (bin/main.ml's own
+# [schema_path], read by `colitur publish`) and <prefix>/share/colitur/
+# templates/ (a convenience install -- `--template` takes a plain file path,
+# nothing in colitur probes this location the way [data_dir]/[schema_path] do).
 #
 # dune needs the project-local opam switch on PATH. Every recipe that invokes
 # dune goes through this, so `make` works from a plain shell with no
@@ -17,7 +22,7 @@ MAN5DIR  := $(PREFIX)/share/man/man5
 # over documenting the dune commands.
 DUNE := opam exec --
 
-.PHONY: help build test check check-schema install uninstall reinstall clean fmt man doc release
+.PHONY: help build test check check-schema check-templates install uninstall reinstall clean fmt man doc release
 help: ## show this help
 	@grep -hE '^[a-z-]+:.*##' $(MAKEFILE_LIST) | sed -E 's/:.*## /\t/' | sort
 
@@ -39,19 +44,47 @@ check-schema: build ## validate emitted XML against schema/colitur-v1.xsd (needs
 	  echo "SKIPPED: xmllint not installed -- XML is emitted but NOT schema-validated"; \
 	fi
 
-install: build ## install binary, calendar data and man page into PREFIX (default ~/.local)
+# Typesets every shipped template through the real tool that would typeset it
+# for a reader, not merely through this program's own renderer. The golden
+# tests already prove `colitur table` PRODUCES the expected LaTeX/groff/HTML
+# text; only this proves that text actually TYPESETS -- a template can render
+# byte-for-byte as pinned and still be malformed LaTeX or groff. Each tool is
+# genuinely optional (neither is in colitur's own frozen deps), so absence is
+# printed LOUDLY as SKIPPED rather than silently treated as a pass -- a
+# silent skip reads as a pass, which is the whole failure mode this guards
+# against.
+check-templates: build ## typeset every shipped template (needs pdflatex/groff; skipped if absent)
+	@ok=1; \
+	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; }; \
+	  done; \
+	else echo "SKIPPED: pdflatex not installed -- LaTeX templates render but are NOT typeset"; fi; \
+	if command -v groff >/dev/null 2>&1; then \
+	  for t in ordo grid; do \
+	    opam exec -- dune exec colitur -- table --year 2027 --template templates/ef/$$t.ms > /tmp/$$t.ms && \
+	    groff -ms -t -Tpdf /tmp/$$t.ms > /tmp/$$t-ms.pdf && \
+	    echo "groff: $$t.ms OK" || { echo "groff: $$t.ms FAILED"; ok=0; }; \
+	  done; \
+	else echo "SKIPPED: groff not installed -- groff templates render but are NOT typeset"; fi; \
+	test $$ok -eq 1
+
+install: build ## install binary, calendar data, templates, schema and man pages into PREFIX (default ~/.local)
 	$(DUNE) dune install --prefix $(PREFIX)
 	@mkdir -p $(MANDIR)
 	install -m 644 man/colitur.1 $(MANDIR)/colitur.1
 	@mkdir -p $(MAN5DIR)
 	install -m 644 man/colitur-overlay.5 $(MAN5DIR)/colitur-overlay.5
-	@echo "installed $(BINDIR)/$(COLITUR), data in $(PREFIX)/share/colitur/ef, man pages in $(MANDIR) and $(MAN5DIR)"
+	install -m 644 man/colitur-templates.5 $(MAN5DIR)/colitur-templates.5
+	@echo "installed $(BINDIR)/$(COLITUR), data in $(PREFIX)/share/colitur/{ef,templates,schema}, man pages in $(MANDIR) and $(MAN5DIR)"
 	@command -v $(COLITUR) >/dev/null 2>&1 || \
 	  echo "note: $(BINDIR) is not on PATH -- add it, or run $(BINDIR)/$(COLITUR) directly"
 
 uninstall: ## remove everything install put into PREFIX
 	-$(DUNE) dune uninstall --prefix $(PREFIX)
-	rm -f $(MANDIR)/colitur.1 $(MAN5DIR)/colitur-overlay.5
+	rm -f $(MANDIR)/colitur.1 $(MAN5DIR)/colitur-overlay.5 $(MAN5DIR)/colitur-templates.5
 	@echo "removed $(COLITUR) from $(PREFIX)"
 
 reinstall: uninstall install ## uninstall then install (the installed copy is a snapshot, not a link)
@@ -59,10 +92,12 @@ reinstall: uninstall install ## uninstall then install (the installed copy is a
 man: ## preview the man pages
 	man -l man/colitur.1
 	man -l man/colitur-overlay.5
+	man -l man/colitur-templates.5
 
 doc: ## lint the man pages (groff warnings; silence means clean)
 	groff -man -Tutf8 -ww -z man/colitur.1
 	groff -man -Tutf8 -ww -z man/colitur-overlay.5
+	groff -man -Tutf8 -ww -z man/colitur-templates.5
 
 fmt: ## format the OCaml sources
 	$(DUNE) dune build @fmt --auto-promote