.Dd $Mdocdate: May 01 2025 $
.Dt ESV 1
.Os
.Sh NAME
.Nm esv
.Nd read the Bible
.Sh SYNOPSIS
.Nm esv
.Bk -words
.Op Fl aFfHhNnRrV
.Op Fl c Ar config
.Op Fl l Ar length
.Ar book verses
.Ek
.Sh DESCRIPTION
.Nm
displays Bible passages on your terminal.
It can also play recorded audio tracks of certain passages,
through integration with an MP3 player utility.
.Pp
See the section
.Sx EXAMPLES
below for some basic usage examples.
Verses can be provided in the format of
.Em chapter ,
.Em chapter-chapter ,
.Em chapter:verse ,
and
.Em chapter:verse-verse .
If the name of your desired book has a space in it, e.g.
.Dq "1 Corinthians" ,
you can put a hyphen or underscore in the place of the space,
or you can just pass the full book name with the space in it
by surrounding the argument with quotes in your shell.
Thus, both
.Dq 1-Corinthians
and
.Dq "1 Corinthians"
are valid book names.
.Pp
By default,
.Xr mpg123 1
is used as the MP3 player.
However, this can be overridden;
see the
.Sx ENVIRONMENT
section for more information on this.
.Pp
The options are as follows:
.Bl -tag -width 123456
.It Fl a
Play a recorded audio track rather than showing a passage.
.It Fl c Ar config
Read the configuration from the path
.Ar config .
This overrides the
.Ev ESV_CONFIG
environment variable (see section
.Sx ENVIRONMENT ) .
.It Fl F
Exclude footnotes.
.It Fl f
Include footnotes (the default).
.It Fl H
Exclude headings.
.It Fl h
Include headings (the default).
.It Fl l Ar length
Limit the length of lines in passages at
.Ar length
characters. If
.Ar length
is 0, do not set a limit on line length.
.Pp
If this option is not given,
the line length limit will fall back on the value provided in
the configuration file;
see
.Xr esv.conf 5 .
.Pp
If there is no value present in the configuration file,
.Nm
will get the width of the terminal,
and will use this as the line length limit,
unless the terminal's width is greater than 78,
in which case the line length limit will be set to 78.
This heuristic exists for readability purposes,
and you can always override it by specifying your preference in
.Xr esv.conf 5 .
.It Fl N
Exclude verse numbers.
.It Fl n
Include verse numbers (the default).
.It Fl R
Exclude passage references.
.It Fl r
Include passage references (the default).
.It Fl V
Print the version number and exit.
.El
.Pp
The options
.Fl FfHhlNnRr
only apply when reading text passages,
that is, when
.Fl a
or
.Fl s
is not given.
.Sh ENVIRONMENT
.Bl -tag -width ESV_CONFIG
.It Ev ESV_CONFIG
Where to read the configuration file,
rather than using the default location (see section
.Sx FILES ) .
.It Ev ESV_PLAYER
The name of the MP3 player to use for playing audio passages.
If this is not set,
.Nm
will look for
.Xr mpg123 1
and start it.
.El
.Sh FILES
.Bl -tag -width ~/.config/esv.conf
.It Pa ~/.config/esv.conf
default configuration file location
.El
.Sh EXAMPLES
Read John 1:29-31:
.Pp
.Dl esv John 1:29-31
.Pp
Listen to a recorded audio track of Psalm 128:
.Pp
.Dl esv -a Psalm 128
.Pp
Search the Bible for the phrase
.Dq "in love" :
.Pp
.Dl esv -s 'in love'
.Pp
.Sh SEE ALSO
.Xr esv.conf 5
.Sh AUTHORS
.An Jeremy Baxter Aq Mt jeremy@reformers.dev
.Pp
Part of the
.Sy esv
distribution found at
.Lk https://reformers.dev/esv
.Sh BUGS
Currently there are no known bugs in
.Nm .
If you think you've found a potential bug,
please report it to my email address above.