Annotation of src/usr.bin/less/lesskey.1, Revision 1.1.1.1
1.1.1.1 ! shadchin 1: .\" $OpenBSD: lesskey.1,v 1.10 2013/07/16 00:07:52 schwarze Exp $
1.1 millert 2: .\"
1.1.1.1 ! shadchin 3: .\" Copyright (C) 2000-2012 Mark Nudelman
1.1 millert 4: .\"
1.1.1.1 ! shadchin 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.1.1.1 ! shadchin 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.
! 25: .Dd $Mdocdate: July 16 2013 $
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.1.1.1 ! shadchin 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.1.1.1 ! shadchin 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.1.1.1 ! shadchin 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.1.1.1 ! shadchin 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.1.1.1 ! shadchin 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.1.1.1 ! shadchin 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.1.1.1 ! shadchin 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.1.1.1 ! shadchin 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.1.1.1 ! shadchin 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.1.1.1 ! shadchin 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.1.1.1 ! shadchin 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.1.1.1 ! shadchin 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.1.1.1 ! shadchin 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.1.1.1 ! shadchin 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
1.1.1.1 ! shadchin 239: \eeF forw-until-hilite
1.1 millert 240: R repaint-flush
241: r repaint
242: ^R repaint
243: ^L repaint
244: \eeu undo-hilite
245: g goto-line
246: \ekh goto-line
247: < goto-line
248: \ee< goto-line
249: p percent
250: % percent
251: \ee[ left-scroll
252: \ee] right-scroll
253: \ee( left-scroll
254: \ee) right-scroll
255: { forw-bracket {}
256: } back-bracket {}
257: ( forw-bracket ()
258: ) back-bracket ()
259: [ forw-bracket []
260: ] back-bracket []
261: \ee^F forw-bracket
262: \ee^B back-bracket
263: G goto-end
264: \ee> goto-end
265: > goto-end
266: \eke goto-end
267: = status
268: ^G status
269: :f status
270: / forw-search
271: ? back-search
272: \ee/ forw-search *
273: \ee? back-search *
274: n repeat-search
275: \een repeat-search-all
276: N reverse-search
277: \eeN reverse-search-all
1.1.1.1 ! shadchin 278: & filter
1.1 millert 279: m set-mark
280: \' goto-mark
281: ^X^X goto-mark
282: E examine
283: :e examine
284: ^X^V examine
285: :n next-file
286: :p prev-file
287: t next-tag
288: T prev-tag
289: :x index-file
290: :d remove-file
291: - toggle-option
292: :t toggle-option t
293: s toggle-option o
294: _ display-option
295: | pipe
296: v visual
297: ! shell
298: + firstcmd
299: H help
300: h help
301: V version
302: 0 digit
303: 1 digit
304: 2 digit
305: 3 digit
306: 4 digit
307: 5 digit
308: 6 digit
309: 7 digit
310: 8 digit
311: 9 digit
312: q quit
313: Q quit
314: :q quit
315: :Q quit
316: ZZ quit
317: .Ed
318: .Sh PRECEDENCE
319: Commands specified by
320: .Nm
321: take precedence over the default commands.
322: A default command key may be disabled by including it in the
1.1.1.1 ! shadchin 323: input file with the action
! 324: .Qq invalid .
1.1 millert 325: Alternatively, a key may be defined
1.1.1.1 ! shadchin 326: to do nothing by using the action
! 327: .Qq noaction .
! 328: .Qq noaction
! 329: is similar to
! 330: .Qq invalid ,
! 331: but less will give an error beep for an
! 332: .Qq invalid
! 333: command, but not for a
! 334: .Qq noaction
! 335: command.
1.1 millert 336: In addition, ALL default commands may be disabled by
337: adding this control line to the input file:
338: .Pp
339: .Dl #stop
340: .Pp
341: This will cause all default commands to be ignored.
342: The #stop line should be the last line in that section of the file.
343: .Pp
344: Be aware that #stop can be dangerous.
345: Since all default commands are disabled, you must provide sufficient
346: commands before the #stop line to enable all necessary actions.
1.1.1.1 ! shadchin 347: For example, failure to provide a
! 348: .Qq quit
! 349: command can lead to frustration.
1.1 millert 350: .Sh LINE EDITING SECTION
351: The line-editing section begins with the line:
352: .Pp
353: .Dl #line-edit
354: .Pp
355: This section specifies new key bindings for the line editing commands,
356: in a manner similar to the way key bindings for
357: ordinary commands are specified in the #command section.
358: The line-editing section consists of a list of keys and actions,
359: one per line as in the example below.
1.1.1.1 ! shadchin 360: .Pp
1.1 millert 361: The following input file describes the set of
362: default line-editing keys used by less:
363: .Bd -literal -offset indent
364: #line-edit
365: \et forw-complete
366: \e17 back-complete
367: \ee\et back-complete
368: ^L expand
369: ^V literal
370: ^A literal
371: \eel right
372: \ekr right
373: \eeh left
374: \ekl left
375: \eeb word-left
376: \ee\ekl word-left
377: \eew word-right
378: \ee\ekr word-right
379: \eei insert
380: \eex delete
381: \ekx delete
382: \eeX word-delete
383: \eekx word-delete
384: \ee\eb word-backspace
385: \ee0 home
386: \ekh home
387: \ee$ end
388: \eke end
389: \eek up
390: \eku up
391: \eej down
1.1.1.1 ! shadchin 392: ^G abort
1.1 millert 393: .Ed
1.1.1.1 ! shadchin 394: .Sh ENVIRONMENT SECTION
1.1 millert 395: The environment variable section begins with the line
396: .Pp
397: .Dl #env
398: .Pp
399: Following this line is a list of environment variable assignments.
1.1.1.1 ! shadchin 400: Each line consists of an environment variable name, an equals sign
! 401: .Pq Sq =
1.1 millert 402: and the value to be assigned to the environment variable.
403: Whitespace before and after the equals sign is ignored.
404: Variables assigned in this way are visible only to less.
1.1.1.1 ! shadchin 405: If environment variables are defined in more than one place,
! 406: variables defined in a local lesskey file take precedence over
! 407: variables defined in the system environment, which take precedence
! 408: over variables defined in the system-wide lesskey file.
1.1 millert 409: Although the lesskey file can be used to override variables set in the
410: environment, the main purpose of assigning variables in the lesskey file
411: is simply to have all less configuration information stored in one file.
412: .Pp
1.1.1.1 ! shadchin 413: The following input file sets the -i option whenever less is run,
! 414: and specifies the character set to be
! 415: .Qq latin1 :
1.1 millert 416: .Bd -literal -offset indent
417: #env
418: LESS = -i
419: LESSCHARSET = latin1
420: .Ed
1.1.1.1 ! shadchin 421: .Sh ENVIRONMENT
! 422: .Bl -tag -width LESSKEY_SYSTEM -compact
! 423: .It Ev LESSKEY
! 424: Name of the default
! 425: .Nm
! 426: file.
! 427: .It Ev LESSKEY_SYSTEM
! 428: Name of the default system-wide
! 429: .Nm
! 430: file.
! 431: .El
! 432: .Sh FILES
! 433: .Bl -tag -width "$HOME/.lesskey" -compact
! 434: .It $HOME/.less
! 435: Default
! 436: .Nm
! 437: file.
! 438: .It $HOME/.lesskey
! 439: Default
! 440: .Nm
! 441: input file.
! 442: .It /etc/sysless
! 443: Default system-wide
! 444: .Nm
! 445: file.
! 446: .El
1.1 millert 447: .Sh SEE ALSO
448: .Xr less 1
1.1.1.1 ! shadchin 449: .Sh AUTHORS
! 450: .An Mark Nudelman
! 451: .Pp
! 452: Send bug reports or comments to
! 453: .Aq Mt bug\-less@gnu.org .
! 454: .\" .Sh CAVEATS
1.1 millert 455: .\" On MS-DOS and OS/2 systems, certain keys send a sequence of characters
456: .\" which start with a NUL character (0).
457: .\" This NUL character should be represented as \e340 in a lesskey file.