From 2468224d0aaacd8b0e7478af55142bcd831d2b77 Mon Sep 17 00:00:00 2001
From: Lukasz Kasprzak <lukas@labunix.xyz>
Date: Wed, 29 Jul 2026 09:55:22 +0200
Subject: feat: standalone calendar overrides (calendar.h) + document
 customization

Add a compile-time override table for MINOR local calendar changes, standalone
(no lectio, no toolchain): edit calendar.h (copied from calendar.def.h), add a
{ month, day, colour, "name" } row, make. It replaces a fixed date's name and
colour, every year, in both single-day and --month output. Limits (no engine):
fixed dates only; name/colour only, not readings or rank/precedence; an override
wins unconditionally.

README gains a "Customize the calendar" section documenting both tiers with
their limits: the standalone override above, and -- for readings, ranks and
movable feasts -- regenerating gen/ from a lectio calendar layer via
clectio-gen (-caldir/-use), then rebuilding with CORPUS= to repack any newly
cited verses, with a git-checkout revert note.

Both forms build clean under -Wall -Wextra; binary unchanged at 666 KB; default
(empty override table) output is unchanged.

Claude-Session: https://claude.ai/code/session_01S1CD1u3tgSS4xNu6WHfp5a
---
 README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 0de5efe..162f6c3 100644
--- a/README.md
+++ b/README.md
@@ -104,10 +104,81 @@ restore it:
 The compiled calendar runs 2025–2054. Dates outside that range are reported, not
 guessed. To extend it, regenerate `gen/` with lectio's `clectio-gen`.
 
+## Customize the calendar
+
+clectio has **no calendar engine** — it looks the calendar up in a compiled
+table, it doesn't compute one. That sets the limits below. There are two ways to
+change what it shows, sized to how much you need.
+
+### Minor: name + colour of a fixed date — standalone, in `calendar.h`
+
+For a local **name and colour** on a **fixed date** (a diocesan patron, a
+national memorial, a renaming), edit `calendar.h` — same suckless flow as
+`config.h`: it is copied from `calendar.def.h` on first build; edit it and
+`make`. No lectio, no toolchain.
+
+    static const Override overrides[] = {
+        { 5, 16, RED,   "Saint Andrew Bobola, priest and martyr" },
+        { 8, 15, WHITE, "Assumption of Our Lady, Patroness" },
+        { 0, 0, 0, 0 }   /* keep this row last */
+    };
+
+Fields are `{ month, day, colour, "name" }`; colours are `GREEN WHITE RED VIOLET
+ROSE BLACK`. Overrides apply to both the single-day and `--month` output, every
+year.
+
+**Limits** (all because there is no engine):
+- **fixed dates only** — no movable / computed feasts;
+- changes the **name and colour only**, not a day's **readings** or its
+  **rank / precedence** (the table stores neither). The readings shown stay the
+  underlying day's — which is correct for a memorial, since it uses the weekday
+  readings;
+- an override **wins unconditionally**, so only override a date whose
+  celebration you truly mean to replace.
+
+### Full: readings, ranks, movable feasts — via lectio, then recompile
+
+Anything the engine must compute — **proper readings, a changed rank, a movable
+feast** — is done in **lectio** (its Go engine is where clectio's tables come
+from) and baked back into `gen/`. The *running* clectio stays standalone; only
+*regenerating* needs lectio and a Go toolchain.
+
+1. Describe the change as a lectio **calendar layer** (see lectio's README,
+   "Calendar of saints"). A layer entry can set `rank`, `colour`,
+   `name.<lang>`, and `reading.first|psalm|second|acclamation|gospel`:
+
+        lectio --cal-dump mine        # writes ~/.config/lectio/calendars/mine.ini
+        $EDITOR ~/.config/lectio/calendars/mine.ini
+        lectio --cal-check mine
+
+2. Regenerate clectio's tables **with that layer applied** (`old` for the EF):
+
+        cd ~/git/projects/lectio
+        go run ./cmd/clectio-gen -caldir ~/.config/lectio/calendars -use mine \
+            new 2025 2054 ~/git/projects/clectio/gen/
+
+   (`-sanctorale DIR` instead applies a full `of.ini`/`ef.ini` replacement. The
+   book table stays embedded, so a stale `books.ini` can't affect the result.
+   The 30-year range takes roughly a minute.)
+
+3. Rebuild clectio, **repacking the text** so any newly-cited verses are
+   included:
+
+        cd ~/git/projects/clectio
+        make CC=gcc clean
+        make CC=gcc CORPUS=~/git/projects/lectio/internal/bible/corpora/vul.tsv
+
+   (A change that cites only already-embedded verses would build without
+   `CORPUS=`, but repacking is the safe default.)
+
+To undo it and return to the shipped calendar: `git checkout gen/ text_of.lz`
+(or `text_ef.lz`) and rebuild.
+
 ## Files
 
     clectio.c        the program: date -> table lookup -> print
     config.def.h     compile-time configuration
+    calendar.def.h   local calendar overrides (name + colour by fixed date)
     puff.c/.h        DEFLATE decompressor (Mark Adler's puff, public domain)
     mktext.c         build tool: resolve verse keys against a corpus, gzip-pack the text
     bin2h.c          build tool: embed the packed text as C
-- 
cgit v1.3