From d0bcdc3f3912a4e746fe12050e8062b3679124aa Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Wed, 29 Jul 2026 09:13:38 +0200 Subject: docs: fully document the bring-your-own-Bible corpus format Expand "Bring your own Bible" with the details a user needs to actually do it: - the six-column TSV format with three real, tab-marked example rows and a column legend; - which columns are load-bearing -- clectio matches on Book+Chapter+Verse (cols 1,4,5) and prints col 6; Abbrev/BookNum (cols 2,3) are ignored but must be present; - the Vulgate-versification requirement made explicit (a differently numbered Bible misaligns), with the "start from vul.tsv, swap the text column" tip; - pointer to the four ready corpora shipped with lectio, with a runnable drb example; - a "switching back to the Vulgate" note (the git-tracked text_*.lz blob is overwritten by a CORPUS= build). Docs only; no code change. Claude-Session: https://claude.ai/code/session_01S1CD1u3tgSS4xNu6WHfp5a --- README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 51 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index eb763e2..0de5efe 100644 --- a/README.md +++ b/README.md @@ -45,17 +45,59 @@ One form per binary; for both, build twice. The interface is English only. ## Bring your own Bible -The default build embeds the Latin Vulgate. To compile with another -translation, hand `make` a corpus in the same 6-column TSV format -(`BookAbbrevBookNumChapterVerseText`), using Vulgate -chapter/verse numbering: +The default build embeds the Latin **Vulgate**. clectio compiles in only the +~12,000 verses the lectionary actually cites (never a whole Bible), so it stays +well under 1 MiB with any text. To build with a different translation, point +`make` at a corpus and it repacks exactly those verses from it: - make CORPUS=/path/to/mybible.tsv + make CC=gcc CORPUS=/path/to/mybible.tsv -clectio compiles in only the ~12000 verses the lectionary actually cites, so the -binary stays well under 1 MiB whatever the Bible. A verse the corpus lacks prints -blank; it never fails the day. (The default build needs only a compiler; a -`CORPUS=` rebuild also needs `gzip`, which `mktext` uses to pack the text.) +You already have four corpora in the required format: lectio ships them under +`internal/bible/` — Vulgate (`vul`), Douay-Rheims (`drb`), Wujek (`wuj`) and +Greek (`grb`). For an English build: + + make CC=gcc CORPUS=~/git/projects/lectio/internal/bible/corpora_optional/drb.tsv + +### Corpus format + +A plain UTF-8 file, **six columns separated by a single TAB, one verse per +line**. These three real rows show the shape (arrows mark the tabs): + + Genesis → Ge → 1 → 1 → 1 → In the beginning God created heaven, and earth. + John → John → 43 → 20 → 1 → AND on the first day of the week, Mary Magdalen … + 1 John → 1Jn → 62 → 5 → 11 → And this is the testimony, that God hath given … + + column: 1 Book 2 Abbrev 3 BookNum 4 Chapter 5 Verse 6 Text + +clectio matches a citation to a row on **Book + Chapter + Verse** (columns 1, 4, +5) and prints column 6. What that means for your file: + + * **Book (col 1)** must be the full name the calendar's keys use — e.g. + `1 John`, `Song of Songs`, `Numbers`, not `1Jn` or `Cant`. Copy the exact + spellings from any shipped `*.tsv` (the safest start is to take `vul.tsv` and + replace only the text column). + * **Chapter and Verse (cols 4, 5)** must follow **Vulgate numbering** — the + versification the lectionary is keyed to. A Bible numbered differently + (modern Psalm numbers, split or renamed books) will silently misalign, so a + translation not already Vulgate-numbered has to be re-numbered first. + * **Abbrev (col 2) and BookNum (col 3)** are ignored by clectio, but the + columns must still be present so every line has six fields (a line with fewer + is skipped). + * **Text (col 6)** is the verse; runs of whitespace are collapsed to one space. + +A verse the corpus does not contain prints blank — it never fails the day; the +build just warns how many verses were missing. The default Vulgate build needs +only a C compiler; a `CORPUS=` rebuild also needs `gzip` (which `mktext` uses to +pack the text). + +### Switching back to the Vulgate + +The shipped `text_of.lz` / `text_ef.lz` hold the packed Vulgate text and are +git-tracked; a `CORPUS=` build overwrites the one for the form you built. To +restore it: + + git checkout text_of.lz # or text_ef.lz for an EF build + make CC=gcc clean && make CC=gcc ## Coverage -- cgit v1.3