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
162A JSON file is used to read a Bible. The Bible has to follow this structure:
163.PP
164.nf
165.RS
166{
167  "metadata": { ... },
168  "verses": [
169    {
170      "book_name": "Mateusza",
171      "book": 40,
172      "chapter": 1,
173      "verse": 1,
174      "text": "¶ KSIĘGA początku Jezusa Chrystusa..."
175    },
176    ...
177  ]
178}
179.RE
180.fi
181.SH EASTER CALCULATIONS
182The TUI displays a progress bar showing time until the next Easter:
183.IP \(bu 3
184\fBOrthodox Easter\fR (default): Calculated using Meeus Julian algorithm,
185accurate for years after 325 AD.
186.IP \(bu 3
187\fBRoman Catholic Easter\fR (with \fB\-l\fR flag): Calculated using Delambre
188and Butcher's algorithm for Gregorian calendar.
189.PP
190The progress bar shows:
191.IP \(bu 3
192Visual segments (█) representing percentage of annual cycle between consecutive
193Easters
194.IP \(bu 3
195Exact days, hours, and minutes until next Easter
196.IP \(bu 3
197Real-time updates while TUI is running
198.SH EXAMPLES
199.TP
200.B bibel
201Default TUI mode with interactive display showing Orthodox Easter progress.
202.TP
203.B bibel \-\-latin
204Roman Catholic Easter progress bar instead of Orthodox.
205.TP
206.B bibel \-\-plain
207Plain text output without formatting or TUI.
208.TP
209.B bibel \-\-formatted
210Formatted output with ANSI colours.
211.TP
212.B bibel \-\-numbered
213Numbered verses (each verse on its own line with verse number).
214.TP
215.B bibel \-\-paragraphs
216Paragraph mode (pilcrows render as blank lines).
217.TP
218.B bibel \-\-numbered \-\-paragraphs
219Combine numbered and paragraph modes.
220.TP
221.B bibel \-\-plain \-\-numbered
222Plain output with numbered verses.
223.TP
224.B bibel \-\-generate\-config
225Generate a default configuration file.
226.TP
227.B bibel \-\-reading new_testament \-\-formatted
228Formatted output from New Testament.
229.TP
230.B bibel \-\-reading bible \-\-plain
231Plain text output from entire Bible.
232.SH FILES
233.TP
234.B $XDG_CONFIG_HOME/bibel/config.toml
235Configuration file (default: ~/.config/bibel/config.toml).
236.TP
237.B $XDG_DATA_HOME/bibel/
238Directory for Bible JSON files (default: ~/.local/share/bibel/).
239.TP
240.B ./books/pol_nbg.json
241Default Bible data file (Polish New Bible translation).
242.TP
243.B ./configs/config.example.toml
244Example configuration file.
245.SH EXIT STATUS
246.PP
247.B bibel
248exits with:
249.TP
250.B 0
251on successful operation.
252.TP
253.B 1
254on configuration error, Bible data loading failure, or calculation error.
255.SH ENVIRONMENT
256.TP
257.B XDG_CONFIG_HOME
258Base directory for user-specific configuration files. Defaults to ~/.config.
259.TP
260.B XDG_DATA_HOME
261Base directory for user-specific data files. Defaults to ~/.local/share.
262.TP
263.B TERM
264Terminal type. Used for determining TUI capabilities and colour support.
265.SH BUGS
266Report issues at the project repository.
267.SH SEE ALSO
268.PP
269.UR https://github.com/charmbracelet/bubbletea
270bubbletea(1)
271.UE ,
272.UR https://github.com/charmbracelet/lipgloss
273lipgloss(1)
274.UE ,
275.UR https://github.com/spf13/viper
276viper(1)
277.UE ,
278.UR https://github.com/alexflint/go-arg
279go\-arg(1)
280.UE ,
281.UR https://github.com/adrg/xdg
282xdg(1)
283.UE
284.PP
285.UR https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
286European Union Public Licence 1.2
287.UE
288.PP
289.SH AUTHORS
290Maxwell Jensen <maxwelljensen@posteo.net>
291.PP
292Project repository:
293.UR https://codeberg.org/maxwelljens/bibel
294codeberg.org/maxwelljens/bibel
295.UE
296.SH COPYRIGHT
297Copyright \(co 2026 Maxwell Jensen.
298.br
299This program is licensed under the European Union Public Licence 1.2.