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