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