Debian Codegraph @

upstream/mageia-cauldron/man1/lesskey.1

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