path: root/man/lectio.1

.TH LECTIO 1 "2026" "lectio" "User Commands"
.SH NAME
lectio \- offline Catholic daily readings and liturgical calendar
.SH SYNOPSIS
.B lectio
.RI [ DATE ]
.RI [ flags ]
.br
.B lectio
.BR compare | show | ref | rand
.RI [ ... ]
.SH DESCRIPTION
.B lectio
computes the Catholic liturgical day and its Mass readings entirely offline,
for either the Ordinary Form (post\-1969) or the Extraordinary Form (1962), and
renders the reading text from an embedded public\-domain scripture corpus. There
is no network access: the calendar, the lectionary citations and the Latin
Vulgate text are all built into the binary.
.PP
With no arguments it prints today's gospel. A
.I DATE
in
.B YYYY-MM-DD
form (any position on the command line) selects another day.
.PP
Only the Latin Vulgate is embedded by default. The other translations \(em
.BR wuj " (Wujek), " grb " (Greek), " drb " (Douay\-Rheims) \(em"
are optional: build with
.B make build-full
or drop a
.IR <code> .tsv " and " <code> .ini
into
.IR ~/.config/lectio/corpora/ .
A version that is not present renders as
.RB \(dq (not\ in\ <code>) \(dq.
.SH OPTIONS
.TP
.BR \-a ", " \-\-all
Show all readings, not just the gospel.
.TP
.BR \-b ", " \-\-bible " " \fIVER\fR
Render one version's text (\fBvul\fR built in; see above for the rest).
.TP
.BR \-c ", " \-\-compare " " \fILIST\fR
Show several versions side by side (comma\-separated codes).
.TP
.BR \-p ", " \-\-ref " " \fIREF\fR
Look up a passage (e.g. \(dqJ 3:16\(dq) with \fB\-b\fR/\fB\-c\fR.
.TP
.BR \-r ", " \-\-raw
Text only, no banner or headings (for piping).
.TP
.BR \-w ", " \-\-width " " \fIN\fR
Wrap width; 0 detects the terminal.
.TP
.BR \-l ", " \-\-lectionary " " \fIWHICH\fR
.BR new " | " trad
(traditional selects the 1962 Extraordinary Form).
.TP
.B \-\-ui\-lang \fILANG\fR
Language of the day and saint names (and interface labels): any code
(\fBen\fR, \fBpl\fR, \(en). Day names come from
.IR ~/.config/lectio/names/<code>.ini ,
interface labels from
.IR ui/<code>.ini ;
English and Polish are built in.
.TP
.BR \-P ", " \-\-pager
Page the reading output; the default comes from config.
.TP
.B \-\-no\-pager
Never page, even if config enables one.
.TP
.B \-\-year \fIYYYY\fR
Print the year's key liturgical dates \(em season boundaries, solemnities and
feasts of the Lord \(em paged when a pager is configured. Combined with
.B \-\-format
it emits the whole year's machine calendar instead.
.TP
.BR \-L ", " \-\-liturgy
Print the computed liturgical day (identity, rank, colour) and exit.
.TP
.B \-\-list
List every book and its abbreviations in the current sigla dialect.
.TP
.B \-\-citation
Print today's gospel reference and exit (for scripts and cron).
.TP
.B \-\-week
List the coming week's gospel references and exit.
.TP
.B \-\-cal\-new \fINAME\fR
Scaffold a small custom calendar layer at
.IR ~/.config/lectio/calendars/NAME.ini .
.TP
.B \-\-cal\-dump \fINAME\fR
Dump the whole universal calendar to
.IR ~/.config/lectio/calendars/NAME.ini ,
every celebration commented out. Uncomment one day and edit a field to override
it. Respects
.BR \-l / \-\-lectionary
(dump the 1962 form with
.BR "\-l trad" ).
Refuses to overwrite an existing file.
.TP
.B \-\-cal\-check \fINAME\fR
Validate a custom calendar layer and exit.
.TP
.B \-\-corpus\-check \fIX\fR
Validate a bible corpus (a code, or a path to a \fI<code>.tsv\fR) and exit;
errors fail, coverage gaps warn. Add \fB\-\-json\fR for a JSON report.
.TP
.BR \-\-rand ", " \-\-rand\-v ", " \-\-rand\-ch
Print a random verse, or a random chapter, and exit.
.TP
.BR \-\-md ", " \-\-pdf ", " \-\-out " " \fIFILE\fR
Export the readings as Markdown or PDF (to \fB\-\-out\fR or stdout).
.TP
.B \-\-calendar \fIYYYY-MM\fR
Export the month as a printable A4 PDF calendar (with \fB\-\-out\fR).
.TP
.B \-\-format \fIWHICH\fR
.BR json " | " ical :
emit the computed calendar and exit. Combine with
.BR \-\-from / \-\-to " or " \-\-year " to pick a range, and " \-\-form " to override the form."
.TP
.BR \-v ", " \-\-version
Print the version and exit.
.TP
.BR \-h ", " \-\-help
Print a short help summary and exit.
.SH FILES
.TP
.I ~/.config/lectio/config.ini
Main configuration (auto\-seeded, self\-documenting).
.TP
.I ~/.config/lectio/corpora/
Drop\-in bible corpora (\fI<code>.tsv\fR + \fI<code>.ini\fR).
.TP
.I ~/.config/lectio/names/<code>.ini
Localised temporal day names for \fBui_language = <code>\fR.
.TP
.I ~/.config/lectio/ui/<code>.ini
Localised interface labels for \fBui_language = <code>\fR.
.TP
.I ~/.config/lectio/calendars/
Custom calendar layers, stacked over the universal calendar via
.B use
in config (field\-level add / override / suppress). Generate a fully\-commented
template of every universal celebration here with
.BR "\-\-cal\-dump NAME" ,
then uncomment and edit a day to change it.
.TP
.I ~/.config/lectio/sanctorale/of.ini
.TQ
.I ~/.config/lectio/sanctorale/ef.ini
Optional external universal sanctorale that REPLACES the embedded one for that
form (a missing or malformed file falls back to the embedded default).
.SH EXAMPLES
.PP
Today's gospel:
.PP
.RS
.B lectio
.RE
.PP
All of a day's readings in the Vulgate:
.PP
.RS
.B lectio 2026\-07\-22 \-a \-b vul
.RE
.PP
The year's key dates:
.PP
.RS
.B lectio \-\-year 2026
.RE
.PP
Change one day's celebration \(em dump the calendar, uncomment and edit the
entry, enable it:
.PP
.RS
.nf
lectio \-\-cal\-dump mine
$EDITOR ~/.config/lectio/calendars/mine.ini
echo 'use = mine' >> ~/.config/lectio/config.ini
.fi
.RE
.SH EXIT STATUS
.TP
.B 0
Success.
.TP
.B 1
Runtime error.
.TP
.B 2
Usage error (bad flag, date, version or lectionary).
.SH SEE ALSO
.BR lectio-ui (1),
.BR lectio-web (1)
.SH LICENSE
AGPL\-3.0\-or\-later. The bible corpora are separate public\-domain scripture
texts, not covered by that licence (see the NOTICE file).