1.\" $OpenBSD: lesskey.1,v 1.8 2007/05/31 19:20:12 jmc Exp $ 2.\" 3.\" Copyright (C) 2000 Mark Nudelman 4.\" 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. 13.\" 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: May 31 2007 $ 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.Oo Fl o Ar output 34.Pf " | " Fl -output Ns = Ns Ar output Oc 35.Op Ar input 36.Nm lesskey 37.Fl V | -version 38.Sh DESCRIPTION 39.Nm 40is used to specify a set of key bindings to be used by 41.Xr less 1 . 42The input file is a text file which describes the key bindings. 43If the input file is 44.Sq - , 45standard input is read. 46If no input file is specified, a standard filename is used 47as the name of the input file; by default 48.Pa $HOME/.lesskey . 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. 52The output file is a binary file which is used by 53.Xr less 1 . 54If no output file is specified, and the environment variable 55.Ev LESSKEY 56is set, the value of 57.Ev LESSKEY 58is used as the name of the output file. 59Otherwise, a standard filename is used as the name of the output file; 60by default 61.Pa $HOME/.less 62is 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. 66If the output file already exists, 67.Nm 68will overwrite it. 69.Pp 70A system-wide lesskey file may also be set up to provide key bindings. 71If a key is defined in both a local lesskey file and in the 72system-wide file, key bindings in the local file take precedence over 73those in the system-wide file. 74If the environment variable 75.Ev LESSKEY_SYSTEM 76is set, 77.Xr less 1 78uses that as the name of the system-wide lesskey file. 79Otherwise, 80.Xr less 1 81looks in a standard place for the system-wide lesskey file: 82On 83.Ox , 84the system-wide lesskey file is 85.Pa /etc/sysless . 86.Pp 87The 88.Fl V 89or 90.Fl -version 91option causes 92.Nm 93to print its version number and immediately exit. 94If 95.Fl V 96or 97.Fl -version 98is present, other options and arguments are ignored. 99.Pp 100The input file consists of one or more sections. 101Each section starts with a line that identifies the type of section. 102Possible sections are: 103.Bl -tag -width "#line-edit" -offset indent 104.It #command 105Defines new command keys. 106.It #line-edit 107Defines new line-editing keys. 108.It #env 109Defines environment variables. 110.El 111.Pp 112Blank lines and lines which start with a pound sign (#) are ignored, 113except for the special section header lines. 114.Sh COMMAND SECTION 115The command section begins with the line 116.Pp 117.Dl #command 118.Pp 119If the command section is the first section in the file, 120this line may be omitted. 121The command section consists of lines of the form: 122.Bd -filled -offset indent 123.Ar string 124.Aq whitespace 125.Ar action 126.Bq extra-string 127.Aq newline 128.Ed 129.Pp 130Whitespace is any sequence of one or more spaces and/or tabs. 131The 132.Ar string 133is the command key(s) which invoke the action. 134The 135.Ar string 136may be a single command key, or a sequence of up to 15 keys. 137The 138.Ar action 139is the name of the less action, from the list below. 140The characters in the 141.Ar string 142may appear literally, or be prefixed by a caret to indicate a control key. 143A backslash followed by one to three octal digits may be used to 144specify a character by its octal value. 145A backslash followed by certain characters specifies input 146characters as follows: 147.Pp 148.Bl -tag -width Ds -offset indent -compact 149.It \eb 150BACKSPACE 151.It \ee 152ESCAPE 153.It \en 154NEWLINE 155.It \er 156RETURN 157.It \et 158TAB 159.It \eku 160UP ARROW 161.It \ekd 162DOWN ARROW 163.It \ekr 164RIGHT ARROW 165.It \ekl 166LEFT ARROW 167.It \ekU 168PAGE UP 169.It \ekD 170PAGE DOWN 171.It \ekh 172HOME 173.It \eke 174END 175.It \ekx 176DELETE 177.El 178.Pp 179A backslash followed by any other character indicates that character is 180to be taken literally. 181Characters which must be preceded by backslash include 182caret, space, tab and the backslash itself. 183.Pp 184An action may be followed by an 185.Qq extra 186string. 187When such a command is entered while running less, 188the action is performed, and then the extra 189string is parsed, just as if it were typed in to less. 190This feature can be used in certain cases to extend 191the functionality of a command. 192For example, see the 193.Sq { 194and 195.Sq :t 196commands in the example below. 197The extra string has a special meaning for the 198.Qq quit 199action: 200when less quits, 201first character of the extra string is used as its exit status. 202.Pp 203The following input file describes the set of 204default command keys used by less: 205.Bd -literal -offset indent 206#command 207\er forw-line 208\en forw-line 209e forw-line 210j forw-line 211\ekd forw-line 212^E forw-line 213^N forw-line 214k back-line 215y back-line 216^Y back-line 217^K back-line 218^P back-line 219J forw-line-force 220K back-line-force 221Y back-line-force 222d forw-scroll 223^D forw-scroll 224u back-scroll 225^U back-scroll 226\e40 forw-screen 227f forw-screen 228^F forw-screen 229^V forw-screen 230\ekD forw-screen 231b back-screen 232^B back-screen 233\eev back-screen 234\ekU back-screen 235z forw-window 236w back-window 237\ee\e40 forw-screen-force 238F forw-forever 239R repaint-flush 240r repaint 241^R repaint 242^L repaint 243\eeu undo-hilite 244g goto-line 245\ekh goto-line 246< goto-line 247\ee< goto-line 248p 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 262G 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 * 273n repeat-search 274\een repeat-search-all 275N reverse-search 276\eeN reverse-search-all 277m set-mark 278\' goto-mark 279^X^X goto-mark 280E examine 281:e examine 282^X^V examine 283:n next-file 284:p prev-file 285t next-tag 286T prev-tag 287:x index-file 288:d remove-file 289- toggle-option 290:t toggle-option t 291s toggle-option o 292_ display-option 293| pipe 294v visual 295! shell 296+ firstcmd 297H help 298h help 299V version 3000 digit 3011 digit 3022 digit 3033 digit 3044 digit 3055 digit 3066 digit 3077 digit 3088 digit 3099 digit 310q quit 311Q quit 312:q quit 313:Q quit 314ZZ quit 315.Ed 316.Sh PRECEDENCE 317Commands specified by 318.Nm 319take precedence over the default commands. 320A default command key may be disabled by including it in the 321input file with the action 322.Qq invalid . 323Alternatively, a key may be defined 324to do nothing by using the action 325.Qq noaction . 326.Qq noaction 327is similar to 328.Qq invalid , 329but less will give an error beep for an 330.Qq invalid 331command, but not for a 332.Qq noaction 333command. 334In addition, ALL default commands may be disabled by 335adding this control line to the input file: 336.Pp 337.Dl #stop 338.Pp 339This will cause all default commands to be ignored. 340The #stop line should be the last line in that section of the file. 341.Pp 342Be aware that #stop can be dangerous. 343Since all default commands are disabled, you must provide sufficient 344commands before the #stop line to enable all necessary actions. 345For example, failure to provide a 346.Qq quit 347command can lead to frustration. 348.Sh LINE EDITING SECTION 349The line-editing section begins with the line: 350.Pp 351.Dl #line-edit 352.Pp 353This section specifies new key bindings for the line editing commands, 354in a manner similar to the way key bindings for 355ordinary commands are specified in the #command section. 356The line-editing section consists of a list of keys and actions, 357one per line as in the example below. 358.Pp 359The following input file describes the set of 360default 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 391.Sh ENVIRONMENT SECTION 392The environment variable section begins with the line 393.Pp 394.Dl #env 395.Pp 396Following this line is a list of environment variable assignments. 397Each line consists of an environment variable name, an equals sign 398.Pq Sq = 399and the value to be assigned to the environment variable. 400Whitespace before and after the equals sign is ignored. 401Variables assigned in this way are visible only to less. 402If environment variables are defined in more than one place, 403variables defined in a local lesskey file take precedence over 404variables defined in the system environment, which take precedence 405over variables defined in the system-wide lesskey file. 406Although the lesskey file can be used to override variables set in the 407environment, the main purpose of assigning variables in the lesskey file 408is simply to have all less configuration information stored in one file. 409.Pp 410The following input file sets the -i option whenever less is run, 411and specifies the character set to be 412.Qq latin1 : 413.Bd -literal -offset indent 414#env 415LESS = -i 416LESSCHARSET = latin1 417.Ed 418.Sh ENVIRONMENT 419.Bl -tag -width LESSKEY_SYSTEM -compact 420.It Ev LESSKEY 421Name of the default 422.Nm 423file. 424.It Ev LESSKEY_SYSTEM 425Name of the default system-wide 426.Nm 427file. 428.El 429.Sh FILES 430.Bl -tag -width "$HOME/.lesskey" -compact 431.It $HOME/.less 432Default 433.Nm 434file. 435.It $HOME/.lesskey 436Default 437.Nm 438input file. 439.It /etc/sysless 440Default system-wide 441.Nm 442file. 443.El 444.Sh SEE ALSO 445.Xr less 1 446.Sh AUTHORS 447.An Mark Nudelman Aq markn@greenwoodsoftware.com 448.Pp 449Send bug reports or comments to the above address or to 450.Aq bug\-less@gnu.org . 451.Sh CAVEATS 452It is not possible to specify special keys, such as uparrow, 453in a keyboard-independent manner. 454The only way to specify such keys is to specify the escape sequence 455which 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