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.

1 files changed, 11 insertions, 4 deletions

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
 # (<prefix>/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