diff options
| -rw-r--r-- | man/colitur-overlay.5 | 65 |
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) |