diff options
Diffstat (limited to 'man/colitur.1')
| -rw-r--r-- | man/colitur.1 | 314 |
1 files changed, 249 insertions, 65 deletions
diff --git a/man/colitur.1 b/man/colitur.1 index a55e476..1a330d8 100644 --- a/man/colitur.1 +++ b/man/colitur.1 @@ -7,9 +7,15 @@ colitur \- deterministic liturgical calendar and lectionary engine (Roman rite, .I YEAR .br .B colitur -.BR day | readings +.B temporal .I YEAR .RB [ \-\-rite " ef\(brof" ] +.br +.B colitur +.BR day | readings | rubrics +.RI [ YEAR ] +.RB [ \-\-year " YEAR" ] +.RB [ \-\-rite " ef\(brof" ] .RB [ \-\-overlay " FILE" " ...]" .RB [ \-\-lang " CODE\(brFILE" ] .RB [ \-\-sigla\-style " CODE\(brFILE" ] @@ -18,15 +24,11 @@ colitur \- deterministic liturgical calendar and lectionary engine (Roman rite, .RB [ \-\-raw ] .br .B colitur -.B rubrics -.I YEAR -.RB [ \-\-overlay " FILE" " ...]" -.br -.B colitur .B emit .BI \-\-format " FMT" .BI \-\-from " YEAR" .BI \-\-to " YEAR" +.RB [ \-\-rite " ef\(brof" ] .RB [ \-\-overlay " FILE" " ...]" .RB [ \-\-dtstamp " STAMP" ] .RB [ \-\-lang " CODE\(brFILE" ] @@ -37,8 +39,10 @@ colitur \- deterministic liturgical calendar and lectionary engine (Roman rite, .br .B colitur .BR table | render -.BI \-\-year " YEAR" +.RI [ YEAR ] +.RB [ \-\-year " YEAR" ] .BI \-\-template " FILE" +.RB [ \-\-rite " ef\(brof" ] .RB [ \-\-flavour " FLAVOUR" ] .RB [ \-\-overlay " FILE" " ...]" .RB [ \-\-lang " CODE\(brFILE" ] @@ -52,6 +56,7 @@ colitur \- deterministic liturgical calendar and lectionary engine (Roman rite, .BI \-\-from " YEAR" .BI \-\-to " YEAR" .BI \-\-out " DIR" +.RB [ \-\-rite " ef\(brof" ] .RB [ \-\-overlay " FILE" " ...]" .RB [ \-\-prune ] .RB [ \-\-dtstamp " STAMP" ] @@ -112,7 +117,14 @@ Ascension, Pentecost, Corpus Christi \(em one per line, as .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. +in isolation. Takes +.B \-\-rite +(default +.BR ef , +see below): the OF's own temporal cycle has five seasons, no Septuagesima, +and every slug carries an "of\-" prefix rather than "ef\-", so +.B \-\-rite\ of +changes essentially every line. .TP .BI day " YEAR" The resolved day identity, one line per day: the temporal cycle and the @@ -122,6 +134,27 @@ occurrence, commemoration and transfer. .BI readings " YEAR" The Mass reading citations, one line per day. .TP +.BI \-\-year " YEAR" +An alternative to the positional +.I YEAR +shown above, accepted (additively, not instead) on +.BR day ", " readings ", " rubrics ", " table " and " render : +.BR "colitur day \-\-year 2026" +means exactly what +.BR "colitur day 2026" +does. Naming both is fine as long as they agree; naming both with +.I different +years is a usage error, not one silently overriding the other. +.B emit +and +.B publish +do not take +.BR \-\-year : +they take a range instead +.RB ( "\-\-from Y \-\-to Y" , +inclusive, including for a single year), and gain no second, redundant +spelling of the same thing. +.TP .BR \-\-rite " " ef\(brof Select the rite module. .B ef @@ -130,17 +163,52 @@ Select the rite module. at all is byte\-identical to before this flag existed) computes the Roman .B EF (1962); the alternative, -.BR of ", " computes the Roman +.BR of , +computes the Roman .B OF (the post\-1970 Missal, base calendar the 2002 -.IR Missale Romanum , -editio typica tertia). Accepted only by -.B day -and -.BR readings ; -every other command refuses it rather than silently ignoring it, printing -one line to standard error and exiting +.IR "Missale Romanum" , +editio typica tertia). Accepted by +.BR day ", " readings ", " rubrics ", " temporal ", " emit ", " table ", " render " and " publish ; +refused, not silently ignored, on +.BR check / convert +(operate on an overlay file, not a computed year), +.B new\-overlay +(prints a static starter, no calendar computation), and +.BR lang / config +(answer naming/config questions orthogonal to any rite) \(em one line to +standard error and exit .BR 2 . +.B easter +is refused too, but PROVEN rite\-invariant rather than merely unbuilt for +.BR of : +EF and OF reckon Easter on the identical Gregorian computus, so no second +value could ever change the six dates it prints. +.BR "colitur emit \-\-format csv \-\-rite of" +and +.BR "colitur publish \-\-rite of" +widen the CSV output with a 17th column, +.IR second , +between +.I first +and +.IR gospel : +present, and usually empty, because a Sunday or solemnity genuinely carries +a Second reading (OLM 1981 Praenotanda n. 66.1) and a feria/feast/memorial +does not (n. 69.1); EF's own 16\-column header is unaffected, byte for byte, +because EF's citations never contain one \(em see +.B EMIT +below. A single +.B \-\-out +directory can hold both rites' own +.B publish +trees side by side +.RI ( ef/ ", " of/ ), +but not safely combined with +.BR \-\-prune : +see +.B PUBLISH +below. The OF module is younger than the EF one: it has no published\-ordo witness yet, its lectionary's English text is niedziela.pl's own translation lineage (not the USA\-English one), and a handful of dates are known\-wrong @@ -489,7 +557,7 @@ own trailing field, above. .SS rubrics .RS .nf -date [TAB] formulary\-slug [TAB] source [TAB] creed [TAB] gloria [TAB] preface +date [TAB] formulary\-slug [TAB] source [TAB] creed [TAB] gloria [TAB] preface [TAB name] .fi .RE .PP @@ -504,10 +572,9 @@ or .RB \(lq " | " \(rq like .B readings -\(em because a resolved formulary NAME (a column a later version may add, -not either of these) can carry both spaces and punctuation a citation never -does, which rules out either separator already in use above. A separate -command for the identical mechanical reason +\(em because the resolved formulary NAME (below) can carry both spaces and +punctuation a citation never does, which rules out either separator already +in use above. A separate command for the identical mechanical reason .B day is separate from .BR readings : @@ -550,22 +617,29 @@ here can also mean a rite that has not implemented the rule at all. .RS .nf -2026\-01\-01 [TAB] ef\-circumcision [TAB] own [TAB] true [TAB] true [TAB] nativity -2038\-03\-08 [TAB] john\-of\-god [TAB] proper [TAB] false [TAB] true [TAB] common -2025\-12\-01 [TAB] ef\-advent\-sunday\-1 [TAB] preceding\-sunday [TAB] false [TAB] false [TAB] common +2026\-01\-01 [TAB] ef\-circumcision [TAB] own [TAB] true [TAB] true [TAB] nativity [TAB] In Octava Nativitatis Domini +2038\-03\-08 [TAB] john\-of\-god [TAB] proper [TAB] false [TAB] true [TAB] common [TAB] S. Ioannis a Deo Conf. +2025\-12\-01 [TAB] ef\-advent\-sunday\-1 [TAB] preceding\-sunday [TAB] false [TAB] false [TAB] common [TAB] Dominica I Adventus .fi .RE .PP -Unlike +Like .B day and .BR readings , .B rubrics -resolves no display name and no citation, so it takes none of -.BR \-\-lang ", " \-\-raw -or any +resolves the formulary slug to a display name under +.BR \-\-lang / \-\-raw : +appended as a trailing 8th field, present only when it differs from the +slug already shown \(em the identical append\-only rule those two commands +use, so +.B \-\-raw +(or a language with no entry for that day) is byte\-identical to the +seven\-field row shown above. It resolves no +.I citation +of its own, though, so .B \-\-sigla\-* -flag \(em refused rather than silently ignored, the same discipline +stays refused \(em the same discipline .B \-\-overlay gets on .B easter @@ -580,16 +654,9 @@ and .BR join (1) in the ordinary way. Pass .B \-\-raw -to restore the pre\-naming byte\-exact output of -.B day -or -.B readings -\(em no trailing field at all \(em for a script written against either -before the naming feature existed; -.B rubrics -is already in that form and has no -.B \-\-raw -of its own to pass. +to restore the pre\-naming byte\-exact output of any of the three \(em no +trailing field at all \(em for a script written against one before its own +naming feature existed. .SH EMIT .BI "colitur emit " \-\-format " FMT " \-\-from " YEAR " \-\-to " YEAR" renders the same resolved day \(em season, week, slug, rank, colour, @@ -625,6 +692,31 @@ stay the kernel's own unlocalised keys, unaffected by .BR \-\-lang / \-\-raw , so a script can key off the stable machine value while a human reads the localised one beside it. +.PP +The header is +.B \-\-rite +dependent. EF's 16 columns above are unchanged from before +.B \-\-rite +existed on +.B emit +at all; any other rite +.RB ( of +today) gets a 17th column, +.IR second , +between +.I first +and +.IR gospel : +present, and usually empty, because a Sunday or solemnity genuinely +carries a Second reading (OLM 1981 Praenotanda n. 66.1) and a +feria/feast/memorial does not (n. 69.1). +.RS +.nf + +.B colitur emit \-\-rite of \-\-format csv \-\-from 2026 \-\-to 2026 | head \-1 +date,rite,season,season_name,week,slug,name,weekday,rank,rank_name,colour,colour_name,subject,first,second,gospel,comms +.fi +.RE .TP .B json One JSON object per requested year, concatenated. Shape pinned by @@ -697,10 +789,29 @@ applied on top of the shipped calendar, in order, before the range is rendered. See .B OVERLAYS below. +.PP +.BR \-\-rite +selects the rite module exactly as on +.B day +and +.BR readings ; +see the +.B \-\-rite +entry under +.B COMMANDS +above for the full account, CSV's own +.I second +column included. .SH RENDERING -.BI "colitur table " \-\-year " YEAR " \-\-template " FILE" +.B "colitur table" +.RI [ YEAR ] +.RB [ \-\-year " YEAR" ] +.BI \-\-template " FILE" and -.BI "colitur render " \-\-template " FILE " \-\-year " YEAR" +.B "colitur render" +.BI \-\-template " FILE" +.RI [ YEAR ] +.RB [ \-\-year " YEAR" ] are the .I same operation under two names: compute the resolved year, shape it into the @@ -708,8 +819,20 @@ same view .B emit uses, and render it through .I FILE -in one process. Both accept -.BR \-\-flavour " and " \-\-overlay +in one process. +.I YEAR +may be given positionally or as +.BR \-\-year , +additively, the same either\-or\-both\-if\-they\-agree rule +.B day +and +.B readings +follow (see +.B \-\-year +under +.B COMMANDS +above). Both commands accept +.BR \-\-rite ", " \-\-flavour " and " \-\-overlay identically. .SS Why there is no stdin\-fed render The design this project followed originally sketched a Unix pipe, @@ -769,7 +892,18 @@ list, with padding cells flagged for the leading and trailing blanks a grid needs and a booklet does not). A key absent on a given day (an optional field a rite does not always set) renders as the empty string rather than an error \(em the one deliberate silence, so a template survives a day that does not -carry every optional field. +carry every optional field. This is also what happens, harmlessly, when a +template written for one rite is pointed at the other's year with +.BR \-\-rite : +an EF\-era template that never references +.B {{second}} +(OF's own Sunday/solemnity Second reading) simply does not show it, neither +crashing nor dropping any other field, because both rites expose the +identical key +.I set +and differ only in the resolved +.I values +(e.g. season names) underneath it. .PP See .BR colitur\-templates (5) @@ -867,17 +1001,47 @@ serve the result as\-is and nothing runs at request time. .RS .nf -ef/<year>.json one civil year, all days, whole\-year emitters -ef/<year>.csv -ef/<year>.xml -ef/<year>.ics -ef/<year>/<mm>/<dd>.json one file per day +<rite>/<year>.json one civil year, all days, whole\-year emitters +<rite>/<year>.csv +<rite>/<year>.xml +<rite>/<year>.ics +<rite>/<year>/<mm>/<dd>.json one file per day schema/day\-v1.json the published JSON contract index.html a generated index page, not a template \&.colitur\-manifest every path this run wrote, one per line .fi .RE .PP +.I <rite> +is +.B ef +or +.BR of , +selected by +.BR \-\-rite +exactly as on every other command (default +.BR ef ). +A single +.B \-\-out +directory can hold both rites' own trees side by side, across two separate +invocations \(em but +.I not +safely combined with +.BR \-\-prune : +the manifest and +.I index.html +publish writes describe the +.I whole +tree, not one rite's own slice of it, so a +.B \-\-rite of +run's own manifest never mentions an earlier EF run's files, and +.B \-\-prune +would delete them as stale. Publish a single rite per +.BR \-\-out , +or omit +.B \-\-prune +when deliberately layering both. +.PP Every emitted file goes through the same emitters .B emit uses; a published @@ -960,6 +1124,15 @@ applied on top of the shipped calendar, in order, before each year in the range is rendered. See .B OVERLAYS below. +.PP +.BR \-\-rite +selects the rite module and its own output subtree +.RI ( <rite>/ , +above) exactly as on every other command; see the +.B \-\-rite +entry under +.B COMMANDS +for the full account. .SH OVERLAYS .TP .BI \-\-overlay " FILE" @@ -1066,8 +1239,12 @@ each month's own name, and the fixed .I term vocabulary a template routes through \(em through this language instead of the default. Accepted on -.BR day ", " readings ", " emit ", " table ", " render " and " publish ; -refused elsewhere, the same discipline +.BR day ", " readings ", " rubrics ", " emit ", " table ", " render " and " publish +(on +.BR rubrics , +it resolves the formulary slug rather than the observed day's own \(em see +.B OUTPUT FORMAT +above); refused elsewhere, the same discipline .B \-\-overlay gets. .I CODE @@ -1126,12 +1303,10 @@ is an ordinary language table like any other, under which every lookup echoes its key back unchanged, so .B \-\-raw and a real language file share the same code path throughout. -.B day -and -.B readings +.BR day ", " readings " and " rubrics under .B \-\-raw -are byte\-identical to this program's own pre\-naming output; every existing +are byte\-identical to each command's own pre\-naming output; every existing script built against that output therefore needs one flag, not a rewrite. .B \-\-raw also governs every reading citation, through a dedicated @@ -1643,18 +1818,27 @@ validated of the two, against five independent layers including a published Ordo witness. The Ordinary Form (OF, the post\-1970 Missal, base calendar the 2002 .I Missale Romanum ) -is younger: it has no published\-ordo witness yet, a handful of dates are +is younger: it has no published\-ordo witness yet, and a handful of dates are known\-wrong and pinned rather than fixed (St Joseph anticipated onto Palm -Sunday, Normae n. 56(f); the Holy Family Sunday fallback of Normae n. 35(a)), -and on a Sunday or solemnity its lectionary carries only the first reading -and the Gospel, not the Second Reading (the Apostle) or the responsorial -psalm. +Sunday, Normae n. 56(f); the Holy Family Sunday fallback of Normae n. 35(a)). .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. +EF emits the Epistle and the Gospel only \(em its own +.I citations +are always exactly that pair, on every day of every year 1583..9999. OF +also emits a Second reading (the Apostle) on the Sundays and solemnities +its own shipped lectionary carries one for (OLM 1981 Praenotanda n. 66.1 +vs n. 69.1: a Sunday/solemnity Mass has three readings, a feria/feast/ +memorial two) \(em 183 of 1725 emitted citation fields in +.I data/of/lectionary.sexp +today, every one from a Sunday\-cycle entry, never a weekday\-cycle one; the +responsorial Psalm itself (present in the underlying pastoral source) is +deliberately NOT extracted \(em a chant, not a reading, and named in +neither rite's own well\-formed citation shapes. The chants proper \(em +Psalm, Gradual, Tract, Alleluia, Sequence \(em are deliberately not +computed for either rite: they have no source in this engine's data and no +oracle to validate them against, and the engine rejects any citation part +outside its own rite's well\-formed shapes 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 |