diff options
| -rw-r--r-- | README.md | 62 | ||||
| -rw-r--r-- | man/colitur.1 | 380 |
2 files changed, 437 insertions, 5 deletions
@@ -67,6 +67,68 @@ entry naming a slug that does not exist (a typo, otherwise silently dead). it came from. See `colitur(1)`'s `NAMING` section and `colitur-config(5)` for both in full. +## Citations + +A reading citation (`Jn 3:16`) is parsed into structure and re-rendered, so +its book names, its punctuation/abbreviation convention, and its numbering +tradition are each a file to edit, not something the engine hardcodes. One +day, four ways -- every line below is real, not transcribed: + +```sh +$ dune exec colitur -- readings 2026 | grep ^2026-02-25 +2026-02-25 ef-lent-ember-wed | 3 Reg 19:3-8 | Matth 12:38-50 | Feria IV Quatuor Temporum Quadragesimae + +$ dune exec colitur -- readings 2026 --sigla-book full | grep ^2026-02-25 +2026-02-25 ef-lent-ember-wed | Liber Regum III 19:3-8 | Evangelium secundum Matthaeum 12:38-50 | Feria IV Quatuor Temporum Quadragesimae + +$ dune exec colitur -- readings 2026 --lang en | grep ^2026-02-25 +2026-02-25 ef-lent-ember-wed | 3 Kgs. 19:3-8 | Matt 12:38-50 | Lenten Ember Wednesday + +$ dune exec colitur -- readings 2026 --lang en --sigla-tradition modern | grep ^2026-02-25 +2026-02-25 ef-lent-ember-wed | 1 Kgs 19:3-8 | Matt 12:38-50 | Lenten Ember Wednesday +``` + +The same four results, from a config file instead of flags (each block is +the entire `[defaults]` section on its own -- not one file with all four): + +```ini +# 1. Latin abbreviated -- the built-in default, no entries needed +[defaults] + +# 2. Latin full +[defaults] +sigla_book = full + +# 3. English (Vulgate numbering: "3 Kings", not "1 Kings") +[defaults] +lang = en + +# 4. English, modern numbering +[defaults] +lang = en +sigla_tradition = modern +``` + +Two axes are independent and easy to conflate. `--lang`/`sigla_book` (and +a language file's own `[bible]` section) decide what a book is *called* -- +this varies by language. `--sigla-tradition` (`lang/traditions.ini`) +decides which book a reference *denotes* -- this does not vary by +language. `3 Kings 19:3-8` and `1 Kings 19:3-8` above are the *same* verse, +renumbered, not two different readings; conflating naming with renumbering +is how a citation ends up naming the wrong book. + +`--raw` bypasses all of it: every citation is emitted exactly as stored, +byte-for-byte, independently of the parser -- what a script diffing this +engine's output against the sibling `lectio` engine depends on: + +```sh +$ dune exec colitur -- readings 2026 --raw | grep ^2026-02-25 +2026-02-25 ef-lent-ember-wed | 3 Kgs. 19:3-8 | Matt 12:38-50 +``` + +See `colitur(1)`'s `SIGLA` section for the `[bible]`/`[sigla]` language-file +sections, `lang/traditions.ini` in full, and all three `--sigla-*` flags. + ## License AGPL-3.0-or-later. See `LICENSE`. diff --git a/man/colitur.1 b/man/colitur.1 index df7ad3e..4a3c580 100644 --- a/man/colitur.1 +++ b/man/colitur.1 @@ -11,6 +11,9 @@ colitur \- deterministic liturgical calendar and lectionary engine (Roman rite, .I YEAR .RB [ \-\-overlay " FILE" " ...]" .RB [ \-\-lang " CODE\(brFILE" ] +.RB [ \-\-sigla\-style " CODE\(brFILE" ] +.RB [ \-\-sigla\-book " full\(brabbr" ] +.RB [ \-\-sigla\-tradition " NAME" ] .RB [ \-\-raw ] .br .B colitur @@ -21,6 +24,9 @@ colitur \- deterministic liturgical calendar and lectionary engine (Roman rite, .RB [ \-\-overlay " FILE" " ...]" .RB [ \-\-dtstamp " STAMP" ] .RB [ \-\-lang " CODE\(brFILE" ] +.RB [ \-\-sigla\-style " CODE\(brFILE" ] +.RB [ \-\-sigla\-book " full\(brabbr" ] +.RB [ \-\-sigla\-tradition " NAME" ] .RB [ \-\-raw ] .br .B colitur @@ -30,6 +36,9 @@ colitur \- deterministic liturgical calendar and lectionary engine (Roman rite, .RB [ \-\-flavour " FLAVOUR" ] .RB [ \-\-overlay " FILE" " ...]" .RB [ \-\-lang " CODE\(brFILE" ] +.RB [ \-\-sigla\-style " CODE\(brFILE" ] +.RB [ \-\-sigla\-book " full\(brabbr" ] +.RB [ \-\-sigla\-tradition " NAME" ] .RB [ \-\-raw ] .br .B colitur @@ -41,6 +50,9 @@ colitur \- deterministic liturgical calendar and lectionary engine (Roman rite, .RB [ \-\-prune ] .RB [ \-\-dtstamp " STAMP" ] .RB [ \-\-lang " CODE\(brFILE" ] +.RB [ \-\-sigla\-style " CODE\(brFILE" ] +.RB [ \-\-sigla\-book " full\(brabbr" ] +.RB [ \-\-sigla\-tradition " NAME" ] .RB [ \-\-raw ] .br .B colitur @@ -188,7 +200,8 @@ below. .TP .B config \-\-show Print every effective setting \(em -.IR lang ", " overlay ", " template ", " format +.IR lang ", " overlay ", " template ", " format ", " sigla_style ", " +.IR sigla_book " and " sigla_tradition \(em its resolved value, and where it came from: .BR flag ", " config " or " default . See @@ -290,11 +303,60 @@ what is available, never a silent fallback to Latin. See .B NAMING below. .TP +.BI \-\-sigla\-style " CODE\(brFILE" +.RB ( day ", " readings ", " emit ", " table ", " render " and " publish " only)" +Which punctuation/abbreviation convention to render a Mass reading citation +in \(em looked up exactly as +.B \-\-lang +is (a +.I CODE +against the installed language directory, or a literal path). Default the +resolved +.BR \-\-lang , +overridable by a config file. See +.B SIGLA +below. +.TP +.BI \-\-sigla\-book " full\(brabbr" +.RB ( day ", " readings ", " emit ", " table ", " render " and " publish " only)" +Which form of the book name a citation uses. Default +.BR abbr , +overridable by a config file. An unrecognised value is a hard error, the +same discipline an unknown +.B \-\-lang +gets. See +.B SIGLA +below. +.TP +.BI \-\-sigla\-tradition " NAME" +.RB ( day ", " readings ", " emit ", " table ", " render " and " publish " only)" +Which numbering tradition a citation's book DENOTES \(em a section name in +.BR lang/traditions.ini . +Default +.BR vulgate , +overridable by a config file. Unlike +.B \-\-sigla\-book +and +.BR \-\-lang , +an unrecognised value is +.I not +fatal: it degrades to +.B vulgate +with a warning on standard error, because asking for a renumbering is +optional the way asking for a language is not. See +.B SIGLA +below. +.TP .B \-\-raw .RB ( day ", " readings ", " emit ", " table ", " render " and " publish " only)" Restore the pre\-naming output: every display name equals its bare machine -slug. See +slug, and every reading citation is emitted +.B verbatim +\(em exactly as stored, bypassing the parser, the style, the book form and +the tradition entirely. See .B NAMING +and +.B SIGLA below. .TP .BR \-h ", " \-\-help @@ -361,7 +423,10 @@ 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. The resolved display +in either citation field means none was resolved. A citation's book names, +punctuation and numbering are all configurable \(em see +.B SIGLA +below. The resolved display .I name is appended as a fourth, .RB \(lq " | " \(rq \-delimited @@ -931,6 +996,12 @@ under .B \-\-raw are byte\-identical to this program'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 +.I verbatim +path rather than an identity language table \(em see +.B SIGLA +below for why that distinction matters. .TP .B lang \-\-list .TQ @@ -969,7 +1040,8 @@ merely a hand\-picked sample. .TP .B config \-\-show Print every effective setting \(em -.IR lang ", " overlay ", " template ", " format +.IR lang ", " overlay ", " template ", " format ", " sigla_style ", " +.IR sigla_book " and " sigla_tradition \(em its resolved value, and where it came from: .BR flag ", " config " or " default , via the same resolver every other command uses (there is deliberately no @@ -977,7 +1049,305 @@ separate "provenance" function, so the two cannot disagree). Also prints the config file's own path and whether it exists. See .BR colitur\-config (5) for the file's location, its precedence in full, and every setting it -recognises. +recognises (as of this writing that page still describes the original four; +.BR sigla_style / sigla_book / sigla_tradition +are the same +.B [defaults] +mechanism, documented in full here in +.B SIGLA +below). +.SH SIGLA +A Mass reading citation +.RB ( "Jn 3:16" ) +is parsed into structure \(em book, chapter, verses \(em and re\-rendered, so +its book names, its punctuation and abbreviation convention, and its +numbering tradition are each a file a reader can edit, not something baked +into the engine. This section covers the three flags, the two language\-file +sections that drive them, and +.IR lang/traditions.ini . +.SS Two different questions +Getting a citation right involves two independent questions that are easy +to conflate: +.RS +.nf + +what is the book CALLED? -- a language file's [bible] section +what book does it DENOTE? -- lang/traditions.ini +.fi +.RE +.PP +Naming varies by language: the third book of Kings is +.I "Liber Regum III" +in +.I lang/la.ini +and +.I "3 Kings" +in +.IR lang/en.ini . +Denoting does not: "modern numbering" renumbers the SAME book the SAME way +whether the citation is rendered in Latin, English or any other language, so +it lives in one file, not one section per language. Conflating the two is +how a citation ends up naming the +.I wrong +book \(em correct punctuation, correct language, wrong reference. +.SS "[sigla] -- how a citation is written" +A language file's +.I [sigla] +section is a citation +.I style : +.RS +.nf + +book = abbr ; or full +book_sep = " " +chapter_verse = {chapter}:{verses} +range = {first}\-{last} +part_sep = "; " +verse_sep = ", " +.fi +.RE +.PP +.BR book " and " book_sep +control the book name and what separates it from the reference proper. +.BR chapter_verse " and " range +are templates: the placeholders +.BR {chapter} ", " {verses} " (in " chapter_verse ) +and +.BR {first} ", " {last} " (in " range ) +are substituted; an unrecognised +.B {placeholder} +is left in the output literally, so a typo in a hand\-written style file is +visible rather than silently swallowed. +.B {chapter_roman} +is also available in +.BR chapter_verse , +an alternative to +.B {chapter} +that prints the chapter as a Roman numeral \(em set +.RI ( "chapter_verse = {chapter_roman}, {verses}" ) +and the Missal's own idiom +("Feria IV", "Hebdomada I") extends to citations too: +.RS +.nf + +$ colitur readings 2026 | grep 2026\-06\-21 +2026\-06\-21 ef\-time\-after\-pentecost\-sunday\-4 | Rom 8:18\-23 | Luc 5:1\-11 | \e +Dominica IV post Pentecosten +$ colitur readings 2026 \-\-sigla\-style my\-roman\-style.ini | grep 2026\-06\-21 +2026\-06\-21 ef\-time\-after\-pentecost\-sunday\-4 | Rom VIII, 18\-23 | Luc V, 1\-11 | \e +Dominica IV post Pentecosten +.fi +.RE +.PP +(where +.I my\-roman\-style.ini +carries only +.RI ( "chapter_verse = {chapter_roman}, {verses}" ) +under its own +.IR [sigla] ). +.PP +.BR part_sep " and " verse_sep +separate multiple readings within one citation and multiple verse ranges +within one reading, respectively \(em what makes +.I "Ecclus 51:1\-8, 12" +and +.I "Ioel 2:23\-24; 2:26\-27" +render correctly. +.PP +.B "book_sep and typeset output." +A booklet rendered to LaTeX or Typst may want a +.B non\-breaking +space here, so a line break can never fall between the book abbreviation and +its reference (\(lqLuc.\(rq stranded at the end of one line, \(lq5, 12\-14\(rq +starting the next). Set +.B book_sep +to a literal +.B U+00A0 +character \(em typed directly into the INI file, not a LaTeX tie +.RB ( "~" ) : +the flavour escapers match ASCII bytes only, so a real U+00A0 (a two\-byte +UTF\-8 sequence) passes through every flavour untouched, but a literal +.B "~" +does +.I not +survive the LaTeX escaper, which turns it into +.BR \etextasciitilde{} . +.B "U+00A0 is invisible in a terminal" \(em +it looks exactly like an ordinary space in an editor, in +.BR "cat colitur.ini" , +and in a diff that does not mark whitespace \(em so a careless copy\-paste +can silently replace it with a normal space, or vice versa. Verify what is +actually in the file, not what it looks like: +.RS +.nf + +$ grep \-o 'book_sep.*' my\-style.ini | xxd | head \-1 +00000000: 626f 6f6b 5f73 6570 203d 2022 c2a0 220a book_sep = "... +.fi +.RE +.PP +.RB ( c2 " " a0 +is U+00A0 in UTF\-8; +.B 20 +would be a plain space instead.) +.SS "[bible] -- what a book is called" +A language file's +.I [bible] +section supplies every book's display name, one +.B full +and one +.B abbr +form per id: +.RS +.nf + +luke.full = Evangelium secundum Lucam +luke.abbr = Luc +.fi +.RE +.PP +.B \-\-sigla\-book +selects which of the two forms +.RB ( "full" " or " "abbr" ) +a citation uses; the style's own +.B book +setting is the default when neither the flag nor the config key is given. +Unlike +.IR [celebration] " (deliberately partial for a new translation, per " NAMING +above), +.I [bible] +is expected complete: a missing entry degrades to the citation data's own +built\-in spelling (the pre\-naming form), never to another language's name +via the +.B fallback +chain \(em a book name silently borrowed from the wrong language would be +worse than one left untranslated. +.SS "lang/traditions.ini -- what a book denotes" +.I lang/traditions.ini +is a second file, separate from every language file, naming +.B traditions : +sections that remap a Vulgate\-numbered book id onto the id a modern reader +would expect. The shipped file: +.RS +.nf + +[vulgate] +; identity -- deliberately empty + +[modern] +kings_3 = kings_1 +kings_4 = kings_2 +esdras_2 = nehemiah +ecclesiasticus = sirach +osee = hosea +jonas = jonah +apocalypse = revelation +.fi +.RE +.PP +.B \-\-sigla\-tradition +names a section by its header; the default, +.BR vulgate , +is shipped deliberately empty, so a citation is never renumbered unless a +tradition is chosen explicitly \(em the 1962 Missal on which this engine's +data is built is Vulgate\-numbered throughout. +.B modern +renders the Vulgate id but with the OTHER tradition's name and numbering, so +.I "3 Kings 19:3\-8" +becomes +.IR "1 Kings 19:3\-8" , +via this mapping, not via a second copy of the reading data: +.RS +.nf + +$ colitur readings 2026 \-\-lang en | grep 2026\-02\-25 +2026\-02\-25 ef\-lent\-ember\-wed | 3 Kgs. 19:3\-8 | Matt 12:38\-50 | \e +Lenten Ember Wednesday +$ colitur readings 2026 \-\-lang en \-\-sigla\-tradition modern | grep 2026\-02\-25 +2026\-02\-25 ef\-lent\-ember\-wed | 1 Kgs 19:3\-8 | Matt 12:38\-50 | \e +Lenten Ember Wednesday +.fi +.RE +.PP +An unrecognised +.B \-\-sigla\-tradition +degrades to +.B vulgate +with a warning on standard error, never a hard error \(em asking for a +renumbering is optional, unlike asking for a language: +.RS +.nf + +colitur: .../lang/traditions.ini: no tradition "bogus"; falling back to the Vulgate +.fi +.RE +.SS "--raw is byte-exact" +.B \-\-raw +does not merely reformat a citation with an identity style \(em that would +still parse it and reprint its punctuation, which is not the same as +leaving it untouched. Under +.BR \-\-raw , +every citation is emitted +.B exactly +as stored, with no parsing step at all. Two reasons this matters, both +load\-bearing: +.RS +.nf + +1. diffing this program's output against lectio (the sibling Go engine + colitur's citation data is bootstrapped from) is only meaningful + byte\-for\-byte -- a reformatted citation would show spurious diffs + even where the two engines fully agree. +2. the raw view must not depend on the citation PARSER being correct -- + if a parser bug ever mis\-renders a citation, the raw output used to + diagnose that bug must not itself have gone through the same parser. +.fi +.RE +.SS Config keys +.BR sigla_style ", " sigla_book " and " sigla_tradition +in a config file's +.B [defaults] +section are the config\-file counterpart of +.BR \-\-sigla\-style ", " \-\-sigla\-book " and " \-\-sigla\-tradition , +resolved with the identical flag > config > default precedence as +.BR lang , +and reported the same way by +.BR "colitur config \-\-show" . +See +.B COMMANDS +above for each flag's own default and error behaviour, and +.BR colitur\-config (5) +for the config file's format, location and the four settings it currently +documents in full. +.SS Sourcing discipline +.IR lang/la.ini "'s own " +.I [bible] +rows are transcribed from the 1962 Missal's own reading incipits, each +citing a scan line \(em the same discipline +.I [celebration] +already follows. Two rows are marked where that was not straightforwardly +possible, so a reader can tell a sourced name from one that is not at a +glance rather than trusting silently: +.RS +.nf + +; UNSOURCED no instance of the book's own title was found in either + scan; the entry falls back to the citation data's own + built\-in spelling (e.g. Proverbs, Song of Songs). +; CONSTRUCTED composed from two separately\-sourced parts, because their + COMBINATION does not appear verbatim in the Missal (the + two Books of Kings: the shared incipit "Lectio libri + Regum" is sourced, the volume numeral comes from the + sourced chapter:verse locator, but no scan line spells + out "Liber Regum III" as such). +.fi +.RE +.PP +An unmarked row is transcribed verbatim (case aside). This is not an +apology for incompleteness \(em it is what lets a reader trust every +.I sourced +row precisely because the unsourced ones are labelled rather than blended +in silently. .SH ENVIRONMENT .TP .B COLITUR_DATA_DIR |