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. --- Makefile | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) (limited to 'Makefile') diff --git a/Makefile b/Makefile index 1d14437..5b3bb55 100644 --- a/Makefile +++ b/Makefile @@ -2,6 +2,9 @@ COLITUR := colitur PREFIX ?= $(HOME)/.local BINDIR := $(PREFIX)/bin MANDIR := $(PREFIX)/share/man/man1 +# Section 5 is file formats: the overlay format is a thing a user AUTHORS, +# not a command they run, so it belongs beside fstab(5) rather than in man1. +MAN5DIR := $(PREFIX)/share/man/man5 # The binary locates its calendar data relative to its own path # (/share/colitur/ef), so `dune install` -- not a hand-rolled copy -- @@ -31,22 +34,26 @@ install: build ## install binary, calendar data and man page into PREFIX (defaul $(DUNE) dune install --prefix $(PREFIX) @mkdir -p $(MANDIR) install -m 644 man/colitur.1 $(MANDIR)/colitur.1 - @echo "installed $(BINDIR)/$(COLITUR), data in $(PREFIX)/share/colitur/ef, man page in $(MANDIR)" + @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)" @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 + rm -f $(MANDIR)/colitur.1 $(MAN5DIR)/colitur-overlay.5 @echo "removed $(COLITUR) from $(PREFIX)" reinstall: uninstall install ## uninstall then install (the installed copy is a snapshot, not a link) -man: ## preview the man page +man: ## preview the man pages man -l man/colitur.1 + man -l man/colitur-overlay.5 -doc: ## lint the man page (groff warnings; silence means clean) +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 fmt: ## format the OCaml sources $(DUNE) dune build @fmt --auto-promote -- cgit v1.3