Annotation of src/usr.bin/less/lesskey.1, Revision 1.4
1.4 ! jmc 1: .\" $OpenBSD: lesskey.1,v 1.3 2003/06/10 09:12:10 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: .Bd -literal -offset indent
166: #command
167: \er forw-line
168: \en forw-line
169: e forw-line
170: j forw-line
171: \ekd forw-line
172: ^E forw-line
173: ^N forw-line
174: k back-line
175: y back-line
176: ^Y back-line
177: ^K back-line
178: ^P back-line
179: J forw-line-force
180: K back-line-force
181: Y back-line-force
182: d forw-scroll
183: ^D forw-scroll
184: u back-scroll
185: ^U back-scroll
186: \e40 forw-screen
187: f forw-screen
188: ^F forw-screen
189: ^V forw-screen
190: \ekD forw-screen
191: b back-screen
192: ^B back-screen
193: \eev back-screen
194: \ekU back-screen
195: z forw-window
196: w back-window
197: \ee\e40 forw-screen-force
198: F forw-forever
199: R repaint-flush
200: r repaint
201: ^R repaint
202: ^L repaint
203: \eeu undo-hilite
204: g goto-line
205: \ekh goto-line
206: < goto-line
207: \ee< goto-line
208: p percent
209: % percent
210: \ee[ left-scroll
211: \ee] right-scroll
212: \ee( left-scroll
213: \ee) right-scroll
214: { forw-bracket {}
215: } back-bracket {}
216: ( forw-bracket ()
217: ) back-bracket ()
218: [ forw-bracket []
219: ] back-bracket []
220: \ee^F forw-bracket
221: \ee^B back-bracket
222: G goto-end
223: \ee> goto-end
224: > goto-end
225: \eke goto-end
226: = status
227: ^G status
228: :f status
229: / forw-search
230: ? back-search
231: \ee/ forw-search *
232: \ee? back-search *
233: n repeat-search
234: \een repeat-search-all
235: N reverse-search
236: \eeN reverse-search-all
237: m set-mark
238: \' goto-mark
239: ^X^X goto-mark
240: E examine
241: :e examine
242: ^X^V examine
243: :n next-file
244: :p prev-file
245: t next-tag
246: T prev-tag
247: :x index-file
248: :d remove-file
249: - toggle-option
250: :t toggle-option t
251: s toggle-option o
252: _ display-option
253: | pipe
254: v visual
255: ! shell
256: + firstcmd
257: H help
258: h help
259: V version
260: 0 digit
261: 1 digit
262: 2 digit
263: 3 digit
264: 4 digit
265: 5 digit
266: 6 digit
267: 7 digit
268: 8 digit
269: 9 digit
270: q quit
271: Q quit
272: :q quit
273: :Q quit
274: ZZ quit
275: .Ed
276: .Sh PRECEDENCE
277: Commands specified by
278: .Nm
279: take precedence over the default commands.
280: A default command key may be disabled by including it in the
281: input file with the action "invalid".
282: Alternatively, a key may be defined
283: to do nothing by using the action "noaction".
284: "noaction" is similar to "invalid", but
285: less will give an error beep for an "invalid" command,
286: but not for a "noaction" command.
287: In addition, ALL default commands may be disabled by
288: adding this control line to the input file:
289: .Pp
290: .Dl #stop
291: .Pp
292: This will cause all default commands to be ignored.
293: The #stop line should be the last line in that section of the file.
294: .Pp
295: Be aware that #stop can be dangerous.
296: Since all default commands are disabled, you must provide sufficient
297: commands before the #stop line to enable all necessary actions.
298: For example, failure to provide a "quit" command can lead to frustration.
299: .Sh LINE EDITING SECTION
300: The line-editing section begins with the line:
301: .Pp
302: .Dl #line-edit
303: .Pp
304: This section specifies new key bindings for the line editing commands,
305: in a manner similar to the way key bindings for
306: ordinary commands are specified in the #command section.
307: The line-editing section consists of a list of keys and actions,
308: one per line as in the example below.
309: .Sh EXAMPLE
310: The following input file describes the set of
311: default line-editing keys used by less:
312: .Bd -literal -offset indent
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: .Ed
342: .Sh LESS ENVIRONMENT VARIABLES
343: The environment variable section begins with the line
344: .Pp
345: .Dl #env
346: .Pp
347: Following this line is a list of environment variable assignments.
348: Each line consists of an environment variable name, an equals sign (=)
349: and the value to be assigned to the environment variable.
350: Whitespace before and after the equals sign is ignored.
351: Variables assigned in this way are visible only to less.
352: If a variable is specified in the system environment and also in a
353: lesskey file, the value in the lesskey file takes precedence.
354: Although the lesskey file can be used to override variables set in the
355: environment, the main purpose of assigning variables in the lesskey file
356: is simply to have all less configuration information stored in one file.
357: .Sh EXAMPLE
358: The following input file sets the -i option whenever less is run,
359: and specifies the character set to be "latin1":
360: .Bd -literal -offset indent
361: #env
362: LESS = -i
363: LESSCHARSET = latin1
364: .Ed
365: .Sh SEE ALSO
366: .Xr less 1
367: .Sh WARNINGS
368: It is not possible to specify special keys, such as uparrow,
369: in a keyboard-independent manner.
370: The only way to specify such keys is to specify the escape sequence
371: which a particular keyboard sends when such a key is pressed.
372: .\" .Pp
373: .\" On MS-DOS and OS/2 systems, certain keys send a sequence of characters
374: .\" which start with a NUL character (0).
375: .\" This NUL character should be represented as \e340 in a lesskey file.
376: .Sh COPYRIGHT
377: Copyright (C) 2000 Mark Nudelman
378: .Pp
379: lesskey is part of the GNU project and is free software;
380: you can redistribute it and/or modify it
381: under the terms of the GNU General Public License as published by
382: the Free Software Foundation;
383: either version 2, or (at your option) any later version.
384: .Pp
385: lesskey is distributed in the hope that it will be useful, but
386: WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
387: or FITNESS FOR A PARTICULAR PURPOSE.
388: See the GNU General Public License for more details.
389: .Pp
390: You should have received a copy of the GNU General Public License
391: along with lesskey; see the file COPYING.
392: If not, write to the Free Software Foundation, 59 Temple Place,
393: Suite 330, Boston, MA 02111-1307, USA.
1.2 jmc 394: .Sh AUTHORS
1.3 jmc 395: .An Mark Nudelman Aq markn@greenwoodsoftware.com
1.1 millert 396: .Pp
1.3 jmc 397: Send bug reports or comments to the above address or to
398: .Aq bug-less@gnu.org .