| 1 |
'\" t |
| 2 |
.TH LESSKEY 1 "Version 668: 06 Oct 2024" |
| 3 |
.SH NAME |
| 4 |
lesskey \- customize key bindings for less |
| 5 |
.SH "SYNOPSIS (deprecated)" |
| 6 |
.B "lesskey [\-o output] [\-\-] [input]" |
| 7 |
.br |
| 8 |
.B "lesskey [\-\-output=output] [\-\-] [input]" |
| 9 |
.br |
| 10 |
.B "lesskey \-V" |
| 11 |
.br |
| 12 |
.B "lesskey \-\-version" |
| 13 |
.SH SCOPE |
| 14 |
This document describes the format of the |
| 15 |
.B lesskey |
| 16 |
source file, which is used by |
| 17 |
.B less |
| 18 |
version 582 and later. |
| 19 |
In previous versions of |
| 20 |
.BR less , |
| 21 |
a separate program called |
| 22 |
.B lesskey |
| 23 |
was used to compile the |
| 24 |
.B lesskey |
| 25 |
source file into a format understood by |
| 26 |
.BR less . |
| 27 |
This compilation step is no longer required and the |
| 28 |
.B lesskey |
| 29 |
program is therefore deprecated, although the file format remains supported by |
| 30 |
.B less |
| 31 |
itself. |
| 32 |
.PP |
| 33 |
.SH DESCRIPTION |
| 34 |
A |
| 35 |
.B lesskey |
| 36 |
file specifies a set of key bindings and environment variables |
| 37 |
to be used by subsequent invocations of |
| 38 |
.BR less . |
| 39 |
.SH FILE FORMAT |
| 40 |
The input file consists of one or more |
| 41 |
.IR sections . |
| 42 |
Each section starts with a line that identifies the type of section. |
| 43 |
Possible sections are: |
| 44 |
.IP #command |
| 45 |
Customizes command key bindings. |
| 46 |
.IP #line-edit |
| 47 |
Customizes line-editing key bindings. |
| 48 |
.IP #env |
| 49 |
Defines environment variables. |
| 50 |
.PP |
| 51 |
Blank lines and lines which start with a hash mark (#) are ignored, |
| 52 |
except as noted below. |
| 53 |
. |
| 54 |
.SH "COMMAND SECTION" |
| 55 |
The command section begins with the line |
| 56 |
.sp |
| 57 |
#command |
| 58 |
.sp |
| 59 |
If the command section is the first section in the file, |
| 60 |
this line may be omitted. |
| 61 |
The command section consists of lines of the form: |
| 62 |
.sp |
| 63 |
\fIstring\fP <whitespace> \fIaction\fP [extra-string] <newline> |
| 64 |
.sp |
| 65 |
Whitespace is any sequence of one or more spaces and/or tabs. |
| 66 |
The \fIstring\fP is the command key(s) which invoke the action. |
| 67 |
The \fIstring\fP may be a single command key, or a sequence of up to 15 keys. |
| 68 |
The \fIaction\fP is the name of the less action, from the list below. |
| 69 |
The characters in the \fIstring\fP may appear literally, or be |
| 70 |
prefixed by a caret to indicate a control key. |
| 71 |
A backslash followed by one to three octal digits may be used to |
| 72 |
specify a character by its octal value. |
| 73 |
A backslash followed by certain characters specifies input |
| 74 |
characters as follows: |
| 75 |
.RS 5m |
| 76 |
.TS |
| 77 |
l l l. |
| 78 |
\eb BACKSPACE (0x08) |
| 79 |
\ee ESCAPE (0x1B) |
| 80 |
\en NEWLINE (0x0A) |
| 81 |
\er RETURN (0x0D) |
| 82 |
\et TAB (0x09) |
| 83 |
.TE |
| 84 |
.sp |
| 85 |
\ek followed by a single character represents the char(s) produced when one of these keys is pressed: |
| 86 |
.TS |
| 87 |
l l. |
| 88 |
\ekb BACKSPACE (the BACKSPACE key) |
| 89 |
\ekB ctrl-BACKSPACE |
| 90 |
\ekd DOWN ARROW |
| 91 |
\ekD PAGE DOWN |
| 92 |
\eke END |
| 93 |
\ekh HOME |
| 94 |
\eki INSERT |
| 95 |
\ekl LEFT ARROW |
| 96 |
\ekL ctrl-LEFT ARROW |
| 97 |
\ekr RIGHT ARROW |
| 98 |
\ekR ctrl-RIGHT ARROW |
| 99 |
\ekt BACKTAB |
| 100 |
\eku UP ARROW |
| 101 |
\ekU PAGE UP |
| 102 |
\ekx DELETE |
| 103 |
\ekX ctrl-DELETE |
| 104 |
\ek1 F1 |
| 105 |
.TE |
| 106 |
|
| 107 |
.PP |
| 108 |
A backslash followed by any other character indicates that character is |
| 109 |
to be taken literally. |
| 110 |
Characters which must be preceded by backslash include |
| 111 |
caret, space, tab, hash mark and the backslash itself. |
| 112 |
.PP |
| 113 |
An action may be followed by an "extra" string. |
| 114 |
When such a command is entered while running |
| 115 |
.BR less , |
| 116 |
the action is performed, and then the extra |
| 117 |
string is parsed, just as if it were typed in to |
| 118 |
.BR less . |
| 119 |
This feature can be used in certain cases to extend |
| 120 |
the functionality of a command. |
| 121 |
For example, see the "{" and ":t" commands in the example below. |
| 122 |
The extra string has a special meaning for the "quit" action: |
| 123 |
when |
| 124 |
.B less |
| 125 |
quits, the ASCII value of the first character of the extra string |
| 126 |
is used as its exit status. |
| 127 |
. |
| 128 |
.SH EXAMPLE |
| 129 |
The following input file describes the set of |
| 130 |
default command keys used by |
| 131 |
.BR less . |
| 132 |
Documentation on each command can be found in the |
| 133 |
.B less |
| 134 |
man page, under the key sequence which invokes the command. |
| 135 |
.sp |
| 136 |
.RS 5m |
| 137 |
.TS |
| 138 |
l l. |
| 139 |
#command |
| 140 |
\er forw-line |
| 141 |
\en forw-line |
| 142 |
e forw-line |
| 143 |
j forw-line |
| 144 |
\ekd forw-line |
| 145 |
^E forw-line |
| 146 |
^N forw-line |
| 147 |
k back-line |
| 148 |
y back-line |
| 149 |
^Y back-line |
| 150 |
^K back-line |
| 151 |
^P back-line |
| 152 |
J forw-line-force |
| 153 |
K back-line-force |
| 154 |
Y back-line-force |
| 155 |
d forw-scroll |
| 156 |
^D forw-scroll |
| 157 |
u back-scroll |
| 158 |
^U back-scroll |
| 159 |
\e40 forw-screen |
| 160 |
f forw-screen |
| 161 |
^F forw-screen |
| 162 |
^V forw-screen |
| 163 |
\ekD forw-screen |
| 164 |
b back-screen |
| 165 |
^B back-screen |
| 166 |
\eev back-screen |
| 167 |
\ekU back-screen |
| 168 |
z forw-window |
| 169 |
w back-window |
| 170 |
\ee\e40 forw-screen-force |
| 171 |
F forw-forever |
| 172 |
\eeF forw-until-hilite |
| 173 |
R repaint-flush |
| 174 |
r repaint |
| 175 |
^R repaint |
| 176 |
^L repaint |
| 177 |
\eeu undo-hilite |
| 178 |
\eeU clear-search |
| 179 |
g goto-line |
| 180 |
\ekh goto-line |
| 181 |
< goto-line |
| 182 |
\ee< goto-line |
| 183 |
p percent |
| 184 |
% percent |
| 185 |
\ee( left-scroll |
| 186 |
\ee) right-scroll |
| 187 |
\ekl left-scroll |
| 188 |
\ekr right-scroll |
| 189 |
\ee{ no-scroll |
| 190 |
\ee} end-scroll |
| 191 |
{ forw-bracket {} |
| 192 |
} back-bracket {} |
| 193 |
( forw-bracket () |
| 194 |
) back-bracket () |
| 195 |
[ forw-bracket [] |
| 196 |
] back-bracket [] |
| 197 |
\ee^F forw-bracket |
| 198 |
\ee^B back-bracket |
| 199 |
G goto-end |
| 200 |
\ee> goto-end |
| 201 |
> goto-end |
| 202 |
\eke goto-end |
| 203 |
\eeG goto-end-buffered |
| 204 |
\&= status |
| 205 |
^G status |
| 206 |
:f status |
| 207 |
/ forw-search |
| 208 |
? back-search |
| 209 |
\ee/ forw-search * |
| 210 |
\ee? back-search * |
| 211 |
n repeat-search |
| 212 |
\een repeat-search-all |
| 213 |
N reverse-search |
| 214 |
\eeN reverse-search-all |
| 215 |
^O^N osc8-forw-search |
| 216 |
^On osc8-forw-search |
| 217 |
^O^P osc8-back-search |
| 218 |
^Op osc8-back-search |
| 219 |
^O^O osc8-open |
| 220 |
& filter |
| 221 |
m set-mark |
| 222 |
M set-mark-bottom |
| 223 |
\eem clear-mark |
| 224 |
\&' goto-mark |
| 225 |
^X^X goto-mark |
| 226 |
E examine |
| 227 |
:e examine |
| 228 |
^X^V examine |
| 229 |
:n next-file |
| 230 |
:p prev-file |
| 231 |
t next-tag |
| 232 |
T prev-tag |
| 233 |
:x index-file |
| 234 |
:d remove-file |
| 235 |
- toggle-option |
| 236 |
:t toggle-option t |
| 237 |
s toggle-option o |
| 238 |
## Use a long option name by starting the |
| 239 |
## extra string with ONE dash; eg: |
| 240 |
## s toggle-option -log-file\en |
| 241 |
\&_ display-option |
| 242 |
| pipe |
| 243 |
v visual |
| 244 |
! shell |
| 245 |
# pshell |
| 246 |
+ firstcmd |
| 247 |
H help |
| 248 |
h help |
| 249 |
V version |
| 250 |
0 digit |
| 251 |
1 digit |
| 252 |
2 digit |
| 253 |
3 digit |
| 254 |
4 digit |
| 255 |
5 digit |
| 256 |
6 digit |
| 257 |
7 digit |
| 258 |
8 digit |
| 259 |
9 digit |
| 260 |
q quit |
| 261 |
Q quit |
| 262 |
:q quit |
| 263 |
:Q quit |
| 264 |
ZZ quit |
| 265 |
.TE |
| 266 |
.RE |
| 267 |
.sp |
| 268 |
.SH PRECEDENCE |
| 269 |
Commands specified by |
| 270 |
.B lesskey |
| 271 |
take precedence over the default commands. |
| 272 |
A default command key may be disabled by including it in the |
| 273 |
input file with the action "invalid". |
| 274 |
Alternatively, a key may be defined |
| 275 |
to do nothing by using the action "noaction". |
| 276 |
"noaction" is similar to "invalid", but |
| 277 |
.B less |
| 278 |
will give an error beep for an "invalid" command, |
| 279 |
but not for a "noaction" command. |
| 280 |
In addition, ALL default commands may be disabled by |
| 281 |
adding this control line to the input file: |
| 282 |
.sp |
| 283 |
#stop |
| 284 |
.sp |
| 285 |
This will cause all default commands to be ignored. |
| 286 |
The #stop line should be the last line in that section of the file. |
| 287 |
.PP |
| 288 |
Be aware that #stop can be dangerous. |
| 289 |
Since all default commands are disabled, |
| 290 |
you must provide sufficient commands before the #stop line |
| 291 |
to enable all necessary actions. |
| 292 |
For example, failure to provide a "quit" command can lead to frustration. |
| 293 |
. |
| 294 |
.SH "LINE EDITING SECTION" |
| 295 |
The line-editing section begins with the line: |
| 296 |
.sp |
| 297 |
#line-edit |
| 298 |
.sp |
| 299 |
This section specifies new key bindings for the line editing commands, |
| 300 |
in a manner similar to the way key bindings for |
| 301 |
ordinary commands are specified in the #command section. |
| 302 |
The line-editing section consists of a list of keys and actions, |
| 303 |
one per line as in the example below. |
| 304 |
. |
| 305 |
.SH EXAMPLE |
| 306 |
The following input file describes the set of |
| 307 |
default line-editing keys used by |
| 308 |
.BR less : |
| 309 |
.sp |
| 310 |
.RS 5m |
| 311 |
.TS |
| 312 |
l l. |
| 313 |
#line-edit |
| 314 |
\et forw-complete |
| 315 |
\e17 back-complete |
| 316 |
\ee\et back-complete |
| 317 |
^L expand |
| 318 |
^V literal |
| 319 |
^A literal |
| 320 |
\eel right |
| 321 |
\ekr right |
| 322 |
\eeh left |
| 323 |
\ekl left |
| 324 |
\eeb word-left |
| 325 |
\ee\ekl word-left |
| 326 |
\eew word-right |
| 327 |
\ee\ekr word-right |
| 328 |
\eei insert |
| 329 |
\eex delete |
| 330 |
\ekx delete |
| 331 |
\eeX word-delete |
| 332 |
\eekx word-delete |
| 333 |
\ee\eb word-backspace |
| 334 |
\ee0 home |
| 335 |
\ekh home |
| 336 |
\ee$ end |
| 337 |
\eke end |
| 338 |
\eek up |
| 339 |
\eku up |
| 340 |
\eej down |
| 341 |
^G abort |
| 342 |
.TE |
| 343 |
.RE |
| 344 |
.sp |
| 345 |
. |
| 346 |
.SH "LESS ENVIRONMENT VARIABLES" |
| 347 |
The environment variable section begins with the line |
| 348 |
.sp |
| 349 |
#env |
| 350 |
.sp |
| 351 |
Following this line is a list of environment variable assignments. |
| 352 |
Each line consists of an environment variable name, an equals sign (=) |
| 353 |
and the value to be assigned to the environment variable. |
| 354 |
White space before and after the equals sign is ignored. |
| 355 |
Variables assigned in this way are visible only to |
| 356 |
.BR less . |
| 357 |
If a variable is specified in the system environment and also in a |
| 358 |
lesskey file, the value in the lesskey file takes precedence. |
| 359 |
. |
| 360 |
.sp |
| 361 |
If the variable name is followed by += rather than =, |
| 362 |
the string is appended to the variable's existing value. |
| 363 |
This currently works only if any += lines immediately follow |
| 364 |
the same variable's original definition (with an = line), |
| 365 |
without any intervening definitions of other variables. |
| 366 |
It can append only to a variable defined earlier in the file; |
| 367 |
it cannot append to a variable in the system environment. |
| 368 |
The string is appended literally, without any extra whitespace added, |
| 369 |
so if whitespace is desired, |
| 370 |
it should be appended to the end of the preceding line. |
| 371 |
(It cannot be added to the beginning of the += string because space after |
| 372 |
the equals sign is ignored, as noted above.) |
| 373 |
. |
| 374 |
.sp |
| 375 |
In the string after the = sign, a substring of the form ${NAME} |
| 376 |
is replaced with the value of the environment variable "NAME". |
| 377 |
The value of the variable may come from either the system environment, |
| 378 |
an earlier lesskey file, or an earlier definition in the current lesskey file. |
| 379 |
Simple text replacements can be performed by using |
| 380 |
the syntax ${NAME/STRING/REPL}. |
| 381 |
This replaces all instances of "STRING" in the named |
| 382 |
environment variable with the text "REPL". |
| 383 |
STRING is matched using a simple text comparison; |
| 384 |
no metacharacters are supported. |
| 385 |
An instance of slash or right curly bracket in STRING or REPL |
| 386 |
must be escaped by preceding it with \fItwo\fP backslashes. |
| 387 |
If REPL is an empty string, all instances of STRING are removed. |
| 388 |
A slash immediately before the right curly bracket may be omitted. |
| 389 |
Multiple replacements may be performed by using |
| 390 |
the syntax ${NAME/STRING1/REPL1/STRING2/REPL2} and so on. |
| 391 |
. |
| 392 |
.SH CONDITIONAL CONFIGURATION |
| 393 |
If a line begins with #version followed by a relational operator and a version number, |
| 394 |
the remainder of the line is parsed if and only if the running version of |
| 395 |
.B less |
| 396 |
(or |
| 397 |
.BR lesskey ) |
| 398 |
matches the operator. |
| 399 |
This can be helpful if a lesskey file is used by different versions of |
| 400 |
.BR less . |
| 401 |
.sp |
| 402 |
For example, suppose that a new command named 'sideways-search' is added in |
| 403 |
.B less |
| 404 |
version 777. |
| 405 |
Then the following line would assign the command to the Q key, but only in versions of |
| 406 |
.B less |
| 407 |
which support it. The line would be ignored by versions earlier than 777. |
| 408 |
.sp |
| 409 |
.nf |
| 410 |
#version >= 777 Q sideways-search |
| 411 |
.fi |
| 412 |
.sp |
| 413 |
These six operators are supported: |
| 414 |
.RS 5m |
| 415 |
.TS |
| 416 |
l l. |
| 417 |
> Greater than |
| 418 |
< Less than |
| 419 |
>= Greater than or equal to |
| 420 |
<= Less than or equal to |
| 421 |
= Equal to |
| 422 |
!= Not equal to |
| 423 |
.TE |
| 424 |
.RE |
| 425 |
.sp |
| 426 |
The #version feature is not supported in |
| 427 |
.B less |
| 428 |
and |
| 429 |
.B lesskey |
| 430 |
before version 594. |
| 431 |
In those older versions, all #version lines are ignored. |
| 432 |
. |
| 433 |
.SH EXAMPLE |
| 434 |
The following input file sets the \-i and \-S options when |
| 435 |
.B less |
| 436 |
is run and, on version 595 and higher, adds a \-\-color option. |
| 437 |
.sp |
| 438 |
.nf |
| 439 |
#env |
| 440 |
## (Note that there must be a space at the end of the next line, |
| 441 |
## to separate the --color option from the -S option.) |
| 442 |
LESS = \-i\ \-S\ |
| 443 |
#version\ >=\ 595\ \ LESS\ +=\ \-\-color=Hkc |
| 444 |
.fi |
| 445 |
. |
| 446 |
.SH "SEE ALSO" |
| 447 |
.BR less (1) |
| 448 |
. |
| 449 |
.SH WARNINGS |
| 450 |
On MS-DOS and OS/2 systems, certain keys send a sequence of characters |
| 451 |
which start with a NUL character (0). |
| 452 |
This NUL character should be represented as \e340 in a lesskey file. |
| 453 |
. |
| 454 |
.SH COPYRIGHT |
| 455 |
Copyright (C) 1984-2024 Mark Nudelman |
| 456 |
.PP |
| 457 |
less is part of the GNU project and is free software. |
| 458 |
You can redistribute it and/or modify it |
| 459 |
under the terms of either |
| 460 |
(1) the GNU General Public License as published by |
| 461 |
the Free Software Foundation; or (2) the Less License. |
| 462 |
See the file README in the less distribution for more details |
| 463 |
regarding redistribution. |
| 464 |
You should have received a copy of the GNU General Public License |
| 465 |
along with the source for less; see the file COPYING. |
| 466 |
If not, write to the Free Software Foundation, 59 Temple Place, |
| 467 |
Suite 330, Boston, MA 02111-1307, USA. |
| 468 |
You should also have received a copy of the Less License; |
| 469 |
see the file LICENSE. |
| 470 |
.PP |
| 471 |
less is distributed in the hope that it will be useful, but |
| 472 |
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY |
| 473 |
or FITNESS FOR A PARTICULAR PURPOSE. |
| 474 |
See the GNU General Public License for more details. |
| 475 |
. |
| 476 |
.SH AUTHOR |
| 477 |
. |
| 478 |
Mark Nudelman |
| 479 |
.br |
| 480 |
Report bugs at https://github.com/gwsw/less/issues. |