1 files changed, 257 insertions, 0 deletions
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 <prefix>/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.