esv.1: revise manual

Reword much of the manual, add the -s option, and add AUTHORS and BUGS
sections among other small changes.

esv.1

@@ -1,37 +1,48 @@
-.Dd $Mdocdate: December 19 2023 $
+.Dd $Mdocdate: February 29 2024 $
 .Dt ESV 1
 .Os
 .Sh NAME
 .Nm esv
-.Nd read the Bible from your terminal
+.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
-is a program that displays passages of the Bible on your terminal.
+displays Bible passages on your terminal. It can also play recorded
-It can also play recorded audio tracks of certain passages,
+audio tracks of certain passages, through integration with an MP3
-through integration with the
+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 .
+.Pp
+By default,
 .Xr mpg123 1
-utility. While audio is playing, you can use the standard mpg123
+is used as the MP3 player. However, this can be overridden; see the
-controls: spacebar to pause/resume, comma to rewind, period
+.Sx ENVIRONMENT
-to fast-forward, etc. Read about the
+section for more information on this.
-.Fl C
-option in mpg123's manual for more information.
 .Pp
 The options are as follows:
-.Bl -tag -width keyword
+.Bl -tag -width 123456
 .It Fl a
-Instead of displaying text passages, play a recorded audio track.
+Play a recorded audio track rather than showing a passage.
-.It Fl C Ar config
+.It Fl C Ar configfile
-Use
+Read the configuration from the path
-.Ar config
+.Ar configfile .
-as the configuration file path. This overrides the
+This overrides the
 .Ev ESV_CONFIG
 environment variable (see section
 .Sx ENVIRONMENT ) .
@@ -44,9 +55,11 @@ Exclude headings.
 .It Fl h
 Include headings (the default).
 .It Fl l Ar length
-Use
+Limit the width of text passage lines at
 .Ar length
-as the maximum line length.
+characters. If
+.Ar length
+is 0, do not limit them at all.
 .It Fl N
 Exclude verse numbers.
 .It Fl n
@@ -55,33 +68,67 @@ Include verse numbers (the default).
 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
+Where to read the configuration file, rather than using the default
+location (see section
 .Sx FILES ) .
 .It Ev ESV_PLAYER
-What MP3 player to use for playing audio, rather than using mpg123.
+The name of the MP3 player to use for playing audio passages. If this
-Using mpg123 is recommended over other players such as mpv, because
+is not set,
-mpv's controls don't work well when started by another process
+.Nm
-for some reason.
+will look for
+.Xr mpg123 1
+and start it.
 .Sh FILES
 .Bl -tag -width ~/.config/esv.conf
 .It Pa ~/.config/esv.conf
 default configuration file location
 .El
-
 .Sh EXAMPLES
-Read Psalm 23:
+Read Matthew 6:24:
 .Pp
-.Dl esv Psalm 23
+.Dl esv Matthew 6:24
 .Pp
-Listen to a recorded audio track of Matthew 5-7:
+Listen to a recorded audio track of Psalm 23:
 .Pp
-.Dl esv -a Matthew 5-7
+.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 .