Annotation of src/usr.bin/less/lesskey.1, Revision 1.6
1.6 ! jmc 1: .\" $OpenBSD: lesskey.1,v 1.5 2003/08/18 17:21:45 millert 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
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.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
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
277: m set-mark
278: \' goto-mark
279: ^X^X goto-mark
280: E examine
281: :e examine
282: ^X^V examine
283: :n next-file
284: :p prev-file
285: t next-tag
286: T prev-tag
287: :x index-file
288: :d remove-file
289: - toggle-option
290: :t toggle-option t
291: s toggle-option o
292: _ display-option
293: | pipe
294: v visual
295: ! shell
296: + firstcmd
297: H help
298: h help
299: V version
300: 0 digit
301: 1 digit
302: 2 digit
303: 3 digit
304: 4 digit
305: 5 digit
306: 6 digit
307: 7 digit
308: 8 digit
309: 9 digit
310: q quit
311: Q quit
312: :q quit
313: :Q quit
314: ZZ quit
315: .Ed
316: .Sh PRECEDENCE
317: Commands specified by
318: .Nm
319: take precedence over the default commands.
320: A default command key may be disabled by including it in the
1.6 ! jmc 321: input file with the action
! 322: .Qq invalid .
1.1 millert 323: Alternatively, a key may be defined
1.6 ! jmc 324: to do nothing by using the action
! 325: .Qq noaction .
! 326: .Qq noaction
! 327: is similar to
! 328: .Qq invalid ,
! 329: but less will give an error beep for an
! 330: .Qq invalid
! 331: command, but not for a
! 332: .Qq noaction
! 333: command.
1.1 millert 334: In addition, ALL default commands may be disabled by
335: adding this control line to the input file:
336: .Pp
337: .Dl #stop
338: .Pp
339: This will cause all default commands to be ignored.
340: The #stop line should be the last line in that section of the file.
341: .Pp
342: Be aware that #stop can be dangerous.
343: Since all default commands are disabled, you must provide sufficient
344: commands before the #stop line to enable all necessary actions.
1.6 ! jmc 345: For example, failure to provide a
! 346: .Qq quit
! 347: command can lead to frustration.
1.1 millert 348: .Sh LINE EDITING SECTION
349: The line-editing section begins with the line:
350: .Pp
351: .Dl #line-edit
352: .Pp
353: This section specifies new key bindings for the line editing commands,
354: in a manner similar to the way key bindings for
355: ordinary commands are specified in the #command section.
356: The line-editing section consists of a list of keys and actions,
357: one per line as in the example below.
1.6 ! jmc 358: .Pp
1.1 millert 359: The following input file describes the set of
360: default line-editing keys used by less:
361: .Bd -literal -offset indent
362: #line-edit
363: \et forw-complete
364: \e17 back-complete
365: \ee\et back-complete
366: ^L expand
367: ^V literal
368: ^A literal
369: \eel right
370: \ekr right
371: \eeh left
372: \ekl left
373: \eeb word-left
374: \ee\ekl word-left
375: \eew word-right
376: \ee\ekr word-right
377: \eei insert
378: \eex delete
379: \ekx delete
380: \eeX word-delete
381: \eekx word-delete
382: \ee\eb word-backspace
383: \ee0 home
384: \ekh home
385: \ee$ end
386: \eke end
387: \eek up
388: \eku up
389: \eej down
390: .Ed
1.6 ! jmc 391: .Sh ENVIRONMENT SECTION
1.1 millert 392: The environment variable section begins with the line
393: .Pp
394: .Dl #env
395: .Pp
396: Following this line is a list of environment variable assignments.
1.6 ! jmc 397: Each line consists of an environment variable name, an equals sign
! 398: .Pq Sq =
1.1 millert 399: and the value to be assigned to the environment variable.
400: Whitespace before and after the equals sign is ignored.
401: Variables assigned in this way are visible only to less.
1.6 ! jmc 402: If environment variables are defined in more than one place,
! 403: variables defined in a local lesskey file take precedence over
! 404: variables defined in the system environment, which take precedence
! 405: over variables defined in the system-wide lesskey file.
1.1 millert 406: Although the lesskey file can be used to override variables set in the
407: environment, the main purpose of assigning variables in the lesskey file
408: is simply to have all less configuration information stored in one file.
1.6 ! jmc 409: .Pp
1.1 millert 410: The following input file sets the -i option whenever less is run,
1.6 ! jmc 411: and specifies the character set to be
! 412: .Qq latin1 :
1.1 millert 413: .Bd -literal -offset indent
414: #env
415: LESS = -i
416: LESSCHARSET = latin1
417: .Ed
1.6 ! jmc 418: .Sh ENVIRONMENT
! 419: .Bl -tag -width LESSKEY_SYSTEM -compact
! 420: .It Ev LESSKEY
! 421: Name of the default
! 422: .Nm
! 423: file.
! 424: .It Ev LESSKEY_SYSTEM
! 425: Name of the default system-wide
! 426: .Nm
! 427: file.
! 428: .El
! 429: .Sh FILES
! 430: .Bl -tag -width "$HOME/.lesskey" -compact
! 431: .It $HOME/.less
! 432: Default
! 433: .Nm
! 434: file.
! 435: .It $HOME/.lesskey
! 436: Default
! 437: .Nm
! 438: input file.
! 439: .It /etc/sysless
! 440: Default system-wide
! 441: .Nm
! 442: file.
! 443: .El
1.1 millert 444: .Sh SEE ALSO
445: .Xr less 1
1.6 ! jmc 446: .Sh AUTHORS
! 447: .An Mark Nudelman Aq markn@greenwoodsoftware.com
! 448: .Pp
! 449: Send bug reports or comments to the above address or to
! 450: .Aq bug\-less@gnu.org .
! 451: .Sh CAVEATS
1.1 millert 452: It is not possible to specify special keys, such as uparrow,
453: in a keyboard-independent manner.
454: The only way to specify such keys is to specify the escape sequence
455: which a particular keyboard sends when such a key is pressed.
456: .\" .Pp
457: .\" On MS-DOS and OS/2 systems, certain keys send a sequence of characters
458: .\" which start with a NUL character (0).
459: .\" This NUL character should be represented as \e340 in a lesskey file.
460: .Sh COPYRIGHT
461: Copyright (C) 2000 Mark Nudelman
462: .Pp
1.5 millert 463: Redistribution and use in source and binary forms, with or without
464: modification, are permitted provided that the following conditions
465: are met:
466: .Bl -enum -compact
467: .It
468: Redistributions of source code must retain the above copyright
469: notice, this list of conditions and the following disclaimer.
470: .It
471: Redistributions in binary form must reproduce the above copyright
1.6 ! jmc 472: notice in the documentation and/or other materials provided with
1.5 millert 473: the distribution.
474: .El
475: .Pp
476: THIS SOFTWARE IS PROVIDED BY THE AUTHOR
477: .Dq AS IS
478: AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1.6 ! jmc 479: IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
1.5 millert 480: PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE
1.6 ! jmc 481: FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
! 482: CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
! 483: OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
! 484: BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
! 485: WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
! 486: OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
1.5 millert 487: IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.