From 47aba05c98740151219b175f505c1ab7117e372d Mon Sep 17 00:00:00 2001
From: schwarze <schwarze@openbsd.org>
Date: Tue, 7 Dec 2021 13:26:49 +0000
Subject: [PATCH] Improve the COMMAND SECTION section in multiple respects
 regarding correctness, clarity, readability, and markup conventions.
 Triggered by Richard Ulmer <... rulmer at mailbox dot org> wondering whether
 the list of actions is complete and pointing out that the "shell" action no
 longer exists (it was removed quite some time ago for security reasons). OK
 jmc@

---
 usr.bin/less/lesskey.1 | 89 +++++++++++++++++++++++++-----------------
 1 file changed, 54 insertions(+), 35 deletions(-)

diff --git a/usr.bin/less/lesskey.1 b/usr.bin/less/lesskey.1
index 3fccdcea841..c7a8c5bc446 100644
--- a/usr.bin/less/lesskey.1
+++ b/usr.bin/less/lesskey.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: lesskey.1,v 1.16 2019/06/02 06:53:11 bentley Exp $
+.\"	$OpenBSD: lesskey.1,v 1.17 2021/12/07 13:26:49 schwarze Exp $
 .\"
 .\" Copyright (C) 2000-2012  Mark Nudelman
 .\"
@@ -22,7 +22,7 @@
 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-.Dd $Mdocdate: June 2 2019 $
+.Dd $Mdocdate: December 7 2021 $
 .Dt LESSKEY 1
 .Os
 .Sh NAME
@@ -118,32 +118,42 @@ The command section begins with the line
 .Pp
 If the command section is the first section in the file,
 this line may be omitted.
+.Pp
 The command section consists of lines of the form:
 .Bd -filled -offset indent
-.Ar string
-.Aq whitespace
+.Ar keys
 .Ar action
-.Bq extra-string
-.Aq newline
+.Op Ar extra
 .Ed
 .Pp
-Whitespace is any sequence of one or more spaces and/or tabs.
-The
-.Ar string
-is the command key(s) which invoke the action.
-The
-.Ar string
-may be a single command key, or a sequence of up to 15 keys.
+The three fields are separated by whitespace
+consisting of one or more spaces and/or tabs.
+.Pp
 The
+.Ar keys
+string consists of at least one and at most 15 keys.
+By typing it in
+.Xr less 1 ,
+the
 .Ar action
-is the name of the less action, from the list below.
-The characters in the
-.Ar string
-may appear literally, or be prefixed by a caret to indicate a control key.
-A backslash followed by one to three octal digits may be used to
-specify a character by its octal value.
-A backslash followed by certain characters specifies input
-characters as follows:
+is invoked.
+The list of default key bindings given below
+also serves as a list of supported actions.
+.Pp
+Each of the
+.Ar keys
+can be specified in these forms:
+.Bl -bullet -offset indent
+.It
+a literal character
+.It
+a character prefixed by a caret to indicate a control key
+.It
+a backslash followed by one to three octal digits
+to specify a key by its octal value
+.It
+a backslash followed by certain characters
+to specify input characters as follows:
 .Pp
 .Bl -tag -width Ds -offset indent -compact
 .It \eb
@@ -175,33 +185,43 @@ END
 .It \ekx
 DELETE
 .El
-.Pp
-A backslash followed by any other character indicates that character is
-to be taken literally.
+.It
+a backslash followed by any other character
+to indicate that character is to be taken literally.
 Characters which must be preceded by backslash include
-caret, space, tab and the backslash itself.
+caret, space, tab, and the backslash itself.
+.El
 .Pp
 An action may be followed by an
-.Qq extra
+.Ar extra
 string.
-When such a command is entered while running less,
-the action is performed, and then the extra
-string is parsed, just as if it were typed in to less.
+It is parsed, just as if it were typed into
+.Xr less 1 ,
+after performing the
+.Ar action .
 This feature can be used in certain cases to extend
 the functionality of a command.
 For example, see the
 .Sq {
 and
 .Sq :t
-commands in the example below.
-The extra string has a special meaning for the
+keys in the list of default bindings below.
+.Pp
+The
+.Ar extra
+string has a special meaning for the
 .Qq quit
 action:
-when less quits,
-first character of the extra string is used as its exit status.
+when
+.Xr less 1
+quits,
+first character of the
+.Ar extra
+string is used as its exit status.
 .Pp
 The following input file describes the set of
-default command keys used by less:
+default command keys used by
+.Xr less 1 :
 .Bd -literal -offset indent
 #command
 \er	forw-line
@@ -294,7 +314,6 @@ s	toggle-option o
 _	display-option
 |	pipe
 v	visual
-!	shell
 +	firstcmd
 H	help
 h	help
-- 
2.20.1