colitur.git/man, branch v0.10.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(citation): close the final review's blocking findings

2026-08-20T17:03:02Z

The branch was RED and reported green. `dune test` exited 1: test/cli.t pinned the pre-fix output `kings_1 19:3-8`, which the previous commit had already fixed to `1 Reg 19:3-8`. The gate command piped dune through `tail`, so it reported tail's exit status, and cram prints its diff BEFORE the alcotest summary, so the two lines shown were the passing ones. Verify with `dune test; echo $?`, never through a pipe. A style file's own `book` key was unreachable. sigla_book resolved against a hardcoded "abbr" and the result was applied unconditionally, so the documented `[sigla] book = full` could never win. Render gains book_string, and the style's own value is now the default that a flag or config overrides. The unit test pinned style_of_fields correctly while the wiring defeated it. `lang --check` filtered the reference set to the celebration prefix, so a file with no [bible] section at all reported a clean bill of health -- contradicting both the reason the keys change was made and lang.ml's own comment. It now reports missing book names too. The token test missed a FOURTH citation-bearing file: adjustments.sexp writes citations as `Set_citation`, not `(reference ...)`. Its 16 citations all parse, so nothing was broken, but nothing was checking. The first attempt at this fix read the file and extracted NOTHING -- the marker stopped before the opening quote, so every payload was the part label -- which is recorded in the code rather than left as a trap. Also: colitur-config(5) claimed a trailing period the data does not carry, and two la.ini scan quotes silently corrected OCR damage ("Ionae 3, I - I O", "Epistolse") while presenting themselves as verbatim. Both are now marked as corrections.

fix(lang): stop internal book ids reaching output, and finish the docs

2026-08-20T15:33:26Z

Three defects, all found by running the documented examples rather than by reading code. All seven modern-numbering targets carried their own internal id as their Latin name (kings_1.full = kings_1), so --sigla-tradition modern printed "kings_1 19:3-8" -- leaking a key book.mli states is never shown to a reader. They now carry Vulgate-derived Latin names marked CONSTRUCTED: the 1962 Missal uses Vulgate numbering throughout, so it can contain no incipit for a book that exists only under a later convention. In Latin the modern tradition therefore only moves Kings and Esdras; Osee, Ionas, Ecclesiasticus and the Apocalypse keep their names either way, since modern numbering is a vernacular convention. The coverage test could not catch this. It compares a name against its KEY ("kings_1.full"), and "kings_1" differs from that, so the row passed. A second check now asserts no name IS its own id. The two are complementary: one catches a missing row, the other a row present but filled with the wrong thing. Mutation-proved. --help still claimed sigla settings were resolved "but not yet rendered", stale since the render wiring landed. colitur-config.5 documented none of the three settings even though config --show prints them.

docs(citation): sigla flags, book naming and traditions

2026-08-20T15:29:44Z

Includes that --raw emits citations verbatim, which is the behaviour someone diffing against lectio depends on.

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.

feat(cli): --lang and --raw, colitur lang, colitur config

2026-08-20T07:28:08Z

Names are Latin by default now; --raw restores the old byte-exact output, verified against a pre-branch binary built from a clean HEAD checkout, not merely asserted. day and readings gain a trailing display-name field (day's own name suffix, readings' own " | name" suffix) rather than a substitution in the slug's existing position: a name contains spaces and would otherwise break the space-separated columns, the same reasoning that already keeps readings a separate command. The field is present only when it differs from the slug already shown, which is a direct consequence of Lang.raw being the identity table (no lookup ever misses), not a special case threaded through day_line/readings_line -- under --raw, or any language with no entry for a given day, the trailing field is simply absent, byte for byte what this project printed before naming existed. An unknown language is an error naming what is available, never a silent fallback to Latin: a booklet quietly printed in the wrong language is worse than one that refuses to print. A declared fallback still chains, so a partial translation shows its fallback language rather than slugs. lang_dir mirrors data_dir's probe order exactly -- installed prefix, then build tree -- because an installed binary that finds calendar data but no language files is the failure this would otherwise ship. Config (lang/overlay/template/format) is loaded once, unconditionally, before dispatch: a config file that exists but fails to parse is fatal on every command, not only the ones that consult it, because a config the user wrote and colitur cannot honour is not something to silently carry on past. An unknown key or unknown section is reported and ignored, worded differently so a misspelled section reads differently from a misspelled key inside a recognised one. overlay's config default applies only when zero --overlay flags were given, never merged with a partial CLI list, so precedence stays flag > config > default in one direction throughout. colitur lang --list/--dump/--check and colitur config --show are what make "anyone can write a language file" true rather than merely permitted, the same pattern the overlay system already established with new-overlay and check. --check reports what is missing AND rejects an unknown slug (exit 1), because a key matching nothing is silently dead and its author would otherwise never learn why their own name does not appear. --dump emits sections in a fixed order (Lang.keys' own global sort keeps every section's keys contiguous), so two dumps of the same table are byte-identical. config --show resolves through the same Config.resolve every other command uses -- deliberately no separate provenance function, so the two cannot disagree -- and previews exactly what flags given on the same command line would resolve to anywhere else. One authorized change outside this task's own file list: emit_ics.ml's SUMMARY line was reading the unlocalised rank/colour pair ("class-1, white") beside an already-localised name, where the JSON schema right next to it correctly carries rank_name/colour_name ("II classis"/"albus"). Found while reviewing the published site; fixed at the source.

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.