diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/colitur.1 | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/man/colitur.1 b/man/colitur.1 new file mode 100644 index 0000000..c65cc58 --- /dev/null +++ b/man/colitur.1 @@ -0,0 +1,219 @@ +.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 <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 <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 +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. |