Annotation of src/usr.bin/less/lesskey.1, Revision 1.10
1.10 ! schwarze 1: .\" $OpenBSD: lesskey.1,v 1.9 2011/09/16 18:12:09 shadchin Exp $
1.1 millert 2: .\"
1.9 shadchin 3: .\" Copyright (C) 2000-2011 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.10 ! schwarze 25: .Dd $Mdocdate: September 16 2011 $
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.6 jmc 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
112: Blank lines and lines which start with a pound sign (#) are ignored,
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.
121: The command section consists of lines of the form:
1.6 jmc 122: .Bd -filled -offset indent
123: .Ar string
124: .Aq whitespace
125: .Ar action
126: .Bq extra-string
127: .Aq newline
128: .Ed
1.1 millert 129: .Pp
130: Whitespace is any sequence of one or more spaces and/or tabs.
131: The
132: .Ar string
133: is the command key(s) which invoke the action.
134: The
135: .Ar string
136: may be a single command key, or a sequence of up to 15 keys.
137: The
138: .Ar action
139: is the name of the less action, from the list below.
140: The characters in the
141: .Ar string
142: may appear literally, or be prefixed by a caret to indicate a control key.
143: A backslash followed by one to three octal digits may be used to
144: specify a character by its octal value.
145: A backslash followed by certain characters specifies input
146: characters as follows:
1.6 jmc 147: .Pp
148: .Bl -tag -width Ds -offset indent -compact
1.1 millert 149: .It \eb
150: BACKSPACE
151: .It \ee
152: ESCAPE
153: .It \en
154: NEWLINE
155: .It \er
156: RETURN
157: .It \et
158: TAB
159: .It \eku
160: UP ARROW
161: .It \ekd
162: DOWN ARROW
163: .It \ekr
164: RIGHT ARROW
165: .It \ekl
166: LEFT ARROW
167: .It \ekU
168: PAGE UP
169: .It \ekD
170: PAGE DOWN
171: .It \ekh
172: HOME
173: .It \eke
174: END
175: .It \ekx
176: DELETE
177: .El
178: .Pp
179: A backslash followed by any other character indicates that character is
180: to be taken literally.
181: Characters which must be preceded by backslash include
182: caret, space, tab and the backslash itself.
183: .Pp
1.6 jmc 184: An action may be followed by an
185: .Qq extra
186: string.
1.1 millert 187: When such a command is entered while running less,
188: the action is performed, and then the extra
189: string is parsed, just as if it were typed in to less.
190: This feature can be used in certain cases to extend
191: the functionality of a command.
1.6 jmc 192: For example, see the
193: .Sq {
194: and
195: .Sq :t
196: commands in the example below.
197: The extra string has a special meaning for the
198: .Qq quit
199: action:
1.1 millert 200: when less quits,
201: first character of the extra string is used as its exit status.
1.6 jmc 202: .Pp
1.1 millert 203: The following input file describes the set of
204: default command keys used by less:
205: .Bd -literal -offset indent
206: #command
207: \er forw-line
208: \en forw-line
209: e forw-line
210: j forw-line
211: \ekd forw-line
212: ^E forw-line
213: ^N forw-line
214: k back-line
215: y back-line
216: ^Y back-line
217: ^K back-line
218: ^P back-line
219: J forw-line-force
220: K back-line-force
221: Y back-line-force
222: d forw-scroll
223: ^D forw-scroll
224: u back-scroll
225: ^U back-scroll
226: \e40 forw-screen
227: f forw-screen
228: ^F forw-screen
229: ^V forw-screen
230: \ekD forw-screen
231: b back-screen
232: ^B back-screen
233: \eev back-screen
234: \ekU back-screen
235: z forw-window
236: w back-window
237: \ee\e40 forw-screen-force
238: F forw-forever
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
323: .Qq invalid .
1.1 millert 324: Alternatively, a key may be defined
1.6 jmc 325: to do nothing by using the action
326: .Qq noaction .
327: .Qq noaction
328: is similar to
329: .Qq invalid ,
330: but less will give an error beep for an
331: .Qq invalid
332: command, but not for a
333: .Qq noaction
334: command.
1.1 millert 335: In addition, ALL default commands may be disabled by
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.
341: The #stop line should be the last line in that section of the file.
342: .Pp
343: Be aware that #stop can be dangerous.
344: Since all default commands are disabled, you must provide sufficient
345: commands before the #stop line to enable all necessary actions.
1.6 jmc 346: For example, failure to provide a
347: .Qq quit
348: command can lead to frustration.
1.1 millert 349: .Sh LINE EDITING SECTION
350: The line-editing section begins with the line:
351: .Pp
352: .Dl #line-edit
353: .Pp
354: This section specifies new key bindings for the line editing commands,
355: in a manner similar to the way key bindings for
356: ordinary commands are specified in the #command section.
357: The line-editing section consists of a list of keys and actions,
358: one per line as in the example below.
1.6 jmc 359: .Pp
1.1 millert 360: The following input file describes the set of
361: default line-editing keys used by less:
362: .Bd -literal -offset indent
363: #line-edit
364: \et forw-complete
365: \e17 back-complete
366: \ee\et back-complete
367: ^L expand
368: ^V literal
369: ^A literal
370: \eel right
371: \ekr right
372: \eeh left
373: \ekl left
374: \eeb word-left
375: \ee\ekl word-left
376: \eew word-right
377: \ee\ekr word-right
378: \eei insert
379: \eex delete
380: \ekx delete
381: \eeX word-delete
382: \eekx word-delete
383: \ee\eb word-backspace
384: \ee0 home
385: \ekh home
386: \ee$ end
387: \eke end
388: \eek up
389: \eku up
390: \eej down
1.9 shadchin 391: ^G abort
1.1 millert 392: .Ed
1.6 jmc 393: .Sh ENVIRONMENT SECTION
1.1 millert 394: The environment variable section begins with the line
395: .Pp
396: .Dl #env
397: .Pp
398: Following this line is a list of environment variable assignments.
1.6 jmc 399: Each line consists of an environment variable name, an equals sign
400: .Pq Sq =
1.1 millert 401: and the value to be assigned to the environment variable.
402: Whitespace before and after the equals sign is ignored.
403: Variables assigned in this way are visible only to less.
1.6 jmc 404: If environment variables are defined in more than one place,
405: variables defined in a local lesskey file take precedence over
406: variables defined in the system environment, which take precedence
407: over variables defined in the system-wide lesskey file.
1.1 millert 408: Although the lesskey file can be used to override variables set in the
409: environment, the main purpose of assigning variables in the lesskey file
410: is simply to have all less configuration information stored in one file.
1.6 jmc 411: .Pp
1.1 millert 412: The following input file sets the -i option whenever less is run,
1.6 jmc 413: and specifies the character set to be
414: .Qq latin1 :
1.1 millert 415: .Bd -literal -offset indent
416: #env
417: LESS = -i
418: LESSCHARSET = latin1
419: .Ed
1.6 jmc 420: .Sh ENVIRONMENT
421: .Bl -tag -width LESSKEY_SYSTEM -compact
422: .It Ev LESSKEY
423: Name of the default
424: .Nm
425: file.
426: .It Ev LESSKEY_SYSTEM
427: Name of the default system-wide
428: .Nm
429: file.
430: .El
431: .Sh FILES
432: .Bl -tag -width "$HOME/.lesskey" -compact
433: .It $HOME/.less
434: Default
435: .Nm
436: file.
437: .It $HOME/.lesskey
438: Default
439: .Nm
440: input file.
441: .It /etc/sysless
442: Default system-wide
443: .Nm
444: file.
445: .El
1.1 millert 446: .Sh SEE ALSO
447: .Xr less 1
1.6 jmc 448: .Sh AUTHORS
1.10 ! schwarze 449: .An Mark Nudelman Aq Mt markn@greenwoodsoftware.com
1.6 jmc 450: .Pp
451: Send bug reports or comments to the above address or to
1.10 ! schwarze 452: .Aq Mt bug\-less@gnu.org .
1.9 shadchin 453: .\" .Sh CAVEATS
1.1 millert 454: .\" On MS-DOS and OS/2 systems, certain keys send a sequence of characters
455: .\" which start with a NUL character (0).
456: .\" This NUL character should be represented as \e340 in a lesskey file.