.Dd $Mdocdate: June 18 2024 $
.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
.Op Fl s Ar query
.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 an underscore in the place of the space,
or you can just pass the full book name with the space
by surrounding the argument with quotes in your shell.
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 configfile
Read the configuration from the path
.Ar configfile .
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 s Ar query
Rather than displaying a passage or playing an audio track,
search the Bible for instances of
.Ar query .
.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 Matthew 6:24:
.Pp
.Dl esv Matthew 6:24
.Pp
Listen to a recorded audio track of Psalm 23:
.Pp
.Dl esv -a Psalm 23
.Pp
Search the Bible for instances of the word
.Dq dogs :
.Pp
.Dl esv -s dogs
.Pp
.Sh SEE ALSO
.Xr esv.conf 5
.Sh AUTHORS
.An Jeremy Baxter Aq Mt jtbx@disroot.org
.Sh BUGS
Currently searching the Bible using
.Fl s
only shows a portion of the results.
If you have many results for your query,
and there are not many in the New Testament compared to those
in the Old Testament,
your search may have been affected by this bug.
.Pp
If you have discovered a bug in
.Nm ,
please report it to the bug tracker found at
.Lk https://todo.sr.ht/~jeremy/esv
or send an email to
.Mt ~jeremy/esv@todo.sr.ht .