Annotation of src/usr.bin/less/lesskey.1, Revision 1.17
1.17 ! schwarze 1: .\" $OpenBSD: lesskey.1,v 1.16 2019/06/02 06:53:11 bentley Exp $
1.1 millert 2: .\"
1.11 shadchin 3: .\" Copyright (C) 2000-2012 Mark Nudelman
1.1 millert 4: .\"
1.5 millert 5: .\" Redistribution and use in source and binary forms, with or without
6: .\" modification, are permitted provided that the following conditions
7: .\" are met:
8: .\" 1. Redistributions of source code must retain the above copyright
9: .\" notice, this list of conditions and the following disclaimer.
10: .\" 2. Redistributions in binary form must reproduce the above copyright
1.6 jmc 11: .\" notice in the documentation and/or other materials provided with
1.5 millert 12: .\" the distribution.
1.1 millert 13: .\"
1.5 millert 14: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY
15: .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1.6 jmc 16: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
1.5 millert 17: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE
1.6 jmc 18: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
19: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
20: .\" OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
21: .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
22: .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
23: .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
1.5 millert 24: .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.17 ! schwarze 25: .Dd $Mdocdate: June 2 2019 $
1.1 millert 26: .Dt LESSKEY 1
27: .Os
28: .Sh NAME
29: .Nm lesskey
30: .Nd specify key bindings for less
31: .Sh SYNOPSIS
32: .Nm lesskey
1.13 nicm 33: .Oo Fl o Ar output
34: .Pf " | " Fl -output Ns = Ns Ar output Oc
1.1 millert 35: .Op Ar input
36: .Nm lesskey
1.6 jmc 37: .Fl V | -version
1.1 millert 38: .Sh DESCRIPTION
39: .Nm
40: is used to specify a set of key bindings to be used by
41: .Xr less 1 .
42: The input file is a text file which describes the key bindings.
1.6 jmc 43: If the input file is
44: .Sq - ,
45: standard input is read.
1.1 millert 46: If no input file is specified, a standard filename is used
1.6 jmc 47: as the name of the input file; by default
48: .Pa $HOME/.lesskey .
1.1 millert 49: .\" on MS-DOS systems, $HOME/_lesskey is used;
50: .\" and on OS/2 systems $HOME/lesskey.ini is used,
51: .\" or $INIT/lesskey.ini if $HOME is undefined.
1.6 jmc 52: The output file is a binary file which is used by
53: .Xr less 1 .
1.1 millert 54: If no output file is specified, and the environment variable
55: .Ev LESSKEY
1.6 jmc 56: is set, the value of
57: .Ev LESSKEY
58: is used as the name of the output file.
59: Otherwise, a standard filename is used as the name of the output file;
60: by default
61: .Pa $HOME/.less
62: is used.
1.1 millert 63: .\" on MS-DOS systems, $HOME/_less is used;
64: .\" and on OS/2 systems, $HOME/less.ini is used,
65: .\" or $INIT/less.ini if $HOME is undefined.
66: If the output file already exists,
67: .Nm
68: will overwrite it.
69: .Pp
1.6 jmc 70: A system-wide lesskey file may also be set up to provide key bindings.
71: If a key is defined in both a local lesskey file and in the
72: system-wide file, key bindings in the local file take precedence over
73: those in the system-wide file.
74: If the environment variable
75: .Ev LESSKEY_SYSTEM
76: is set,
77: .Xr less 1
78: uses that as the name of the system-wide lesskey file.
79: Otherwise,
80: .Xr less 1
81: looks in a standard place for the system-wide lesskey file:
82: On
83: .Ox ,
84: the system-wide lesskey file is
85: .Pa /etc/sysless .
86: .Pp
87: The
88: .Fl V
89: or
90: .Fl -version
91: option causes
1.1 millert 92: .Nm
93: to print its version number and immediately exit.
1.6 jmc 94: If
95: .Fl V
96: or
97: .Fl -version
98: is present, other options and arguments are ignored.
1.1 millert 99: .Pp
100: The input file consists of one or more sections.
101: Each section starts with a line that identifies the type of section.
102: Possible sections are:
1.6 jmc 103: .Bl -tag -width "#line-edit" -offset indent
1.1 millert 104: .It #command
105: Defines new command keys.
106: .It #line-edit
107: Defines new line-editing keys.
108: .It #env
109: Defines environment variables.
110: .El
111: .Pp
1.13 nicm 112: Blank lines and lines which start with a pound sign (#) are ignored,
1.1 millert 113: except for the special section header lines.
114: .Sh COMMAND SECTION
115: The command section begins with the line
116: .Pp
117: .Dl #command
118: .Pp
119: If the command section is the first section in the file,
120: this line may be omitted.
1.17 ! schwarze 121: .Pp
1.1 millert 122: The command section consists of lines of the form:
1.6 jmc 123: .Bd -filled -offset indent
1.17 ! schwarze 124: .Ar keys
1.6 jmc 125: .Ar action
1.17 ! schwarze 126: .Op Ar extra
1.6 jmc 127: .Ed
1.1 millert 128: .Pp
1.17 ! schwarze 129: The three fields are separated by whitespace
! 130: consisting of one or more spaces and/or tabs.
! 131: .Pp
1.1 millert 132: The
1.17 ! schwarze 133: .Ar keys
! 134: string consists of at least one and at most 15 keys.
! 135: By typing it in
! 136: .Xr less 1 ,
! 137: the
1.1 millert 138: .Ar action
1.17 ! schwarze 139: is invoked.
! 140: The list of default key bindings given below
! 141: also serves as a list of supported actions.
! 142: .Pp
! 143: Each of the
! 144: .Ar keys
! 145: can be specified in these forms:
! 146: .Bl -bullet -offset indent
! 147: .It
! 148: a literal character
! 149: .It
! 150: a character prefixed by a caret to indicate a control key
! 151: .It
! 152: a backslash followed by one to three octal digits
! 153: to specify a key by its octal value
! 154: .It
! 155: a backslash followed by certain characters
! 156: to specify input characters as follows:
1.6 jmc 157: .Pp
158: .Bl -tag -width Ds -offset indent -compact
1.1 millert 159: .It \eb
160: BACKSPACE
161: .It \ee
162: ESCAPE
163: .It \en
164: NEWLINE
165: .It \er
166: RETURN
167: .It \et
168: TAB
169: .It \eku
170: UP ARROW
171: .It \ekd
172: DOWN ARROW
173: .It \ekr
174: RIGHT ARROW
175: .It \ekl
176: LEFT ARROW
177: .It \ekU
178: PAGE UP
179: .It \ekD
180: PAGE DOWN
181: .It \ekh
182: HOME
183: .It \eke
184: END
185: .It \ekx
186: DELETE
187: .El
1.17 ! schwarze 188: .It
! 189: a backslash followed by any other character
! 190: to indicate that character is to be taken literally.
1.1 millert 191: Characters which must be preceded by backslash include
1.17 ! schwarze 192: caret, space, tab, and the backslash itself.
! 193: .El
1.1 millert 194: .Pp
1.13 nicm 195: An action may be followed by an
1.17 ! schwarze 196: .Ar extra
1.13 nicm 197: string.
1.17 ! schwarze 198: It is parsed, just as if it were typed into
! 199: .Xr less 1 ,
! 200: after performing the
! 201: .Ar action .
1.1 millert 202: This feature can be used in certain cases to extend
203: the functionality of a command.
1.6 jmc 204: For example, see the
1.13 nicm 205: .Sq {
1.6 jmc 206: and
1.13 nicm 207: .Sq :t
1.17 ! schwarze 208: keys in the list of default bindings below.
! 209: .Pp
! 210: The
! 211: .Ar extra
! 212: string has a special meaning for the
1.13 nicm 213: .Qq quit
1.6 jmc 214: action:
1.17 ! schwarze 215: when
! 216: .Xr less 1
! 217: quits,
! 218: first character of the
! 219: .Ar extra
! 220: string is used as its exit status.
1.6 jmc 221: .Pp
1.1 millert 222: The following input file describes the set of
1.17 ! schwarze 223: default command keys used by
! 224: .Xr less 1 :
1.1 millert 225: .Bd -literal -offset indent
226: #command
227: \er forw-line
228: \en forw-line
229: e forw-line
230: j forw-line
231: \ekd forw-line
232: ^E forw-line
233: ^N forw-line
234: k back-line
235: y back-line
236: ^Y back-line
237: ^K back-line
238: ^P back-line
239: J forw-line-force
240: K back-line-force
241: Y back-line-force
242: d forw-scroll
243: ^D forw-scroll
244: u back-scroll
245: ^U back-scroll
246: \e40 forw-screen
247: f forw-screen
248: ^F forw-screen
249: ^V forw-screen
250: \ekD forw-screen
251: b back-screen
252: ^B back-screen
253: \eev back-screen
254: \ekU back-screen
255: z forw-window
256: w back-window
257: \ee\e40 forw-screen-force
258: F forw-forever
1.11 shadchin 259: \eeF forw-until-hilite
1.1 millert 260: R repaint-flush
261: r repaint
262: ^R repaint
263: ^L repaint
264: \eeu undo-hilite
265: g goto-line
266: \ekh goto-line
267: < goto-line
268: \ee< goto-line
269: p percent
270: % percent
271: \ee[ left-scroll
272: \ee] right-scroll
273: \ee( left-scroll
274: \ee) right-scroll
275: { forw-bracket {}
276: } back-bracket {}
277: ( forw-bracket ()
278: ) back-bracket ()
279: [ forw-bracket []
280: ] back-bracket []
281: \ee^F forw-bracket
282: \ee^B back-bracket
283: G goto-end
284: \ee> goto-end
285: > goto-end
286: \eke goto-end
287: = status
288: ^G status
289: :f status
290: / forw-search
291: ? back-search
292: \ee/ forw-search *
293: \ee? back-search *
294: n repeat-search
295: \een repeat-search-all
296: N reverse-search
297: \eeN reverse-search-all
1.9 shadchin 298: & filter
1.1 millert 299: m set-mark
1.16 bentley 300: \(aq goto-mark
1.1 millert 301: ^X^X goto-mark
302: E examine
303: :e examine
304: ^X^V examine
305: :n next-file
306: :p prev-file
307: t next-tag
308: T prev-tag
309: :x index-file
310: :d remove-file
311: - toggle-option
312: :t toggle-option t
313: s toggle-option o
314: _ display-option
315: | pipe
316: v visual
317: + firstcmd
318: H help
319: h help
320: V version
321: 0 digit
322: 1 digit
323: 2 digit
324: 3 digit
325: 4 digit
326: 5 digit
327: 6 digit
328: 7 digit
329: 8 digit
330: 9 digit
331: q quit
332: Q quit
333: :q quit
334: :Q quit
335: ZZ quit
336: .Ed
337: .Sh PRECEDENCE
338: Commands specified by
339: .Nm
340: take precedence over the default commands.
341: A default command key may be disabled by including it in the
1.6 jmc 342: input file with the action
1.13 nicm 343: .Qq invalid .
1.1 millert 344: Alternatively, a key may be defined
1.6 jmc 345: to do nothing by using the action
1.13 nicm 346: .Qq noaction .
347: .Qq noaction
1.6 jmc 348: is similar to
1.13 nicm 349: .Qq invalid ,
1.6 jmc 350: but less will give an error beep for an
1.13 nicm 351: .Qq invalid
1.6 jmc 352: command, but not for a
1.13 nicm 353: .Qq noaction
1.6 jmc 354: command.
1.13 nicm 355: In addition, ALL default commands may be disabled by
1.1 millert 356: adding this control line to the input file:
357: .Pp
358: .Dl #stop
359: .Pp
360: This will cause all default commands to be ignored.
1.13 nicm 361: The #stop line should be the last line in that section of the file.
1.1 millert 362: .Pp
1.13 nicm 363: Be aware that #stop can be dangerous.
1.1 millert 364: Since all default commands are disabled, you must provide sufficient
1.13 nicm 365: commands before the #stop line to enable all necessary actions.
1.6 jmc 366: For example, failure to provide a
1.13 nicm 367: .Qq quit
1.6 jmc 368: command can lead to frustration.
1.1 millert 369: .Sh LINE EDITING SECTION
370: The line-editing section begins with the line:
371: .Pp
372: .Dl #line-edit
373: .Pp
374: This section specifies new key bindings for the line editing commands,
375: in a manner similar to the way key bindings for
376: ordinary commands are specified in the #command section.
377: The line-editing section consists of a list of keys and actions,
378: one per line as in the example below.
1.6 jmc 379: .Pp
1.1 millert 380: The following input file describes the set of
381: default line-editing keys used by less:
382: .Bd -literal -offset indent
383: #line-edit
384: \et forw-complete
385: \e17 back-complete
386: \ee\et back-complete
387: ^L expand
388: ^V literal
389: ^A literal
390: \eel right
391: \ekr right
392: \eeh left
393: \ekl left
394: \eeb word-left
395: \ee\ekl word-left
396: \eew word-right
397: \ee\ekr word-right
398: \eei insert
399: \eex delete
400: \ekx delete
401: \eeX word-delete
402: \eekx word-delete
403: \ee\eb word-backspace
404: \ee0 home
405: \ekh home
406: \ee$ end
407: \eke end
408: \eek up
409: \eku up
410: \eej down
1.9 shadchin 411: ^G abort
1.1 millert 412: .Ed
1.6 jmc 413: .Sh ENVIRONMENT SECTION
1.1 millert 414: The environment variable section begins with the line
415: .Pp
416: .Dl #env
417: .Pp
418: Following this line is a list of environment variable assignments.
1.6 jmc 419: Each line consists of an environment variable name, an equals sign
420: .Pq Sq =
1.1 millert 421: and the value to be assigned to the environment variable.
422: Whitespace before and after the equals sign is ignored.
423: Variables assigned in this way are visible only to less.
1.6 jmc 424: If environment variables are defined in more than one place,
425: variables defined in a local lesskey file take precedence over
426: variables defined in the system environment, which take precedence
427: over variables defined in the system-wide lesskey file.
1.1 millert 428: Although the lesskey file can be used to override variables set in the
429: environment, the main purpose of assigning variables in the lesskey file
430: is simply to have all less configuration information stored in one file.
1.6 jmc 431: .Pp
1.15 tb 432: The following input file sets the -i option whenever less is run:
1.1 millert 433: .Bd -literal -offset indent
434: #env
435: LESS = -i
436: .Ed
1.6 jmc 437: .Sh ENVIRONMENT
438: .Bl -tag -width LESSKEY_SYSTEM -compact
439: .It Ev LESSKEY
440: Name of the default
441: .Nm
442: file.
443: .It Ev LESSKEY_SYSTEM
444: Name of the default system-wide
445: .Nm
446: file.
447: .El
448: .Sh FILES
449: .Bl -tag -width "$HOME/.lesskey" -compact
1.13 nicm 450: .It $HOME/.less
1.6 jmc 451: Default
452: .Nm
453: file.
1.13 nicm 454: .It $HOME/.lesskey
1.6 jmc 455: Default
456: .Nm
457: input file.
1.13 nicm 458: .It /etc/sysless
1.6 jmc 459: Default system-wide
460: .Nm
461: file.
462: .El
1.1 millert 463: .Sh SEE ALSO
464: .Xr less 1
1.6 jmc 465: .Sh AUTHORS
1.11 shadchin 466: .An Mark Nudelman