1 files changed, 65 insertions, 0 deletions
diff --git a/man/colitur-overlay.5 b/man/colitur-overlay.5
index a2d2dae..f1360e2 100644
--- a/man/colitur-overlay.5
+++ b/man/colitur-overlay.5
@@ -228,6 +228,71 @@ Recolour a universal entry without otherwise touching it:
 A worked file exercising all four directives and all three date shapes is
 installed at
 .IR <prefix>/share/colitur/examples/diocesan\-example.sexp .
+.SH HOW AN OVERLAY IS APPLIED
+Worth understanding, because the commonest surprise \(em "my feast does not
+appear" \(em is almost never a loading failure.
+.PP
+Four stages, in order:
+.TP
+.B 1. Load
+Each file is parsed into a list of directives. A syntax error here is fatal
+and names the section and the value.
+.TP
+.B 2. Merge
+The shipped universal calendar is taken as the base, then
+.I data/ef/adjustments.sexp
+(colitur's own corrections \(em the inseparable Peter/Paul commemoration, the
+Major Litanies, St Barbara, Rogation Wednesday), then each
+.B \-\-overlay
+in command\-line order. Within a file, directives apply in the order written.
+Last writer wins per slug.
+.IP
+A directive whose slug is not present is
+.I not
+fatal: it warns and the run continues, so an overlay written against a
+slightly different base stays usable.
+.B colitur check
+turns the same condition into exit 2.
+.TP
+.B 3. Resolve
+For each day, the temporal cycle and the merged sanctoral calendar are
+reconciled by the rite's own rules \(em occurrence, precedence, commemoration
+and transfer.
+.B Your entries take part in this on equal terms.
+An overlay feast is not privileged for being local: it competes for its day
+under RG 91's table exactly as a universal feast does.
+.TP
+.B 4. Emit
+One line per day.
+.SS Why a feast may not appear
+Because it lost stage 3, not because it failed stage 1. Some common causes:
+.IP \(bu 2
+It is outranked. A III\-class local feast loses to any I\- or II\-class day it
+lands on, including every Sunday of Advent, Lent and Paschaltide, and to a
+universal feast of higher class on the same date.
+.IP \(bu 2
+Its date is structurally occupied. An
+.B easter+60
+feast will never appear, because Corpus Christi is Easter+60 and is I class.
+The same is true of any offset already carrying a I\-class day.
+.IP \(bu 2
+It is a
+.B commemoration
+and the day already admits its limit \(em RG 111 allows one on a II\-class
+day and two on a III\- or IV\-class one.
+.PP
+.B colitur check
+confirms the file loaded and every directive found its target. If it says so
+and the feast is still absent, stage 3 is the answer: raise its class, or
+choose a date that is not already spoken for.
+.SS Why the shipped adjustments are applied first
+An overlay is applied
+.I on top of
+colitur's own corrections, never instead of them. Replacing them would
+silently drop four things the universal calendar needs, so the order is not
+configurable. A local calendar can still override any of them deliberately by
+naming the slug \(em last writer wins \(em which is a different thing from
+losing them by accident.
 .SH CAVEATS
 .B An overlay is applied, not validated.
 .BR colitur (1)