Annotation of src/usr.bin/less/lesskey.1, Revision 1.3
1.3 ! jmc 1: .\" $OpenBSD: lesskey.1,v 1.2 2003/05/08 09:17:56 jmc Exp $
1.1 millert 2: .\"
3: .\" Copyright (C) 2000 Mark Nudelman
4: .\"
5: .\" lesskey is part of the GNU project and is free software;
6: .\" you can redistribute it and/or modify it
7: .\" under the terms of the GNU General Public License as published by
8: .\" the Free Software Foundation;
9: .\" either version 2, or (at your option) any later version.
10: .\"
11: .\" lesskey is distributed in the hope that it will be useful, but
12: .\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13: .\" or FITNESS FOR A PARTICULAR PURPOSE.
14: .\" See the GNU General Public License for more details.
15: .\"
16: .\" You should have received a copy of the GNU General Public License
17: .\" along with lesskey; see the file COPYING.
18: .\" If not, write to the Free Software Foundation, 59 Temple Place,
19: .\" Suite 330, Boston, MA 02111-1307, USA.
20: .\"
21: .Dd January 17, 2003
22: .Dt LESSKEY 1
23: .Os
24: .Sh NAME
25: .Nm lesskey
26: .Nd specify key bindings for less
27: .Sh SYNOPSIS
28: .Nm lesskey
29: .Op Fl o Ar output
30: .Op Fl -
31: .Op Ar input
32: .Nm lesskey
33: .Op Fl -output Ns No = Ns Ar output
34: .Op Fl -
35: .Op Ar input
36: .Nm lesskey
37: .Fl V
38: .Nm lesskey
39: .Fl -version
40: .Sh DESCRIPTION
41: .Nm
42: is used to specify a set of key bindings to be used by
43: .Xr less 1 .
44: The input file is a text file which describes the key bindings.
45: If the input file is "-", standard input is read.
46: If no input file is specified, a standard filename is used
47: as the name of the input file, which depends on the system being used:
48: On Unix systems, $HOME/.lesskey is used.
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.
52: The output file is a binary file which is used by less.
53: If no output file is specified, and the environment variable
54: .Ev LESSKEY
55: is set, the value of LESSKEY is used as the name of the output file.
56: Otherwise, a standard filename is used as the name of the output file,
57: which depends on the system being used:
58: On Unix and OS-9 systems, $HOME/.less is used.
59: .\" on MS-DOS systems, $HOME/_less is used;
60: .\" and on OS/2 systems, $HOME/less.ini is used,
61: .\" or $INIT/less.ini if $HOME is undefined.
62: If the output file already exists,
63: .Nm
64: will overwrite it.
65: .Pp
66: The -V or --version option causes
67: .Nm
68: to print its version number and immediately exit.
69: If -V or --version is present, other options and arguments are ignored.
70: .Pp
71: The input file consists of one or more sections.
72: Each section starts with a line that identifies the type of section.
73: Possible sections are:
74: .Bl -tag -width "#line-edit"
75: .It #command
76: Defines new command keys.
77: .It #line-edit
78: Defines new line-editing keys.
79: .It #env
80: Defines environment variables.
81: .El
82: .Pp
83: Blank lines and lines which start with a pound sign (#) are ignored,
84: except for the special section header lines.
85: .Sh COMMAND SECTION
86: The command section begins with the line
87: .Pp
88: .Dl #command
89: .Pp
90: If the command section is the first section in the file,
91: this line may be omitted.
92: The command section consists of lines of the form:
93: .Pp
94: .Xo
95: .Ar \& string No <whitespace>
96: .Ar action No [extra-string] <newline>
97: .Xc
98: .Pp
99: Whitespace is any sequence of one or more spaces and/or tabs.
100: The
101: .Ar string
102: is the command key(s) which invoke the action.
103: The
104: .Ar string
105: may be a single command key, or a sequence of up to 15 keys.
106: The
107: .Ar action
108: is the name of the less action, from the list below.
109: The characters in the
110: .Ar string
111: may appear literally, or be prefixed by a caret to indicate a control key.
112: A backslash followed by one to three octal digits may be used to
113: specify a character by its octal value.
114: A backslash followed by certain characters specifies input
115: characters as follows:
116: .Bl -tag -width Ds
117: .It \eb
118: BACKSPACE
119: .It \ee
120: ESCAPE
121: .It \en
122: NEWLINE
123: .It \er
124: RETURN
125: .It \et
126: TAB
127: .It \eku
128: UP ARROW
129: .It \ekd
130: DOWN ARROW
131: .It \ekr
132: RIGHT ARROW
133: .It \ekl
134: LEFT ARROW
135: .It \ekU
136: PAGE UP
137: .It \ekD
138: PAGE DOWN
139: .It \ekh
140: HOME
141: .It \eke
142: END
143: .It \ekx
144: DELETE
145: .El
146: .Pp
147: A backslash followed by any other character indicates that character is
148: to be taken literally.
149: Characters which must be preceded by backslash include
150: caret, space, tab and the backslash itself.
151: .Pp
152: An action may be followed by an "extra" string.
153: When such a command is entered while running less,
154: the action is performed, and then the extra
155: string is parsed, just as if it were typed in to less.
156: This feature can be used in certain cases to extend
157: the functionality of a command.
158: For example, see the "{" and ":t" commands in the example below.
159: The extra string has a special meaning for the "quit" action:
160: when less quits,
161: first character of the extra string is used as its exit status.
162: .Sh EXAMPLE
163: The following input file describes the set of
164: default command keys used by less:
165: .Pp
166: .Bd -literal -offset indent
167: #command
168: \er forw-line
169: \en forw-line
170: e forw-line
171: j forw-line
172: \ekd forw-line
173: ^E forw-line
174: ^N forw-line
175: k back-line
176: y back-line
177: ^Y back-line
178: ^K back-line
179: ^P back-line
180: J forw-line-force
181: K back-line-force
182: Y back-line-force
183: d forw-scroll
184: ^D forw-scroll
185: u back-scroll
186: ^U back-scroll
187: \e40 forw-screen
188: f forw-screen
189: ^F forw-screen
190: ^V forw-screen
191: \ekD forw-screen
192: b back-screen
193: ^B back-screen
194: \eev back-screen
195: \ekU back-screen
196: z forw-window
197: w back-window
198: \ee\e40 forw-screen-force
199: F forw-forever
200: R repaint-flush
201: r repaint
202: ^R repaint
203: ^L repaint
204: \eeu undo-hilite
205: g goto-line
206: \ekh goto-line
207: < goto-line
208: \ee< goto-line
209: p percent
210: % percent
211: \ee[ left-scroll
212: \ee] right-scroll
213: \ee( left-scroll
214: \ee) right-scroll
215: { forw-bracket {}
216: } back-bracket {}
217: ( forw-bracket ()
218: ) back-bracket ()
219: [ forw-bracket []
220: ] back-bracket []
221: \ee^F forw-bracket
222: \ee^B back-bracket
223: G goto-end
224: \ee> goto-end
225: > goto-end
226: \eke goto-end
227: = status
228: ^G status
229: :f status
230: / forw-search
231: ? back-search
232: \ee/ forw-search *
233: \ee? back-search *
234: n repeat-search
235: \een repeat-search-all
236: N reverse-search
237: \eeN reverse-search-all
238: m set-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: _ display-option
254: | pipe
255: v visual
256: ! shell
257: + firstcmd
258: H help
259: h help
260: V version
261: 0 digit
262: 1 digit
263: 2 digit
264: 3 digit
265: 4 digit
266: 5 digit
267: 6 digit
268: 7 digit
269: 8 digit
270: 9 digit
271: q quit
272: Q quit
273: :q quit
274: :Q quit
275: ZZ quit
276: .Ed
277: .Sh PRECEDENCE
278: Commands specified by
279: .Nm
280: take precedence over the default commands.
281: A default command key may be disabled by including it in the
282: input file with the action "invalid".
283: Alternatively, a key may be defined
284: to do nothing by using the action "noaction".
285: "noaction" is similar to "invalid", but
286: less will give an error beep for an "invalid" command,
287: but not for a "noaction" command.
288: In addition, ALL default commands may be disabled by
289: adding this control line to the input file:
290: .Pp
291: .Dl #stop
292: .Pp
293: This will cause all default commands to be ignored.
294: The #stop line should be the last line in that section of the file.
295: .Pp
296: Be aware that #stop can be dangerous.
297: Since all default commands are disabled, you must provide sufficient
298: commands before the #stop line to enable all necessary actions.
299: For example, failure to provide a "quit" command can lead to frustration.
300: .Sh LINE EDITING SECTION
301: The line-editing section begins with the line:
302: .Pp
303: .Dl #line-edit
304: .Pp
305: This section specifies new key bindings for the line editing commands,
306: in a manner similar to the way key bindings for
307: ordinary commands are specified in the #command section.
308: The line-editing section consists of a list of keys and actions,
309: one per line as in the example below.
310: .Sh EXAMPLE
311: The following input file describes the set of
312: default line-editing keys used by less:
313: .Pp
314: .Bd -literal -offset indent
315: #line-edit
316: \et forw-complete
317: \e17 back-complete
318: \ee\et back-complete
319: ^L expand
320: ^V literal
321: ^A literal
322: \eel right
323: \ekr right
324: \eeh left
325: \ekl left
326: \eeb word-left
327: \ee\ekl word-left
328: \eew word-right
329: \ee\ekr word-right
330: \eei insert
331: \eex delete
332: \ekx delete
333: \eeX word-delete
334: \eekx word-delete
335: \ee\eb word-backspace
336: \ee0 home
337: \ekh home
338: \ee$ end
339: \eke end
340: \eek up
341: \eku up
342: \eej down
343: .Ed
344: .Sh LESS ENVIRONMENT VARIABLES
345: The environment variable section begins with the line
346: .Pp
347: .Dl #env
348: .Pp
349: Following this line is a list of environment variable assignments.
350: Each line consists of an environment variable name, an equals sign (=)
351: and the value to be assigned to the environment variable.
352: Whitespace before and after the equals sign is ignored.
353: Variables assigned in this way are visible only to less.
354: If a variable is specified in the system environment and also in a
355: lesskey file, the value in the lesskey file takes precedence.
356: Although the lesskey file can be used to override variables set in the
357: environment, the main purpose of assigning variables in the lesskey file
358: is simply to have all less configuration information stored in one file.
359: .Sh EXAMPLE
360: The following input file sets the -i option whenever less is run,
361: and specifies the character set to be "latin1":
362: .Pp
363: .Bd -literal -offset indent
364: #env
365: LESS = -i
366: LESSCHARSET = latin1
367: .Ed
368: .Sh SEE ALSO
369: .Xr less 1
370: .Sh WARNINGS
371: It is not possible to specify special keys, such as uparrow,
372: in a keyboard-independent manner.
373: The only way to specify such keys is to specify the escape sequence
374: which a particular keyboard sends when such a key is pressed.
375: .\" .Pp
376: .\" On MS-DOS and OS/2 systems, certain keys send a sequence of characters
377: .\" which start with a NUL character (0).
378: .\" This NUL character should be represented as \e340 in a lesskey file.
379: .Sh COPYRIGHT
380: Copyright (C) 2000 Mark Nudelman
381: .Pp
382: lesskey is part of the GNU project and is free software;
383: you can redistribute it and/or modify it
384: under the terms of the GNU General Public License as published by
385: the Free Software Foundation;
386: either version 2, or (at your option) any later version.
387: .Pp
388: lesskey is distributed in the hope that it will be useful, but
389: WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
390: or FITNESS FOR A PARTICULAR PURPOSE.
391: See the GNU General Public License for more details.
392: .Pp
393: You should have received a copy of the GNU General Public License
394: along with lesskey; see the file COPYING.
395: If not, write to the Free Software Foundation, 59 Temple Place,
396: Suite 330, Boston, MA 02111-1307, USA.
1.2 jmc 397: .Sh AUTHORS
1.3 ! jmc 398: .An Mark Nudelman Aq markn@greenwoodsoftware.com
1.1 millert 399: .Pp
1.3 ! jmc 400: Send bug reports or comments to the above address or to
! 401: .Aq bug-less@gnu.org .