.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 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.