1.\" $OpenBSD: lesskey.1,v 1.18 2021/12/09 21:09:51 jmc Exp $ 2.\" 3.\" Copyright (C) 2000-2012 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: December 9 2021 $ 26.Dt LESSKEY 1 27.Os 28.Sh NAME 29.Nm lesskey 30.Nd customize 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 change the default key bindings of 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. 121.Pp 122The command section consists of lines of the form: 123.Bd -filled -offset indent 124.Ar keys 125.Ar action 126.Op Ar extra 127.Ed 128.Pp 129The three fields are separated by whitespace 130consisting of one or more spaces and/or tabs. 131.Pp 132The 133.Ar keys 134string consists of at least one and at most 15 keys. 135By typing it in 136.Xr less 1 , 137the 138.Ar action 139is invoked. 140The list of default key bindings given below 141also serves as a list of supported actions. 142.Pp 143Each of the 144.Ar keys 145can be specified in these forms: 146.Bl -bullet -offset indent 147.It 148a literal character 149.It 150a character prefixed by a caret to indicate a control key 151.It 152a backslash followed by one to three octal digits 153to specify a key by its octal value 154.It 155a backslash followed by certain characters 156to specify input characters as follows: 157.Pp 158.Bl -tag -width Ds -offset indent -compact 159.It \eb 160BACKSPACE 161.It \ee 162ESCAPE 163.It \en 164NEWLINE 165.It \er 166RETURN 167.It \et 168TAB 169.It \eku 170UP ARROW 171.It \ekd 172DOWN ARROW 173.It \ekr 174RIGHT ARROW 175.It \ekl 176LEFT ARROW 177.It \ekU 178PAGE UP 179.It \ekD 180PAGE DOWN 181.It \ekh 182HOME 183.It \eke 184END 185.It \ekx 186DELETE 187.El 188.It 189a backslash followed by any other character 190to indicate that character is to be taken literally. 191Characters which must be preceded by backslash include 192caret, space, tab, and the backslash itself. 193.El 194.Pp 195An action may be followed by an 196.Ar extra 197string. 198It is parsed, just as if it were typed into 199.Xr less 1 , 200after performing the 201.Ar action . 202This feature can be used in certain cases to extend 203the functionality of a command. 204For example, see the 205.Sq { 206and 207.Sq :t 208keys in the list of default bindings below. 209.Pp 210The 211.Ar extra 212string has a special meaning for the 213.Qq quit 214action: 215when 216.Xr less 1 217quits, 218first character of the 219.Ar extra 220string is used as its exit status. 221.Pp 222The following input file describes the set of 223default command keys used by 224.Xr less 1 : 225.Bd -literal -offset indent 226#command 227\er forw-line 228\en forw-line 229e forw-line 230j forw-line 231\ekd forw-line 232^E forw-line 233^N forw-line 234k back-line 235y back-line 236^Y back-line 237^K back-line 238^P back-line 239J forw-line-force 240K back-line-force 241Y back-line-force 242d forw-scroll 243^D forw-scroll 244u back-scroll 245^U back-scroll 246\e40 forw-screen 247f forw-screen 248^F forw-screen 249^V forw-screen 250\ekD forw-screen 251b back-screen 252^B back-screen 253\eev back-screen 254\ekU back-screen 255z forw-window 256w back-window 257\ee\e40 forw-screen-force 258F forw-forever 259\eeF forw-until-hilite 260R repaint-flush 261r repaint 262^R repaint 263^L repaint 264\eeu undo-hilite 265g goto-line 266\ekh goto-line 267< goto-line 268\ee< goto-line 269p percent 270% percent 271\ee[ left-scroll 272\ee] right-scroll 273\ee( left-scroll 274\ee) right-scroll 275{ forw-bracket {} 276} back-bracket {} 277( forw-bracket () 278) back-bracket () 279[ forw-bracket [] 280] back-bracket [] 281\ee^F forw-bracket 282\ee^B back-bracket 283G goto-end 284\ee> goto-end 285> goto-end 286\eke goto-end 287= status 288^G status 289:f status 290/ forw-search 291? back-search 292\ee/ forw-search * 293\ee? back-search * 294n repeat-search 295\een repeat-search-all 296N reverse-search 297\eeN reverse-search-all 298& filter 299m set-mark 300\(aq goto-mark 301^X^X goto-mark 302E examine 303:e examine 304^X^V examine 305:n next-file 306:p prev-file 307t next-tag 308T prev-tag 309:x index-file 310:d remove-file 311- toggle-option 312:t toggle-option t 313s toggle-option o 314_ display-option 315| pipe 316v visual 317+ firstcmd 318H help 319h help 320V version 3210 digit 3221 digit 3232 digit 3243 digit 3254 digit 3265 digit 3276 digit 3287 digit 3298 digit 3309 digit 331q quit 332Q quit 333:q quit 334:Q quit 335ZZ quit 336.Ed 337.Sh PRECEDENCE 338Commands specified by 339.Nm 340take precedence over the default commands. 341A default command key may be disabled by including it in the 342input file with the action 343.Qq invalid . 344Alternatively, a key may be defined 345to do nothing by using the action 346.Qq noaction . 347.Qq noaction 348is similar to 349.Qq invalid , 350but less will give an error beep for an 351.Qq invalid 352command, but not for a 353.Qq noaction 354command. 355In addition, ALL default commands may be disabled by 356adding this control line to the input file: 357.Pp 358.Dl #stop 359.Pp 360This will cause all default commands to be ignored. 361The #stop line should be the last line in that section of the file. 362.Pp 363Be aware that #stop can be dangerous. 364Since all default commands are disabled, you must provide sufficient 365commands before the #stop line to enable all necessary actions. 366For example, failure to provide a 367.Qq quit 368command can lead to frustration. 369.Sh LINE EDITING SECTION 370The line-editing section begins with the line: 371.Pp 372.Dl #line-edit 373.Pp 374This section specifies new key bindings for the line editing commands, 375in a manner similar to the way key bindings for 376ordinary commands are specified in the #command section. 377The line-editing section consists of a list of keys and actions, 378one per line as in the example below. 379.Pp 380The following input file describes the set of 381default line-editing keys used by less: 382.Bd -literal -offset indent 383#line-edit 384\et forw-complete 385\e17 back-complete 386\ee\et back-complete 387^L expand 388^V literal 389^A literal 390\eel right 391\ekr right 392\eeh left 393\ekl left 394\eeb word-left 395\ee\ekl word-left 396\eew word-right 397\ee\ekr word-right 398\eei insert 399\eex delete 400\ekx delete 401\eeX word-delete 402\eekx word-delete 403\ee\eb word-backspace 404\ee0 home 405\ekh home 406\ee$ end 407\eke end 408\eek up 409\eku up 410\eej down 411^G abort 412.Ed 413.Sh ENVIRONMENT SECTION 414The environment variable section begins with the line 415.Pp 416.Dl #env 417.Pp 418Following this line is a list of environment variable assignments. 419Each line consists of an environment variable name, an equals sign 420.Pq Sq = 421and the value to be assigned to the environment variable. 422Whitespace before and after the equals sign is ignored. 423Variables assigned in this way are visible only to less. 424If environment variables are defined in more than one place, 425variables defined in a local lesskey file take precedence over 426variables defined in the system environment, which take precedence 427over variables defined in the system-wide lesskey file. 428Although the lesskey file can be used to override variables set in the 429environment, the main purpose of assigning variables in the lesskey file 430is simply to have all less configuration information stored in one file. 431.Pp 432The following input file sets the -i option whenever less is run: 433.Bd -literal -offset indent 434#env 435LESS = -i 436.Ed 437.Sh ENVIRONMENT 438.Bl -tag -width LESSKEY_SYSTEM -compact 439.It Ev LESSKEY 440Name of the default 441.Nm 442file. 443.It Ev LESSKEY_SYSTEM 444Name of the default system-wide 445.Nm 446file. 447.El 448.Sh FILES 449.Bl -tag -width "$HOME/.lesskey" -compact 450.It $HOME/.less 451Default 452.Nm 453file. 454.It $HOME/.lesskey 455Default 456.Nm 457input file. 458.It /etc/sysless 459Default system-wide 460.Nm 461file. 462.El 463.Sh SEE ALSO 464.Xr less 1 465.Sh AUTHORS 466.An Mark Nudelman 467