From 150f8c550d2f9ebbac61d195eb342eb2b2ec6b95 Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Tue, 18 Aug 2026 13:33:41 +0200 Subject: docs(man): colitur-overlay(5), the overlay format in full The overlay format was documented in three partial places -- a paragraph in colitur(1), a block in --help, and the comments inside the shipped example -- none of which was a reference. Someone writing a diocesan calendar had to read all three and infer the rest. Section 5 because an overlay is a thing a user AUTHORS rather than a command they run: it belongs beside fstab(5), not in man1. Covers every directive and every field edit, the six required fields and the two optional ones, all three date specifications including the signed Easter_offset and the negative nth, three worked examples, and the caveats. The subject field gets a note explaining that it is not decoration -- it decides whether a feast displaces an occurring Sunday under RG 16(a). Two things it says that the code says and the old prose did not. There is no Set_status and no Set_date among the field edits, deliberately: changing an entry's status or its date makes it a different celebration rather than an edited one, so Replace is the right directive and the change stays visible in `colitur check` output. And a local feast missing from output has usually LOST its day under the general rubrics rather than failed to load -- the engine applies precedence to overlay entries exactly as to universal ones, which is the first thing an author hits and was written down nowhere. Writing it caught a documentation bug before it shipped: a first draft listed a Set_status edit that does not exist and omitted Remove_name that does. Every documented edit is now cross-checked against overlay.mli. Linked from colitur(1)'s SEE ALSO and its OVERLAYS section, and from --help. The Makefile installs it into man5, removes it on uninstall, and the man and doc targets lint both pages. --- bin/main.ml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'bin') diff --git a/bin/main.ml b/bin/main.ml index e748629..b997cbe 100644 --- a/bin/main.ml +++ b/bin/main.ml @@ -450,7 +450,8 @@ exit status: 2 bad usage, year out of range, or the calendar data could not be read Reading references only (e.g. "Jn 3:16"); never scripture text. -See colitur(1) for the full description and the sources it computes against.|} +See colitur(1) for the full description and the sources it computes against, +and colitur-overlay(5) for the overlay file format in full.|} let print_help () = print_endline help_text; -- cgit v1.3