diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 118 |
1 files changed, 47 insertions, 71 deletions
@@ -1,15 +1,16 @@ # lectio `lectio` is a self-contained Go rewrite of the Python `daily-reading` tool -(`ewangelia.py`). It fetches the day's Catholic liturgical readings and -shows them across five scripture versions with correct psalm -versification, and can run entirely offline once a date has been -harvested. There are no external tool dependencies at runtime, and no -network dependency at all in offline mode. +(`ewangelia.py`). It **computes** the day's Catholic liturgical calendar and +readings entirely offline — Ordinary Form (modern) or Extraordinary Form +(1962) — and shows the text across four public-domain scripture corpora with +correct psalm versification. There is no network dependency at all: the +calendar, the lectionary citations, and the scripture corpora are all +embedded in the binary. Three binaries share the same config and reading pipeline: -- **`lectio`** — subcommand CLI (`today`, `date`, `show`, `compare`, `update`) +- **`lectio`** — the CLI (daily readings, version compare, passage lookup, calendar export) - **`lectio-ui`** — a colored, scrollable Bubble Tea terminal reader - **`lectio-web`** — a local HTMX browser UI (bundled, no CDN — works offline) @@ -41,26 +42,20 @@ lectio --version | -v lectio help | -h | lectio <cmd> -h ``` -Versions: `bt` (Biblia Tysiąclecia, niedziela.pl), `wuj` (Wujek), `vul` (Wulgata), +Versions (all embedded, public-domain): `wuj` (Wujek), `vul` (Wulgata), `grb` (Grecki), `drb` (Douay-Rheims). -Global flags (any subcommand, any position): +Flags: -- `--offline` — skip the network, use cached/harvested data only - `--lectionary new|traditional` — override config `lectionary` for this run -- `--lang pl|en` — override config `traditional_lang` for this run - -Per-command flags: - +- `--ui-lang pl|en` — override the interface/citation language for this run - `--all` — show every reading part (1st/2nd reading, psalm, acclamation, gospel); default is the gospel only, unless config `all = true` - `--raw` — omit the banner/headings (for piping) - `--width N` — wrap width; `0` detects the terminal width, else falls back to 80 (120 for `compare`) -- `--refresh` — bypass the cache and re-fetch -- `--date D` — date as `YYYY-MM-DD` (`show`/`compare` only; default: today) -Exit codes: `0` ok, `1` runtime error (fetch/parse), `2` usage error. +Exit codes: `0` ok, `1` runtime error, `2` usage error. ### Subcommands @@ -88,16 +83,7 @@ lectio show wuj --date 2026-12-25 falls back to config `versions` if omitted): ```sh -lectio compare bt,wuj,drb --date 2026-04-05 -``` - -`update [--days N] [--from D]` — harvest future dates' scripture -citations into the offline sigla store (see "Offline mode" below); does -not respect `--lectionary`/`--offline`, it always harvests the modern -(niedziela.pl) lectionary: - -```sh -lectio update --days 30 +lectio compare wuj,drb --date 2026-04-05 ``` ### Calendar API — JSON & iCal @@ -136,15 +122,14 @@ A full-day, scrollable, colored view built on Bubble Tea. Key bindings: | `j`/`↓`, `k`/`↑` | scroll down/up one line | | `space` / `b` | page down/up | | `g` / `G` | jump to top/bottom | -| `r` | refresh (re-fetch the current date) | | `q` / `ctrl+c` | quit | Colors are a fixed light/dark-adaptive palette (Catppuccin-style, not configurable per instance): the heading is accented, the citation line is -faint, verse numbers are muted, verse/paragraph text is the default -foreground, a psalm's refrain line is italic, and the header/footer bars -use an inverted background. Colors degrade automatically to plain text -when `NO_COLOR` is set or the terminal doesn't support them. +faint, verse numbers are muted, verse text is the default foreground, and +the header/footer bars use an inverted background. Colors degrade +automatically to plain text when `NO_COLOR` is set or the terminal doesn't +support them. ## `lectio-web` — the browser UI @@ -167,7 +152,7 @@ Page controls: - **Date navigation** — a date picker plus `←`/`→` buttons - **Lekcjonarz (lectionary)** — new vs traditional, same as `--lectionary` -- **Version checkboxes** — bt/wuj/vul/grb/drb, independent of any one +- **Version checkboxes** — wuj/vul/grb/drb, independent of any one visitor's config - **Zakres (all-parts toggle)** — gospel-only vs every part, same as `--all` - **Układ (display mode)** — horizontal / vertical / interlinear, see below @@ -181,9 +166,7 @@ Page controls: - **vertical** — the same per-version text laid out as side-by-side columns, like the CLI's `compare` - **interlinear** — every version interleaved verse-by-verse by - chapter:verse. `bt` cannot participate (niedziela.pl prose carries no - verse numbers), so it is silently substituted with `wuj` (dropped - entirely if `wuj` is already selected) + chapter:verse ## Configuration @@ -193,13 +176,12 @@ set. An invalid file falls back to defaults with a warning on stderr. ```toml schema_version = 1 -lectionary = "new" # "new" (niedziela.pl) or "traditional" (missalemeum, 1962) -traditional_lang = "pl" # vernacular for traditional propers: "pl" or "en" -versions = ["bt", "wuj", "vul", "grb", "drb"] # compare set + TUI cycle order -default_version = "bt" # TUI start / `lectio show` default +lectionary = "new" # "new" (Ordinary Form) or "traditional" (Extraordinary Form, 1962) +versions = ["wuj", "vul", "grb", "drb"] # compare set + TUI cycle order +default_version = "vul" # TUI start / `lectio show` default width = 0 # CLI wrap width; 0 = detect terminal all = false # default to all parts (true) or just the gospel (false) -offline = false # true = never fetch; read only harvested sigla + cache +reading_version = "" # force a reading corpus (e.g. "wuj", "drb"); blank = auto/Latin web_theme = "transfiguration" # built-in order/season theme or a user theme in ~/.config/lectio/themes/ web_port = 0 # lectio-web port; 0 = try 1099, then any free port web_display = "horizontal" # lectio-web layout: "horizontal" (stacked), "vertical" (columns), "interlinear" (verse-by-verse) @@ -227,7 +209,7 @@ web_display = "horizontal" # lectio-web layout: "horizontal" (stacked), "v # postcommunio = true # Postcommunion ``` -CLI flags (`--offline`, `--lectionary`, `--lang`) and `lectio-web` query +CLI flags (`--lectionary`, `--ui-lang`, `--all`, …) and `lectio-web` query parameters override the corresponding config values for that run/request only; the file itself is never rewritten. @@ -268,42 +250,36 @@ full list and a template) at: Restart (or reload) `lectio-web`; `<yourname>` appears in the theme list and overrides any built-in theme of the same name. -## Offline mode and `lectio update` +## Offline by design -Two data stores back offline use, both outside the config file: +Everything ships in the binary — there is no cache, no harvest step, and no +network access. For any date, `lectio` computes the liturgical day (season, +precedence, calendar of saints) and resolves its reading citations from the +embedded lectionary tables, then renders the verse text from an embedded +scripture corpus. Reading citations are stored in English-canonical form; the +Psalms are renumbered per corpus (Hebrew→Vulgate for `wuj`/`vul`/`grb`, kept +modern for `drb`), and the citation shown in the heading is formatted in your +sigla dialect (`sigla_style` / `ui_language`). -- **Cache** (`~/.cache/lectio/`) — parsed HTML/JSON of dates already - fetched normally; used automatically before hitting the network. -- **Sigla store** (`~/.local/share/lectio/sigla.tsv`) — just the - section labels and scripture citations (no reading text) for dates - harvested by `lectio update`. +The reading text comes from the configured `reading_version` (else the corpus +that matches your language, else the complete Latin Vulgate). Where the chosen +corpus lacks a passage, the `-L`/liturgy view falls back to the Latin Vulgate, +which carries the full canon. -Workflow: while online, run - -```sh -lectio update --days 30 -``` - -to walk forward from today (or `--from D`) harvesting citations into the -sigla TSV, stopping at niedziela.pl's unpublished horizon (or after -`--days N` days; `0`, the default, means "until unpublished"). Later, -with `offline = true` in config (or `--offline` on any command), reads -come only from the cache/sigla store, never the network — and since the -sigla store holds no `bt` text, `bt` is transparently substituted with -`wuj` wherever a version list would otherwise include it (CLI, TUI, and -`lectio-web`'s interlinear mode all apply this the same way). - -Offline mode currently only supports the "new" (modern) lectionary — -`lectionary = traditional` combined with offline is rejected with an -error, since traditional propers aren't harvested by `update`. +> The modern Polish text (Biblia Tysiąclecia) is copyrighted and cannot be +> embedded; the public-domain Polish corpus is Wujek (`wuj`), which is +> ~16th-century and incomplete. Set `reading_version = "wuj"` for Polish text, +> or keep the default Latin Vulgate for a complete, consistent reading. ## Lectionaries -- **new** (default) — scrapes the modern Polish lectionary from - `niezbednik.niedziela.pl`, one page per day. -- **traditional** — the 1962 Roman Missal's propers of the day, fetched - from the `missalemeum.com` JSON API in either Polish or English - (`traditional_lang` / `--lang`; no other language is supported). +Both are computed offline from the embedded calendar engine and lectionary +data — no external service: + +- **new** (default) — the Ordinary Form (post-1969) calendar and lectionary, + with the 3-year Sunday cycle (A/B/C) and 2-year weekday cycle (I/II). +- **traditional** — the Extraordinary Form (1962 Roman Missal): the temporal + and sanctoral of the day with its epistle and gospel. Switch per run with `--lectionary new|traditional`, or set `lectionary` in config for a permanent default. |