diff options
Diffstat (limited to 'man/colitur.1')
| -rw-r--r-- | man/colitur.1 | 76 |
1 files changed, 76 insertions, 0 deletions
diff --git a/man/colitur.1 b/man/colitur.1 index c65cc58..a18b299 100644 --- a/man/colitur.1 +++ b/man/colitur.1 @@ -7,6 +7,12 @@ colitur \- deterministic liturgical calendar and lectionary engine (Roman rite, .I YEAR .br .B colitur +.BR day | readings +.I YEAR +.BI \-\-overlay " FILE" +.RI [ ... ] +.br +.B colitur .BR \-h | \-\-help .SH DESCRIPTION .B colitur @@ -59,8 +65,20 @@ occurrence, commemoration and transfer. .BI readings " YEAR" The Mass reading citations, one line per day. .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 @@ -114,6 +132,55 @@ Both reports are one line per day and ordered by date, so they compose with 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 +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, or an +.I Nth_weekday +of a month \(em so a patronal feast on "the first Sunday of October" or a +dedication anniversary reckoned from Easter are both expressible. See +.I test/fixtures/overlay\-example\-diocesan.sexp +in the source distribution for a worked example of both shapes. +.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 @@ -182,6 +249,15 @@ Days carrying at least one commemoration: .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 |