From d17262c10fc24557741a5b571f40dfd9625fdb2e Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Wed, 29 Jul 2026 10:06:24 +0200 Subject: feat: man page (clectio.1), installed by make install Add a manual page covering usage, the -a/-g and --month options, the compile- time config.h settings (FORM/SIGLA/COLOR/GOSPEL_ONLY/WRAP), and both the bring-your-own-Bible and bring-your-own-calendar workflows, matching the README. Install it via make (MANPREFIX = $PREFIX/share/man); uninstall removes it too. Renders clean under man --warnings. Claude-Session: https://claude.ai/code/session_01S1CD1u3tgSS4xNu6WHfp5a --- Makefile | 5 +- README.md | 3 +- clectio.1 | 156 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 162 insertions(+), 2 deletions(-) create mode 100644 clectio.1 diff --git a/Makefile b/Makefile index c22556a..f114488 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,8 @@ CFLAGS = -std=c99 -Os -Wall -Wextra # string-table pointers in at link time instead of emitting ~57 KB of runtime # relocations -- a ~6% smaller binary for free. LDFLAGS = -s -no-pie -PREFIX = /usr/local +PREFIX = /usr/local +MANPREFIX = $(PREFIX)/share/man # The form to build is read from config.h so there is one source of truth. FORM := $(shell grep -Eq '^[[:space:]]*\#[[:space:]]*define[[:space:]]+FORM_EF' config.h 2>/dev/null && echo ef || echo of) @@ -53,9 +54,11 @@ size: clectio install: clectio install -Dm755 clectio $(DESTDIR)$(PREFIX)/bin/clectio + install -Dm644 clectio.1 $(DESTDIR)$(MANPREFIX)/man1/clectio.1 uninstall: rm -f $(DESTDIR)$(PREFIX)/bin/clectio + rm -f $(DESTDIR)$(MANPREFIX)/man1/clectio.1 clean: rm -f clectio mktext bin2h text.lz.h gen/verses_of.keys gen/verses_ef.keys diff --git a/README.md b/README.md index 8f6c678..5429ea0 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ the Go engine that computes and generates clectio's data. ./clectio -a # all readings (override a Gospel-only build) ./clectio --month # this month at a glance (day, colour, celebration) ./clectio --month 2026-04 > apr.txt # a month to a file for reference - make install # into $PREFIX/bin (default /usr/local) + make install # binary into $PREFIX/bin, man page into $PREFIX/share/man Needs only a C99 compiler and libc. It builds in about a second. @@ -184,6 +184,7 @@ guessed. To extend the range, regenerate `gen/` with lectio's `clectio-gen` 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 + clectio.1 the manual page (installed by make install) gen/ generated, corpus-independent data (calendar + citations) text_of.lz the default Vulgate text, DEFLATE-packed (one per form) diff --git a/clectio.1 b/clectio.1 new file mode 100644 index 0000000..1083630 --- /dev/null +++ b/clectio.1 @@ -0,0 +1,156 @@ +.TH CLECTIO 1 "2026" "clectio" "User Commands" +.SH NAME +clectio \- tiny, fast, offline Catholic daily readings +.SH SYNOPSIS +.B clectio +.RB [ \-a | \-g ] +.RI [ YYYY\-MM\-DD ] +.br +.B clectio \-\-month +.RI [ YYYY\-MM " | " N ] +.SH DESCRIPTION +.B clectio +prints the Catholic liturgical day and its Mass readings for a date, entirely +offline. It computes nothing at run time: the calendar, the reading citations +and the scripture text are all compiled into the binary, so a date is a table +lookup. With no date it prints today. +.PP +One liturgical form, citation dialect and scripture text are built into a given +binary; all of that is compile\-time configuration (see +.BR CONFIGURATION ). +The default text is the public\-domain Latin Vulgate. The compiled calendar +covers 2025\-2054; a date outside that range is reported, not guessed. +.SH OPTIONS +.TP +.BR \-a ", " \-\-all +Print all of the day's readings, overriding the compiled default. +.TP +.BR \-g ", " \-\-gospel +Print only the Gospel, overriding the compiled default. +.TP +.B \-\-month +List a whole month, one line per day: weekday, day, liturgical colour and +celebration (no readings). Takes an optional +.I YYYY\-MM +or a bare month number +.RI ( N , +in the current year); with no argument, the current month. Useful piped to a +file as a reference. +.TP +.BR \-h ", " \-\-help +Print usage and the compiled configuration, and exit. +.SH CONFIGURATION +There is no run\-time configuration file. Options are set at compile time in +.IR config.h , +copied from +.I config.def.h +on first build \(em edit it, then run +.BR make . +.TP +.BR FORM_OF " / " FORM_EF +Ordinary Form (post\-1969) or Extraordinary Form (1962). Enable exactly one. +.TP +.BR SIGLA_ENGLISH " / " SIGLA_LATIN +Citation dialect: \(dqJer 14\(dq versus \(dqIer 14\(dq. Enable exactly one. +.TP +.B COLOR +Colour the day name with its liturgical colour on a terminal (1 on, 0 off). +.TP +.B GOSPEL_ONLY +Default reading set: all readings (0) or the Gospel only (1). Override per run +with +.BR \-a / \-g . +.TP +.B WRAP +Wrap reading text at N columns; +.B 0 +fits the terminal, and leaves piped output one line per verse. +.PP +One form per binary; build twice for both. The interface is English only. +.SH BRING YOUR OWN BIBLE +The default build embeds the Latin Vulgate. To build with another translation, +pass a corpus \(em a six\-column TSV +.RB ( Book ", " Abbrev ", " BookNum ", " Chapter ", " Verse ", " Text , +in Vulgate chapter/verse numbering) \(em to +.BR make : +.PP +.RS +.B make CORPUS=/path/to/bible.tsv +.RE +.PP +clectio matches a citation on Book+Chapter+Verse and prints Text; Abbrev and +BookNum are ignored, but the columns must be present. A verse the corpus lacks +prints blank; it never fails the day. See the README for the full format, an +example, and how to switch back. +.SH BRING YOUR OWN CALENDAR +Out of the box the calendar is the universal Roman calendar, compiled in. It can +be changed in two tiers, because clectio has no calendar engine. +.PP +.B Minor \(em name and colour of a fixed date, standalone. +Edit +.I calendar.h +(copied from +.IR calendar.def.h ), +add a +.B { month, day, colour, "name" } +row, and +.BR make . +It replaces that fixed date's name and colour every year, in both the single\-day +and +.B \-\-month +output. It cannot change a day's readings or rank, place movable feasts, or +arbitrate precedence \(em an override wins unconditionally. +.PP +.B Full \(em readings, ranks, movable feasts, via lectio. +Describe the change as a +.BR lectio (1) +calendar layer +.RB ( "lectio \-\-cal\-dump" ), +then regenerate clectio's tables with it applied and recompile \(em from the +lectio source tree: +.PP +.RS +.nf +go run ./cmd/clectio\-gen \-caldir DIR \-use NAME new 2025 2054 gen/ +make CORPUS=.../vul.tsv +.fi +.RE +.PP +The running binary stays standalone; only regenerating needs lectio and a Go +toolchain. See the README for the full workflow and a revert note. +.SH FILES +.TP +.I config.def.h +Template for the compile\-time configuration; copied to +.I config.h +on first build. +.TP +.I calendar.def.h +Template for local calendar overrides; copied to +.IR calendar.h . +.TP +.I gen/ +Generated, corpus\-independent tables (calendar, citations, verse keys). +.TP +.IR text_of.lz ", " text_ef.lz +The packed scripture text for each form (default: the Latin Vulgate). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +The date is outside the compiled range. +.TP +.B 2 +Usage error (bad option, date or month). +.SH SEE ALSO +.BR lectio (1) +.PP +The full manual \(em corpus format, calendar customization, sizing \(em is the +project README. +.SH LICENSE +ISC (clectio's own code). The compiled scripture text is a separate work under +its own terms; the default Latin Vulgate is public domain. +.SH AUTHOR +Łukasz Kasprzak. -- cgit v1.3