.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 audio passages.
.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 spaces in it, e.g.
.Dq "1 Corinthians" ,
you can provide the book name with hyphens or underscores in place of
the spaces, or you can pass the original book name.
Thus, both
.Dq 1-Corinthians
and
.Dq 1_Corinthians
are also valid book names.
.Pp
By default,
.Xr mpg123 1
is used as the player for audio passages.
This can be overridden however;
see the
.Sx ENVIRONMENT
section for more information.
.Pp
The options are as follows:
.Bl -tag -width 123456
.It Fl a
Play an audio passage instead of printing a text 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 audio player to use when playing audio passages.
The program specified must support playing MP3 audio.
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 139
.Pp
.Sh SEE ALSO
.Xr esvsearch 1
.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.