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. --- man/colitur-overlay.5 | 257 ++++++++++++++++++++++++++++++++++++++++++++++++++ man/colitur.1 | 8 +- 2 files changed, 264 insertions(+), 1 deletion(-) create mode 100644 man/colitur-overlay.5 (limited to 'man') diff --git a/man/colitur-overlay.5 b/man/colitur-overlay.5 new file mode 100644 index 0000000..00a84a7 --- /dev/null +++ b/man/colitur-overlay.5 @@ -0,0 +1,257 @@ +.TH COLITUR\-OVERLAY 5 "2026" "colitur" "File Formats" +.SH NAME +colitur\-overlay \- local calendar file for colitur(1) +.SH SYNOPSIS +.I my\-parish.sexp +.SH DESCRIPTION +An +.B overlay +is a file describing a local calendar \(em a diocese's propers, a religious +house's own feasts, a parish patronal day \(em applied +.I on top of +the universal 1962 calendar that +.BR colitur (1) +ships, never instead of it. +.PP +Overlays are S\-expressions. The format is the engine's own data type written +out, which is why it is parenthesised rather than prose: there is no separate +parser to disagree with the program. +.SH GETTING STARTED +Do not write one from scratch. Start from the generated template, which is +commented and known to load: +.RS +.nf + +.B colitur new\-overlay > my\-parish.sexp +.B $EDITOR my\-parish.sexp +.B colitur check my\-parish.sexp +.B colitur day 2026 \-\-overlay my\-parish.sexp +.fi +.RE +.PP +.BR "colitur check" , +described in +.BR colitur (1), +reports what each directive targets and exits +.B 2 +if the file will not load or a directive matched nothing. Run it after every +edit; it is much faster than reading a year of output. +.SH STRUCTURE +A file has an +.I id +and a list of +.IR directives : +.RS +.nf + +((id my\-parish) + (directives + (\fIdirective\fR \fIdirective\fR ...))) +.fi +.RE +.PP +The +.I id +names the layer. It appears in diagnostics, and it is the default +.I layer +value for every celebration the file adds. +.SH DIRECTIVES +.TP +.BI Add " entry" +Add a celebration that is not in the universal calendar. +.TP +.BI Suppress " slug" +Remove a universal entry your calendar does not keep. +.TP +.BI Replace " slug entry" +Replace a universal entry wholesale. +.TP +.BI Edit " slug (edits ...)" +Keep a universal entry but change individual fields. The edits are +.BI Set_rank " rank" +, +.BI Set_colour " colour" +, +.BI Set_subject " subject" +, +.BI Set_name " lang string" +, +.BI Remove_name " lang" +, +.BI Set_citation " part string" +and +.BI Remove_citation " part" +. +.IP +There is deliberately no +.B Set_status +and no +.BR Set_date : +changing whether an entry is a feast or a commemoration, or moving it to +another day, makes it a different celebration rather than an edited one. Use +.B Replace +for that, so the change is visible as a replacement in +.BR "colitur check" 's +output rather than hidden inside an edit list. +.PP +Directives are applied in the order written, and files in the order given on +the command line. Last writer wins, so a later directive may deliberately +override an earlier one, or a universal entry, by naming the same slug. +.PP +A directive naming a slug that does not exist is +.I not +fatal: it warns on standard error and the run continues, so an overlay written +against a slightly different base stays usable. +.BR "colitur check" +turns the same condition into a non\-zero exit, which is where you want it. +.SH ENTRY +An entry is a date and a celebration: +.RS +.nf + +((date \fIdate\-spec\fR) + (cel + ((slug my\-local\-patron) + (names ((la "Sancti Patroni Nostri") (en "Our Local Patron"))) + (rank Class3) (status Feast) (colour White) (subject Saint)))) +.fi +.RE +.SS Required fields +.TP +.I slug +Lowercase ASCII, digits and hyphens. Must be unique. +.TP +.I names +Language\-keyed. Any language tag is accepted; +.B la +and +.B en +are conventional. +.TP +.I rank +.BR Class1 ", " Class2 ", " Class3 " or " Class4 . +.TP +.I status +.B Feast +or +.BR Commemoration_only . +A +.B Commemoration_only +entry never becomes the day's office; it can only ever be commemorated. +.TP +.I colour +.BR White ", " Red ", " Violet ", " Green ", " Black " or " Rose . +.TP +.I subject +.BR Lord ", " Bvm ", " Saint " or " Temporal . +This is not decoration: it drives real rules. A feast of the Lord takes an +occurring II\-class Sunday's place outright (RG 16(a)), and two feasts of the +same Divine Person exclude one another's commemoration (RG 112(a)). +.SS Optional fields +.TP +.I citations +Defaults to empty, which is almost always right: reading citations come from +the rite's lectionary, not from calendar data. +.TP +.I layer +Defaults to the file's own +.IR id . +Set it only if one file ships more than one logical layer. +.SH DATE SPECIFICATIONS +.TP +.BI "(Fixed (month " M ") (day " D "))" +A civil date, recurring every year. 29 February is accepted and simply does +not occur in a common year. +.TP +.BI "(Easter_offset " N ")" +Signed days from Easter. +.B 0 +is Easter itself, +.B \-46 +Ash Wednesday, +.B 60 +Corpus Christi. Use this for anything reckoned from the movable cycle. +.TP +.BI "(Nth_weekday (month " M ") (nth " N ") (weekday " W "))" +The +.IR N th +.I W +of month +.IR M . +.I N +may be negative to count from the end, so +.B \-1 +is the last. +.I W +is +.BR Sun ", " Mon ", " Tue ", " Wed ", " Thu ", " Fri " or " Sat . +A month lacking a fifth occurrence simply has no such day that year. +.SH EXAMPLES +A fixed\-date local patron: +.RS +.nf + +(Add + ((date (Fixed (month 7) (day 11))) + (cel + ((slug our\-patron) + (names ((en "St Example, Patron"))) + (rank Class3) (status Feast) (colour White) (subject Saint))))) +.fi +.RE +.PP +A dedication anniversary on the first Sunday of October. I class is correct +and not for effect: a church's own dedication is I class +.I in that church +(RG 91 entry 4). At III class it would lose to the Sunday every year and never +appear: +.RS +.nf + +(Add + ((date (Nth_weekday (month 10) (nth 1) (weekday Sun))) + (cel + ((slug our\-dedication) + (names ((en "Dedication of Our Church"))) + (rank Class1) (status Feast) (colour White) (subject Saint))))) +.fi +.RE +.PP +Recolour a universal entry without otherwise touching it: +.RS +.nf + +(Edit stanislaus ((Set_colour Red))) +.fi +.RE +.PP +A worked file exercising all four directives and all three date shapes is +installed at +.IR /share/colitur/examples/diocesan\-example.sexp . +.SH CAVEATS +.B An overlay is applied, not validated. +.BR colitur (1) +is tested in five layers \(em types, properties over every year in its domain, +a differential against a sibling engine, published\-calendar oracles, and +hand\-verified pins \(em and every one of them asserts something about the +.I shipped +calendar. None can vouch for a file you supply. +.PP +.B colitur check +is not an exception to that. It answers three narrow questions: does the file +parse, does every directive find its target, and what does the merged result +contain. It cannot tell you that a feast belongs on the day you gave it, that +its rank is the one your ordinary assigned, or that your calendar is +internally coherent as a liturgical document. Those remain yours to get right. +.PP +The engine will, however, apply the general rubrics to whatever you add: an +overlay feast competes for its day under the same precedence rules as a +universal one, and may be impeded, transferred or reduced to a commemoration +accordingly. A local feast that never appears in output has usually lost that +contest rather than failed to load \(em +.B colitur check +will confirm it loaded. +.SH SEE ALSO +.BR colitur (1) +.SH LICENSE +AGPL\-3.0\-or\-later. 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. -- cgit v1.3