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, 7 insertions, 1 deletions

diff --git a/man/colitur.1 b/man/colitur.1
index 6e380ce..6463415 100644
--- a/man/colitur.1
+++ b/man/colitur.1
@@ -180,7 +180,9 @@ The workflow:
 .fi
 .RE
 .PP
-An overlay is an S\-expression file with an
+The format is documented in full in
+.BR colitur\-overlay (5).
+In brief, an overlay is an S\-expression file with an
 .I id
 and a list of directives:
 .BR Add ", " Suppress ", " Replace " and " Edit .
@@ -361,6 +363,10 @@ The votive Office of the Blessed Virgin Mary on Saturday is kept, but the
 seasonal selection among its five Masses is not yet implemented, so its
 reading citations fall back to the day's ordinary ones.
 .SH SEE ALSO
+.BR colitur\-overlay (5)
+for the overlay file format \(em every directive, every field, the three date
+shapes and worked examples.
+.PP
 .BR lectio (1)
 .SH LICENSE
 AGPL\-3.0\-or\-later.