colitur.git/man/colitur-templates.5, branch v0.9.0

fix(render): a month answers to both spellings of its own name

2026-08-20T20:33:07Z

A week object carries month_name/month_num/month_abbr, because at that level a bare `name` would be ambiguous. An author who learned those names inside {{#weeks}} reaches for them one level up inside {{#months}} too -- where they resolved to nothing, and an unknown key renders as the empty string by design, so the result was a silently blank month heading rather than any error. Found by writing a template from scratch rather than copying a shipped one; every shipped template sidesteps it, which is why nothing caught it. The aliases are additive, so no existing template or golden changes. colitur-templates(5) now documents both spellings and says why they exist.

fix(cli): close the flavour-list call sites Typst's addition exposed

2026-08-20T08:11:48Z

The task this branch of work set out to test was whether the template engine is genuinely flavour-agnostic outside lib/render/escape.ml. It is not, quite: bin/main.ml's own --flavour error/help text and both man pages hand-typed the flavour list and its count ("the six flavours") as literal prose, so adding Typst as a seventh left three places silently wrong (an incomplete flavour list in two error messages, and "six" where the true count is now seven) until this commit. bin/main.ml's two error messages (unknown --flavour value, and cannot infer a flavour from an extension) now build their flavour list by walking Escape.all/to_string instead of a literal string, so the next flavour added will not reintroduce the same drift; the static --help body text and colitur(1)/colitur-templates(5) still name flavours and their count by hand; there was no equivalent gain available for prose formatted this specifically, so those were updated by hand instead, along with colitur-templates(5)'s FLAVOURS section, which gained typst's own subsection alongside latex/groff/html/xml/ics/none. test/cli.t's two pinned error-text assertions are updated to match, and gained a new case: .typ inferred from extension, and a real shipped citation's hyphen surviving --flavour typst's own escaping live, the same shape the 2035 Ss. Petri et Pauli case already proves for latex's ampersand just above it.

docs(naming): the config man page, and the field reference

2026-08-20T07:28:20Z

colitur-config.5 documents the file's location, the flag > config > default precedence, every setting, and that an unknown key is warned about rather than fatal. Its worked example is a real run against the shipped example overlay, pasted rather than hand-typed -- including one genuine gotcha found while verifying it: overlay/template values are not shell-expanded, so a bare "~/..." written into the config file fails to load; the full path must be written out instead. colitur-templates.5's field reference is updated for the view change -- every field checked against lib/render/view.ml and schema/day-v1.json, not transcribed from memory or an earlier version of this page -- and its worked example is pasted from a real `colitur table` run. Its scope-shadowing warning about {{name.la}} is REMOVED and replaced with a short note that the hazard is now unrepresentable, because name is a plain resolved string with no dotted path left to fall back through. The num collision between a month and a week (both carry num, and a bare {{num}} read from inside a day silently climbs to the week's own value, not the month's) still exists and is demonstrated with a real render, not merely asserted. A man page describing a hazard that was fixed is as wrong as one that omits a real hazard. Two further stale mentions of the removed {{name.la}} hazard, and two places describing the schema as "Latin and English names" rather than one resolved display name, were found in colitur.1 while cross-checking and fixed alongside the primary rewrite; its own CSV example in EMIT was also still the pre-Task-5 column list (name_la/name_en, no *_name columns) and is now the real, verified header. lang/ already installs beside templates/ and schema/ (a prior hotfix); colitur-config.5 is added to install/uninstall/man/doc in the Makefile so `make install`/`make doc` cover it too.

docs(templates): the scope-fallback hazard headline was backwards

2026-08-19T09:35:27Z

It read "an inner key silently loses to an outer key of the SAME NAME" -- false: the document's own num entry, two paragraphs below, shows the opposite (inside {{#weeks}}, a bare {{num}} is the week's own number, correctly, because the inner scope wins). The real hazard, matching the body text and the name example that were already correct: a DOTTED path that resolves only part way inward (the day's own name object exists but lacks the key the path needs) falls back WHOLESALE to an outer scope of the same name, not a bare key losing outright. Corrected the headline only; re-linted clean with groff -man -Tutf8 -ww -z.

docs(templates): fix a false claim in the worked example (F1)

2026-08-19T08:48:06Z

The worked minimal template iterated the top-level, flat days list and claimed the naive {{name.la}} form would print the enclosing month's name there. It would not: with no {{#months}} wrapping it, the flat days list has no month anywhere on the scope stack, so the naive form on an unnamed day resolves to nothing, not to the month. Reproduced against the live engine before touching the page: the flat shape renders empty; the identical naive form nested inside {{#months}} genuinely does print the month's name on both unnamed days. The example now nests days inside months -- the shape every shipped template actually uses, and the shape the hazard needs to fire -- with a second, verified rendering showing the collision for real, and a closing note stating plainly that the flat shape does not reproduce it. SCOPE AND LOOKUP's own name-collision paragraph gained the same nesting precondition it was missing. Both rendered blocks were checked mechanically: extracted verbatim from the page source and diffed against a fresh colitur table run over the exact templates shown, byte for byte. One cosmetic fix along the way: a transition sentence embedded the full safe-idiom string inline via .B, which groff's justifier stretched into visibly wide gaps when rendered. Reworded to reference the idiom shown above instead of repeating it.

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

2026-08-19T08:32:44Z

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 /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.