Debian Codegraph @

upstream/debian-unstable/man1/lesskey.1

raw
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.