From 99dbddb2106f8a3ca31c7e0c43b7dc1a81652786 Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Thu, 20 Aug 2026 09:28:20 +0200 Subject: docs(naming): the config man page, and the field reference 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. --- Makefile | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'Makefile') diff --git a/Makefile b/Makefile index c96113f..6ba81ba 100644 --- a/Makefile +++ b/Makefile @@ -120,13 +120,14 @@ install: build ## install binary, calendar data, language tables, templates, sch @mkdir -p $(MAN5DIR) install -m 644 man/colitur-overlay.5 $(MAN5DIR)/colitur-overlay.5 install -m 644 man/colitur-templates.5 $(MAN5DIR)/colitur-templates.5 + install -m 644 man/colitur-config.5 $(MAN5DIR)/colitur-config.5 @echo "installed $(BINDIR)/$(COLITUR), data in $(PREFIX)/share/colitur/{ef,lang,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 $(MAN5DIR)/colitur-templates.5 + rm -f $(MANDIR)/colitur.1 $(MAN5DIR)/colitur-overlay.5 $(MAN5DIR)/colitur-templates.5 $(MAN5DIR)/colitur-config.5 @echo "removed $(COLITUR) from $(PREFIX)" reinstall: uninstall install ## uninstall then install (the installed copy is a snapshot, not a link) @@ -135,11 +136,13 @@ man: ## preview the man pages man -l man/colitur.1 man -l man/colitur-overlay.5 man -l man/colitur-templates.5 + man -l man/colitur-config.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 + groff -man -Tutf8 -ww -z man/colitur-config.5 fmt: ## format the OCaml sources $(DUNE) dune build @fmt --auto-promote -- cgit v1.3