path: root/man/colitur-overlay.5

.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 .
Every celebration in it is invented, with
.B example\-
slugs, so that nothing in it can be mistaken for calendar data.
.PP
Two REAL local calendars ship beside it, in the flat INI form:
.TP
.I examples/poland.ini
The proper calendar of the dioceses of Poland, from the
.I Calendarium Perpetuum pro Dioecesium Poloniae
(1964). Seventeen entries. Its header records which classes were read from
the source and which are colitur's inference, and warns about the 1921 and
1934
.I Proprium Poloniae
still bound into many missals \(em an outdated arrangement of dioceses and
ranks that is easy to mistake for this calendar.
.TP
.I examples/benedictine.ini
Two entries, and deliberately so. The monastic rite grades feasts
.B Duplex
and
.B Semiduplex
below II class, where the Roman calendar has III and IV class, so most
Benedictine propers cannot be expressed in this format at all. Rather than
invent a mapping the source does not state, that file ships only what its
ordo gives in Roman terms and lists the rest by name as excluded. It is worth
reading for that reason more than for its two feasts.
.PP
.B Both are examples, not authorities.
They are transcriptions from published ordines, and none of this program's
test layers can vouch for either \(em check them against your own ordo.
.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)
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 THE FLAT INI FORM
For a calendar that only adds a few local feasts, drops one or two universal
entries, and recolours nothing complicated, there is a flatter form converted
by
.BR "colitur convert" .
Section names are slugs; a
.RB [ overlay ]
section carries the id.
.RS
.nf

[overlay]
id = my\-parish

[our\-patron]
date    = 07\-11
rank    = class\-3
colour  = white
name.en = St Example, Patron

[our\-dedication]
date    = oct/sun/1
rank    = class\-1
colour  = white
name.en = Dedication of Our Church

[stanislaus]
edit   = yes
colour = red

[barbara]
suppress = yes
.fi
.RE
.PP
.I status
defaults to
.BR feast ,
.I subject
to
.BR saint ,
and
.I layer
to the file's id, so the common case \(em an ordinary local saint's feast \(em
says only what distinguishes it. Dates take the three forms
.IR MM\-DD ,
.IB easter + N
or
.IB easter - N
, and
.IB mon / day / nth
such as
.B oct/sun/1
or
.B oct/sun/\-1
for the last.
.PP
.B This form is deliberately less expressive.
It covers
.BR Add ", " Suppress
and single\-field
.BR Edit .
.B Replace
, multi\-field edits, citation edits and
.B Remove_name
are not expressible, and the converter refuses them
.I by name
rather than dropping them silently. Anything it cannot say is a reason to
write the S\-expression form, not a reason to grow this one.
.PP
.B The conversion verifies its own output.
The generated text is parsed back with the same function that loads an
overlay, and must equal what the INI denoted; nothing is written if it does
not. This matters because a transpiler emitting
.I valid but wrong
S\-expressions is the failure a convenience format invites, and
.B colitur check
could never catch it \(em the output would parse cleanly and simply mean
something else.
.RS
.nf

.B colitur convert my\-parish.ini > my\-parish.sexp
.B colitur check my\-parish.sexp
.fi
.RE
.PP
The conversion is a separate step rather than something
.B \-\-overlay
does invisibly, so you can read what your INI became. When a date form was
mistyped, "what did the engine actually get" is the question, and an invisible
transpile cannot answer it.
.SH SEE ALSO
.BR colitur (1)
.SH LICENSE
AGPL\-3.0\-or\-later.