1.\" bibel(1) - Bible verse CLI/TUI utility
  2.\" 
  3.\" bibel - Display daily Bible readings with date-based progression
  4.\" 
  5.\" European Union Public Licence 1.2
  6.\" 
  7.TH BIBEL 1 "April 2026" "bibel 1.0" "User Commands"
  8.SH NAME
  9bibel \- display today's Bible reading based on date progression
 10.SH SYNOPSIS
 11.B bibel
 12.RI [ options ]
 13.SH DESCRIPTION
 14.B bibel
 15is a command line interface (CLI) and terminal user interface (TUI) utility for
 16displaying Bible verses. Its primary purpose is as a MOTD-like program to be shown
 17on system boot, displaying today's Bible reading based on the current date.
 18.PP
 19The program reads 12 verses per day from the four Gospels (Matthew, Mark, Luke,
 20John), with a yearly progression that restarts on 1 January. It supports
 21multiple output modes including an interactive TUI with progress bars,
 22formatted ANSI-coloured text, and plain text output.
 23.PP
 24The program calculates Easter dates using either Eastern Orthodox (Meeus Julian
 25algorithm) or Roman Catholic (Delambre and Butcher's algorithm) methods.
 26.SH OPTIONS
 27.TP
 28.BI \-r " reading" , " \-\-reading=" reading
 29Reading mode. Must be one of:
 30.RS
 31.IP \fIevangelion\fR 15
 32Four Gospels (Matthew, Mark, Luke, John). Books 40-43. This is the default.
 33.IP \fInew_testament\fR
 34Entire New Testament. Books 40-66 (Matthew through Revelation).
 35.IP \fIold_testament\fR
 36Entire Old Testament. Books 1-39 (Genesis through Malachi).
 37.IP \fIbible\fR
 38Entire Bible. Books 1-66.
 39.RE
 40.TP
 41.BR \-p , " \-\-plain"
 42Output plain text without formatting or TUI. Prints header followed by verse text.
 43.TP
 44.BR \-f , " \-\-formatted"
 45Output formatted text with ANSI colours. Uses colours set by terminal emulator.
 46.TP
 47.BI \-c " path" , " \-\-config=" path
 48Path to configuration file. Defaults to
 49.IR $XDG_CONFIG_HOME/bibel/config.toml
 50(~/.config/bibel/config.toml).
 51.TP
 52.BR \-n , " \-\-numbered"
 53Print each verse on a numbered line corresponding to the verse number.
 54.TP
 55.BR \-g , " \-\-paragraphs"
 56Render pilcrows (¶) found in source JSON Bible file as paragraph breaks with
 57blank lines instead of ignoring them.
 58.TP
 59.BR \-l , " \-\-latin"
 60Use Roman Catholic Easter calculation instead of Eastern Orthodox for the TUI
 61progress bar.
 62.TP
 63.B \-\-generate\-config
 64Generate a default configuration file and exit. File is created at the default
 65configuration path.
 66.TP
 67.BR \-v , " \-\-verbose"
 68Print additional runtime information to STDOUT, including configuration paths,
 69Bible file loading status, and position calculations.
 70.TP
 71.BR \-h , " \-\-help"
 72Display help message and exit.
 73.SH CONFIGURATION
 74.B bibel
 75reads configuration from a TOML file located at
 76.IR $XDG_CONFIG_HOME/bibel/config.toml .
 77Command line arguments override configuration file settings.
 78.PP
 79The configuration file has the following structure:
 80.PP
 81.nf
 82.RS
 83# Output mode: "tui" (interactive terminal UI), "formatted" (ANSI-coloured text),
 84# or "plain" (plain text without formatting)
 85output_mode = "tui"
 86
 87# Path to Bible data file (relative to executable or absolute path). If empty,
 88# automatically uses first JSON file found in $XDG_DATA_HOME/bibel
 89bible_path = ""
 90
 91# Reading mode: "evangelion" (four Gospels), "new_testament", "old_testament", "bible"
 92reading_mode = "evangelion"
 93
 94[tui]
 95  # Whether to show the quit message "Press q to quit..."
 96  show_quit_message = true
 97  
 98  # Box border style: "rounded", "double", "single", or "hidden"
 99  border_style = "rounded"
100
101[formatter]
102  # Whether to use ANSI colours in formatted output mode
103  use_colours = true
104  
105  # Header format template
106  # Available variables: {book}, {chapter}, {first_verse}, {second_verse}
107  header_format = "{book} {chapter}\\nw. {first_verse}-{second_verse}"
108  
109  # Whether to print each verse on a numbered line with verse number
110  numbered = false
111  
112  # Whether to render pilcrows (¶) as blank lines instead of ignoring them
113  paragraphs = false
114
115[date_progression]
116  # Number of verses to read per day
117  verses_per_day = 12
118  
119  # Start date for yearly progression (format: "1 January")
120  # Empty means 1 January of current year
121  start_date = ""
122
123# Easter type: "orthodox" (default) or "latin" (i.e., roman catholic)
124easter_type = "orthodox"
125.RE
126.fi
127.PP
128To generate a default configuration file, run:
129.PP
130.RS
131.B bibel \-\-generate\-config
132.RE
133.SH ALGORITHM
134.B bibel
135uses a date-based algorithm to determine daily readings:
136.IP 1. 4
137Calculate day of year (1-366 for non-leap years, 1-367 for leap years)
138.IP 2. 4
139Compute verse offset: \fIoffset = (day_of_year - 1) × verses_per_day\fR
140(default verses_per_day = 12)
141.IP 3. 4
142Apply modulo with total verses in selected reading mode to cycle yearly.
143For evangelion mode: total verses = 3779
144.IP 4. 4
145Walk through books in selected range to find corresponding verses
146.IP 5. 4
147Apply lookahead rule: if less than \fIverses_per_day\fR verses remain in chapter
148after current snippet, extend to end of chapter
149.PP
150Book ranges for reading modes:
151.TS
152tab(;) allbox;
153l l l.
154Reading Mode;Start Book;End Book
155evangelion;40 (Matthew);43 (John)
156new_testament;40 (Matthew);66 (Revelation)
157old_testament;1 (Genesis);39 (Malachi)
158bible;1 (Genesis);66 (Revelation)
159.TE
160.SH JSON SCHEMA
161.PP
162The Bible data file used by \fBbibel\fR must be a JSON file following a specific
163schema designed for efficient, deterministic processing. The schema is used by
164the JSON Bibles repository
165.RI ( https://codeberg.org/maxwelljensen/bible-json/ )
166and can be adapted for any translation.
167.PP
168Every Bible file consists of a top\-level object with two fields:
169.PP
170.nf
171.RS
172{
173  "metadata": { ... },
174  "verses": [ ... ]
175}
176.RE
177.fi
178.PP
179.IP \(bu 3
180\fBmetadata\fR: an object that may contain information about the translation
181(name, copyright, language, source, etc.). Its exact content is not used by
182\fBbibel\fR but is preserved for provenance.
183.IP \(bu 3
184\fBverses\fR: an array of verse objects, each representing a single verse of
185the Bible. The array is ordered canonically (Genesis 1:1 through Revelation 22:21).
186Each verse object has the following fields:
187.PP
188.TS
189tab(;) allbox;
190l l l.
191Field;Type;Description
192_
193\fBbook_name\fR;string;Full name of the book (e.g., "Mateusza", "John", "Genesis")
194\fBbook\fR;integer;Standard Protestant book number (1 = Genesis, 40 = Matthew, 66 = Revelation)
195\fBchapter\fR;integer;Chapter number within the book
196\fBverse\fR;integer;Verse number within the chapter
197\fBtext\fR;string;The verse text. May contain the pilcrow character ¶ to indicate paragraph breaks.
198.TE
199.PP
200Example entry from \fIpol_nbg.json\fR:
201.PP
202.nf
203.RS
204{
205  "book_name": "Mateusza",
206  "book": 40,
207  "chapter": 1,
208  "verse": 1,
209  "text": "¶ KSIĘGA początku Jezusa Chrystusa, syna Dawida, syna Abrahama."
210}
211.RE
212.fi
213.SS Why this schema?
214.PP
215The schema supports the specific needs of \fBbibel\fR (and similar date‑based
216readers) while keeping the files simple and reusable.
217.PP
218\fBGlobal verse offset\fR
219.RS
220\fBbibel\fR calculates a daily reading position as a global verse offset:
221.PP
222.nf
223offset = (day_of_year - 1) * verses_per_day   (mod total_verses)
224.fi
225.PP
226Because the \fBverses\fR array is flat and ordered canonically, the program can
227immediately jump to the verse at index \fIoffset\fR without traversing nested
228chapters or books. This makes the lookup O(1) in practice.
229.RE
230.PP
231\fBRedundant \fBbook\fB number: fast filtering by testament\fR
232.RS
233Having a numeric \fBbook\fR field (1‑66) allows \fBbibel\fR to efficiently select
234a range of books for different reading modes:
235.PP
236.TS
237tab(;) allbox;
238l l.
239Reading Mode;Book Range
240_
241evangelion;40–43 (Matthew through John)
242new_testament;40–66 (Matthew through Revelation)
243old_testament;1–39 (Genesis through Malachi)
244bible;1–66 (entire Bible)
245.TE
246.PP
247Without the numeric \fBbook\fR field, the program would need to compare string
248names or parse a separate book index, which is slower and more error‑prone
249across different languages.
250.RE
251.PP
252\fBPilcrow (¶) for optional paragraph rendering\fR
253.RS
254Many Bible translations include the pilcrow character ¶ as an inline marker for
255paragraph beginnings. \fBbibel\fR offers a \fB\-\-paragraphs\fR (\fB\-g\fR) flag
256that turns each pilcrow into a blank line instead of ignoring it. This keeps the
257raw text clean (no extra markup) while allowing optional formatting at display
258time.
259.RE
260.PP
261The schema is a direct export format from Bible SuperSearch
262.RI ( https://www.biblesupersearch.com/bible-downloads/ ),
263ensuring compatibility and ease of generation.
264.SH EASTER CALCULATIONS
265The TUI displays a progress bar showing time until the next Easter:
266.IP \(bu 3
267\fBOrthodox Easter\fR (default): Calculated using Meeus Julian algorithm,
268accurate for years after 325 AD.
269.IP \(bu 3
270\fBRoman Catholic Easter\fR (with \fB\-l\fR flag): Calculated using Delambre
271and Butcher's algorithm for Gregorian calendar.
272.PP
273The progress bar shows:
274.IP \(bu 3
275Visual segments (█) representing percentage of annual cycle between consecutive
276Easters
277.IP \(bu 3
278Exact days, hours, and minutes until next Easter
279.SH EXAMPLES
280.TP
281.B bibel
282Default TUI mode with interactive display showing Orthodox Easter progress.
283.TP
284.B bibel \-\-latin
285Roman Catholic Easter progress bar instead of Orthodox.
286.TP
287.B bibel \-\-plain
288Plain text output without formatting or TUI.
289.TP
290.B bibel \-\-formatted
291Formatted output with ANSI colours.
292.TP
293.B bibel \-\-numbered
294Numbered verses (each verse on its own line with verse number).
295.TP
296.B bibel \-\-paragraphs
297Paragraph mode (pilcrows render as blank lines).
298.TP
299.B bibel \-\-numbered \-\-paragraphs
300Combine numbered and paragraph modes.
301.TP
302.B bibel \-\-plain \-\-numbered
303Plain output with numbered verses.
304.TP
305.B bibel \-\-generate\-config
306Generate a default configuration file.
307.TP
308.B bibel \-\-reading new_testament \-\-formatted
309Formatted output from New Testament.
310.TP
311.B bibel \-\-reading bible \-\-plain
312Plain text output from entire Bible.
313.SH FILES
314.TP
315.B $XDG_CONFIG_HOME/bibel/config.toml
316Configuration file (default: ~/.config/bibel/config.toml).
317.TP
318.B $XDG_DATA_HOME/bibel/
319Directory for Bible JSON files (default: ~/.local/share/bibel/).
320.TP
321.B ./books/pol_nbg.json
322Default Bible data file (Polish New Bible translation).
323.TP
324.B ./configs/config.example.toml
325Example configuration file.
326.SH EXIT STATUS
327.PP
328.B bibel
329exits with:
330.TP
331.B 0
332on successful operation.
333.TP
334.B 1
335on configuration error, Bible data loading failure, or calculation error.
336.SH ENVIRONMENT
337.TP
338.B XDG_CONFIG_HOME
339Base directory for user-specific configuration files. Defaults to ~/.config.
340.TP
341.B XDG_DATA_HOME
342Base directory for user-specific data files. Defaults to ~/.local/share.
343.TP
344.B TERM
345Terminal type. Used for determining TUI capabilities and colour support.
346.SH BUGS
347Report issues at the project repository.
348.SH SEE ALSO
349.PP
350.UR https://github.com/charmbracelet/bubbletea
351bubbletea(1)
352.UE ,
353.UR https://github.com/charmbracelet/lipgloss
354lipgloss(1)
355.UE ,
356.UR https://github.com/spf13/viper
357viper(1)
358.UE ,
359.UR https://github.com/alexflint/go-arg
360go\-arg(1)
361.UE ,
362.UR https://github.com/adrg/xdg
363xdg(1)
364.UE
365.PP
366.UR https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
367European Union Public Licence 1.2
368.UE
369.PP
370.SH AUTHORS
371Maxwell Jensen <maxwelljensen@posteo.net>
372.PP
373Project repository:
374.UR https://codeberg.org/maxwelljens/bibel
375codeberg.org/maxwelljens/bibel
376.UE
377.SH COPYRIGHT
378Copyright \(co 2026 Maxwell Jensen.
379.br
380This program is licensed under the European Union Public Licence 1.2.