lesskey.1 (10884B)
- '\" t
- .TH LESSKEY 1 "Version 643: 20 Jul 2023"
- .SH NAME
- lesskey \- customize key bindings for less
- .SH "SYNOPSIS (deprecated)"
- .B "lesskey [\-o output] [\-\-] [input]"
- .br
- .B "lesskey [\-\-output=output] [\-\-] [input]"
- .br
- .B "lesskey \-V"
- .br
- .B "lesskey \-\-version"
- .SH SCOPE
- This document describes the format of the
- .B lesskey
- source file, which is used by
- .B less
- version 582 and later.
- In previous versions of
- .BR less ,
- a separate program called
- .B lesskey
- was used to compile the
- .B lesskey
- source file into a format understood by
- .BR less .
- This compilation step is no longer required and the
- .B lesskey
- program is therefore deprecated, although the file format remains supported by
- .B less
- itself.
- .PP
- .SH DESCRIPTION
- A
- .B lesskey
- file specifies a set of key bindings and environment variables
- to be used by subsequent invocations of
- .BR less .
- .SH FILE FORMAT
- The input file consists of one or more
- .IR sections .
- Each section starts with a line that identifies the type of section.
- Possible sections are:
- .IP #command
- Customizes command key bindings.
- .IP #line-edit
- Customizes line-editing key bindings.
- .IP #env
- Defines environment variables.
- .PP
- Blank lines and lines which start with a hash mark (#) are ignored,
- except as noted below.
- .
- .SH "COMMAND SECTION"
- The command section begins with the line
- .sp
- #command
- .sp
- If the command section is the first section in the file,
- this line may be omitted.
- The command section consists of lines of the form:
- .sp
- \fIstring\fP <whitespace> \fIaction\fP [extra-string] <newline>
- .sp
- Whitespace is any sequence of one or more spaces and/or tabs.
- The \fIstring\fP is the command key(s) which invoke the action.
- The \fIstring\fP may be a single command key, or a sequence of up to 15 keys.
- The \fIaction\fP is the name of the less action, from the list below.
- The characters in the \fIstring\fP 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:
- .RS 5m
- .TS
- l l l.
- \eb BACKSPACE (0x08)
- \ee ESCAPE (0x1B)
- \en NEWLINE (0x0A)
- \er RETURN (0x0D)
- \et TAB (0x09)
- .TE
- .sp
- \ek followed by a single character represents the char(s) produced when one of these keys is pressed:
- .TS
- l l.
- \ekb BACKSPACE (the BACKSPACE key)
- \ekB ctrl-BACKSPACE
- \ekd DOWN ARROW
- \ekD PAGE DOWN
- \eke END
- \ekh HOME
- \eki INSERT
- \ekl LEFT ARROW
- \ekL ctrl-LEFT ARROW
- \ekr RIGHT ARROW
- \ekR ctrl-RIGHT ARROW
- \ekt BACKTAB
- \eku UP ARROW
- \ekU PAGE UP
- \ekx DELETE
- \ekX ctrl-DELETE
- \ek1 F1
- .TE
- .PP
- A backslash followed by any other character indicates that character is
- to be taken literally.
- Characters which must be preceded by backslash include
- caret, space, tab, hash mark and the backslash itself.
- .PP
- An action may be followed by an "extra" string.
- When such a command is entered while running
- .BR less ,
- the action is performed, and then the extra
- string is parsed, just as if it were typed in to
- .BR less .
- This feature can be used in certain cases to extend
- the functionality of a command.
- For example, see the "{" and ":t" commands in the example below.
- The extra string has a special meaning for the "quit" action:
- when
- .B less
- quits, the first character of the extra string is used as its exit status.
- .
- .SH EXAMPLE
- The following input file describes the set of
- default command keys used by
- .BR less .
- Documentation on each command can be found in the
- .less
- man page, under the key sequence which invokes the command.
- .sp
- .RS 5m
- .TS
- l l.
- #command
- \er forw-line
- \en forw-line
- e forw-line
- j forw-line
- \ekd forw-line
- ^E forw-line
- ^N forw-line
- k back-line
- y back-line
- ^Y back-line
- ^K back-line
- ^P back-line
- J forw-line-force
- K back-line-force
- Y back-line-force
- d forw-scroll
- ^D forw-scroll
- u back-scroll
- ^U back-scroll
- \e40 forw-screen
- f forw-screen
- ^F forw-screen
- ^V forw-screen
- \ekD forw-screen
- b back-screen
- ^B back-screen
- \eev back-screen
- \ekU back-screen
- z forw-window
- w back-window
- \ee\e40 forw-screen-force
- F forw-forever
- \eeF forw-until-hilite
- R repaint-flush
- r repaint
- ^R repaint
- ^L repaint
- \eeu undo-hilite
- \eeU clear-search
- g goto-line
- \ekh goto-line
- < goto-line
- \ee< goto-line
- p percent
- % percent
- \ee[ left-scroll
- \ee] right-scroll
- \ee( left-scroll
- \ee) right-scroll
- \ekl left-scroll
- \ekr right-scroll
- \ee{ no-scroll
- \ee} end-scroll
- { forw-bracket {}
- } back-bracket {}
- ( forw-bracket ()
- ) back-bracket ()
- [ forw-bracket []
- ] back-bracket []
- \ee^F forw-bracket
- \ee^B back-bracket
- G goto-end
- \ee> goto-end
- > goto-end
- \eke goto-end
- \eeG goto-end-buffered
- \&= status
- ^G status
- :f status
- / forw-search
- ? back-search
- \ee/ forw-search *
- \ee? back-search *
- n repeat-search
- \een repeat-search-all
- N reverse-search
- \eeN reverse-search-all
- & filter
- m set-mark
- M set-mark-bottom
- \eem clear-mark
- ' goto-mark
- ^X^X goto-mark
- E examine
- :e examine
- ^X^V examine
- :n next-file
- :p prev-file
- t next-tag
- T prev-tag
- :x index-file
- :d remove-file
- - toggle-option
- :t toggle-option t
- s toggle-option o
- ## Use a long option name by starting the
- ## extra string with ONE dash; eg:
- ## s toggle-option -log-file\en
- \&_ display-option
- | pipe
- v visual
- ! shell
- # pshell
- + firstcmd
- H help
- h help
- V version
- 0 digit
- 1 digit
- 2 digit
- 3 digit
- 4 digit
- 5 digit
- 6 digit
- 7 digit
- 8 digit
- 9 digit
- q quit
- Q quit
- :q quit
- :Q quit
- ZZ quit
- .TE
- .RE
- .sp
- .SH PRECEDENCE
- Commands specified by
- .B lesskey
- take precedence over the default commands.
- A default command key may be disabled by including it in the
- input file with the action "invalid".
- Alternatively, a key may be defined
- to do nothing by using the action "noaction".
- "noaction" is similar to "invalid", but
- .B less
- will give an error beep for an "invalid" command,
- but not for a "noaction" command.
- In addition, ALL default commands may be disabled by
- adding this control line to the input file:
- .sp
- #stop
- .sp
- This will cause all default commands to be ignored.
- The #stop line should be the last line in that section of the file.
- .PP
- Be aware that #stop can be dangerous.
- Since all default commands are disabled,
- you must provide sufficient commands before the #stop line
- to enable all necessary actions.
- For example, failure to provide a "quit" command can lead to frustration.
- .
- .SH "LINE EDITING SECTION"
- The line-editing section begins with the line:
- .sp
- #line-edit
- .sp
- This section specifies new key bindings for the line editing commands,
- in a manner similar to the way key bindings for
- ordinary commands are specified in the #command section.
- The line-editing section consists of a list of keys and actions,
- one per line as in the example below.
- .
- .SH EXAMPLE
- The following input file describes the set of
- default line-editing keys used by
- .BR less :
- .sp
- .RS 5m
- .TS
- l l.
- #line-edit
- \et forw-complete
- \e17 back-complete
- \ee\et back-complete
- ^L expand
- ^V literal
- ^A literal
- \eel right
- \ekr right
- \eeh left
- \ekl left
- \eeb word-left
- \ee\ekl word-left
- \eew word-right
- \ee\ekr word-right
- \eei insert
- \eex delete
- \ekx delete
- \eeX word-delete
- \eekx word-delete
- \ee\eb word-backspace
- \ee0 home
- \ekh home
- \ee$ end
- \eke end
- \eek up
- \eku up
- \eej down
- ^G abort
- .TE
- .RE
- .sp
- .
- .SH "LESS ENVIRONMENT VARIABLES"
- The environment variable section begins with the line
- .sp
- #env
- .sp
- Following this line is a list of environment variable assignments.
- Each line consists of an environment variable name, an equals sign (=)
- and the value to be assigned to the environment variable.
- White space before and after the equals sign is ignored.
- Variables assigned in this way are visible only to
- .BR less .
- If a variable is specified in the system environment and also in a
- lesskey file, the value in the lesskey file takes precedence.
- .
- .sp
- If the variable name is followed by += rather than =,
- the string is appended to the variable's existing value.
- This currently works only if any += lines immediately follow
- the same variable's original definition (with an = line),
- without any intervening definitions of other variables.
- It can append only to a variable defined earlier in the file;
- it cannot append to a variable in the system environment.
- The string is appended literally, without any extra whitespace added,
- so if whitespace is desired,
- it should be appended to the end of the preceding line.
- (It cannot be added to the beginning of the += string because space after
- the equals sign is ignored, as noted above.)
- .
- .SH CONDITIONAL CONFIGURATION
- If a line begins with #version followed by a relational operator and a version number,
- the remainder of the line is parsed if and only if the running version of
- .B less
- (or
- .BR lesskey )
- matches the operator.
- This can be helpful if a lesskey file is used by different versions of
- .BR less .
- .sp
- For example, suppose that a new command named 'sideways-search' is added in
- .B less
- version 777.
- Then the following line would assign the command to the Q key, but only in versions of
- .B less
- which support it. The line would be ignored by versions earlier than 777.
- .sp
- .nf
- #version >= 777 Q sideways-search
- .fi
- .sp
- These six operators are supported:
- .RS 5m
- .TS
- l l.
- > Greater than
- < Less than
- >= Greater than or equal to
- <= Less than or equal to
- = Equal to
- != Not equal to
- .TE
- .RE
- .sp
- The #version feature is not supported in
- .B less
- and
- .B lesskey
- before version 594.
- In those older versions, all #version lines are ignored.
- .
- .SH EXAMPLE
- The following input file sets the \-i and \-S options when
- .less
- is run and, on version 595 and higher, adds a \-\-color option.
- .sp
- .nf
- #env
- ## (Note that there must be a space at the end of the next line,
- ## to separate the --color option from the -S option.)
- LESS = \-i\ \-S\
- #version\ >=\ 595\ \ LESS\ +=\ \-\-color=Hkc
- .fi
- .
- .SH "SEE ALSO"
- .BR less (1)
- .
- .SH WARNINGS
- On MS-DOS and OS/2 systems, certain keys send a sequence of characters
- which start with a NUL character (0).
- This NUL character should be represented as \e340 in a lesskey file.
- .
- .SH COPYRIGHT
- Copyright (C) 1984-2023 Mark Nudelman
- .PP
- less is part of the GNU project and is free software.
- You can redistribute it and/or modify it
- under the terms of either
- (1) the GNU General Public License as published by
- the Free Software Foundation; or (2) the Less License.
- See the file README in the less distribution for more details
- regarding redistribution.
- You should have received a copy of the GNU General Public License
- along with the source for less; see the file COPYING.
- If not, write to the Free Software Foundation, 59 Temple Place,
- Suite 330, Boston, MA 02111-1307, USA.
- You should also have received a copy of the Less License;
- see the file LICENSE.
- .PP
- less is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- .
- .SH AUTHOR
- .
- Mark Nudelman
- .br
- Report bugs at https://github.com/gwsw/less/issues.