path: root/man/colitur.1

.TH COLITUR 1 "2026" "colitur" "User Commands"
.SH NAME
colitur \- deterministic liturgical calendar and lectionary engine (Roman rite, 1962)
.SH SYNOPSIS
.B colitur
.BR easter | temporal | day | readings
.I YEAR
.br
.B colitur
.BR day | readings
.I YEAR
.BI \-\-overlay " FILE"
.RI [ ... ]
.br
.B colitur
.BR \-h | \-\-help
.SH DESCRIPTION
.B colitur
computes the liturgical calendar of the 1962 Roman Missal \(em the
Extraordinary Form \(em and the Mass reading citations for every day, entirely
offline and without a network. Its name is
.I computus liturgicus
crossed with the Latin
.IR colitur ,
"He is worshipped".
.PP
For each day it resolves the season, the week, the observed celebration with
its rank and colour, any commemorations, any transfers, and the day's Epistle
and Gospel. It emits reading
.I references
only \(em
.RB \(lq "Jn 3:16" \(rq
\(em and never scripture text.
.PP
The engine is total and deterministic over the whole domain
.BR "1583..9999" .
It reads no clock, draws no randomness, and given the same data produces the
same answer for any year in range. Years outside the domain are refused at the
boundary rather than approximated.
.PP
Each report covers 1 January to 31 December of the civil
.IR YEAR .
That is deliberately not a liturgical year, which is Advent\-anchored and
straddles two civil years;
.B colitur
resolves both liturgical years that touch the requested civil one and prints
the civil slice.
.SH COMMANDS
.TP
.BI easter " YEAR"
Easter and the movable feasts anchored to it \(em Ash Wednesday, Palm Sunday,
Ascension, Pentecost, Corpus Christi \(em one per line, as
.RI \(lq name " " date \(rq.
.TP
.BI temporal " YEAR"
The temporal cycle alone, one line per day, before the sanctoral calendar is
resolved against it. Chiefly useful for inspecting season and week boundaries
in isolation.
.TP
.BI day " YEAR"
The resolved day identity, one line per day: the temporal cycle and the
sanctoral calendar reconciled by the rite's own rules of precedence,
occurrence, commemoration and transfer.
.TP
.BI readings " YEAR"
The Mass reading citations, one line per day.
.TP
.B new\-overlay
Print a starter overlay file to standard output, for redirection. Every value
in it is a placeholder that will appear in
.B day
output if left unedited, so a half\-finished overlay is visible rather than
silently inert.
.TP
.BI check " FILE" ...
Load each overlay, apply it to the shipped calendar, and report what it does:
the directive counts, the slug each targets, and any directive that matched
nothing. Exits
.B 2
if a file fails to load or a directive found no target, so it composes into a
Makefile or a pre\-commit hook. It answers three narrow questions \(em does
the file parse, does every directive find its target, and what does the merged
result contain. It does
.I not
validate a calendar against the rubrics, and cannot: see
.B OVERLAYS
below.
.TP
.BI \-\-overlay " FILE"
Apply a user calendar on top of the shipped one. Repeatable and ordered;
.B day
and
.B readings
only. See
.B OVERLAYS
below.
.TP
.BR \-h ", " \-\-help
Print a usage summary to standard output and exit 0.
.TP
.BR \-V ", " \-\-version
Print the version and exit 0.
.SH OUTPUT FORMAT
.SS day
.RS
.nf
date weekday season week slug rank colour [+commemoration ...]
.fi
.RE
.PP
Space\-separated, with one
.BI + slug
suffix per admitted commemoration. A
.B \-
in the week column means the day carries no week number.
.RS
.nf

2026\-04\-05 sunday paschaltide 1 ef\-easter\-sunday class\-1 white
2026\-11\-02 monday time\-after\-pentecost 23 commemoration\-of\-all\-souls class\-1 black
2057\-03\-26 monday lent 3 annunciation\-of\-the\-blessed\-virgin\-mary class\-1 white +ef\-lent\-3\-monday
.fi
.RE
.SS readings
.RS
.nf
date slug | Epistle | Gospel
.fi
.RE
.PP
A reading citation contains spaces and commas, so this report separates its
fields with
.RB \(lq " | " \(rq
where
.B day
stays space\-separated. That is the reason the citations are a separate command
rather than extra columns on
.BR day :
appended there, no field number could recover where the Epistle ended. A
.B \-
in either citation field means none was resolved.
.RS
.nf

2026\-12\-25 ef\-nativity | Heb 1:1\-12 | John 1:1\-14
2038\-03\-06 sts\-felicitas\-perpetua | Ecclus 51:1\-8, 12 | Matt 13:44\-52
.fi
.RE
.PP
Both reports are one line per day and ordered by date, so they compose with
.BR grep (1),
.BR awk (1)
and
.BR join (1)
in the ordinary way.
.SH OVERLAYS
.TP
.BI \-\-overlay " FILE"
.RB ( \-o )
Apply a user\-supplied calendar on top of the shipped universal one. Repeatable
and ordered.
.PP
Overlays are applied
.I on top of
the 1962 universal calendar, never instead of it. The shipped adjustments \(em
which carry the inseparable Peter/Paul commemoration, the Major Litanies, St
Barbara and Rogation Wednesday \(em are applied first, then each
.B \-\-overlay
in the order given. Last writer wins, so a later file may deliberately override
an earlier one, or a universal entry, by naming its slug.
.PP
The workflow:
.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
An overlay is an S\-expression file with an
.I id
and a list of directives:
.BR Add ", " Suppress ", " Replace " and " Edit .
An added entry carries its own date specification, which may be a fixed
.RI ( month ", " day )
pair, an
.I Easter_offset
in days (signed; Easter itself is 0), or an
.I Nth_weekday
of a month \(em the
.I nth
may be negative to count from the end, so
.B \-1
is the last \(em so a patronal feast on "the first Sunday of October" or a
dedication anniversary reckoned from Easter are both expressible.
.PP
In an added celebration the
.I citations
and
.I layer
fields may be omitted: they default to empty and to the overlay's own
.IR id .
The remaining six are required, and each is a closed set \(em
.I rank
is
.BR Class1 ", " Class2 ", " Class3 " or " Class4 ,
.I status
is
.B Feast
or
.BR Commemoration_only ,
.I colour
is
.BR White ", " Red ", " Violet ", " Green ", " Black " or " Rose ,
and
.I subject
is
.BR Lord ", " Bvm ", " Saint " or " Temporal .
See
.I <prefix>/share/colitur/examples/diocesan\-example.sexp
for a worked, runnable example of all four directives and all three date
shapes:
.RS
.nf

.B colitur day 2026 \-\-overlay <prefix>/share/colitur/examples/diocesan\-example.sexp
.fi
.RE
.PP
Accepted on
.B day
and
.B readings
only. The other commands read no sanctoral data at all, so the flag would have
no effect there and is
.I refused
rather than silently ignored.
.PP
.B An overlay is applied, not validated.
This program's test layers \(em properties over every year in the domain, a
differential against a sibling engine, two published\-calendar oracles, and
hand\-verified pins \(em assert things about the
.I shipped
calendar. None of them can vouch for a file you supply. A directive naming a
slug that does not exist prints a warning to standard error and the run
continues, so a typo in a local calendar is visible rather than silent; a file
that fails to load is fatal.
.SH ENVIRONMENT
.TP
.B COLITUR_DATA_DIR
Read the calendar data from this directory instead of the installed or
build\-tree location. If it is set and contains no
.IR sanctoral.sexp ,
.B colitur
exits 2 naming the directory; it does
.I not
fall back to another copy. Naming a directory states an intent, and quietly
computing a calendar from different data than the one requested is a failure
mode this program refuses.
.SH FILES
.TP
.I <prefix>/share/colitur/ef/
The installed calendar data: the sanctoral calendar, its one hand\-authored
overlay, the temporal lectionary and the Commons. Four S\-expression files.
.TP
.I <prefix>/share/colitur/examples/diocesan\-example.sexp
A worked example overlay, shipped as runnable documentation. Every
celebration in it is invented; copy it and put your own calendar in its place.
.TP
.I <exedir>/../data/ef/
The build\-tree location, used when running from a source checkout.
.PP
Resolution order is
.B COLITUR_DATA_DIR
first, then the installed directory, then the build tree. A directory counts
only if it actually contains
.IR sanctoral.sexp ,
so a failed or half\-removed installation falls through to a working checkout
instead of shadowing it.
.SH EXIT STATUS
.TP
.B 0
Success.
.TP
.B 2
Bad usage, a year outside 1583..9999, or the calendar data could not be read.
.SH EXAMPLES
Easter and its dependent feasts:
.RS
.nf

.B colitur easter 2026
.fi
.RE
.PP
One date:
.RS
.nf

.B colitur day 2026 | grep '^2026\-12\-25'
.fi
.RE
.PP
Every first\-class day of a year:
.RS
.nf

.B colitur day 2026 | awk '$6 == "class\-1"'
.fi
.RE
.PP
Days carrying at least one commemoration:
.RS
.nf

.B colitur day 2027 | grep '+'
.fi
.RE
.PP
A local calendar on top of the universal one:
.RS
.nf

.B colitur day 2026 \-\-overlay ~/calendars/diocese.sexp
.B colitur day 2026 \-\-overlay ~/calendars/diocese.sexp \-\-overlay ~/calendars/parish.sexp
.fi
.RE
.PP
Run against a checkout's data rather than the installed copy:
.RS
.nf

.B COLITUR_DATA_DIR=~/git/projects/colitur/data/ef colitur day 2026
.fi
.RE
.SH SOURCES
The calendar is computed against the 1962
.I Missale Romanum
and its
.IR "Rubricae Generales" ,
which are the sole authority for what
.B colitur
emits. Published calendars \(em missalemeum, Divinum Officium, gcatholic \(em
are used as comparison oracles in the test suite only: a divergence from one
is flagged loudly and adjudicated against the Missal, never silently adopted.
Several such divergences have been resolved in this engine's favour.
.SH LIMITATIONS
Only the Extraordinary Form (1962) is implemented; the Ordinary Form is a
planned peer module, not an overlay of this one.
.PP
Only the Epistle and the Gospel are emitted. The chants \(em Psalm, Gradual,
Tract, Alleluia, Sequence \(em are deliberately not computed: they have no
source in this engine's data and no oracle to validate them against, and the
engine rejects any citation part outside those two rather than emit one it
cannot stand behind.
.PP
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 lectio (1)
.SH LICENSE
AGPL\-3.0\-or\-later.