.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 \-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 .BR \-h ", " \-\-help Print a usage summary to standard output 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 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 /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 /../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 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.