bin/less/lesskey/lesskey.1

   1 .\"     $OpenBSD: lesskey.1,v 1.15 2015/11/23 12:56:13 tb 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: November 23 2015 $
  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
  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.
  43 If the input file is
  44 .Sq - ,
  45 standard input is read.
  46 If no input file is specified, a standard filename is used
  47 as 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.
  52 The output file is a binary file which is used by
  53 .Xr less 1 .
  54 If no output file is specified, and the environment variable
  55 .Ev LESSKEY
  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.
  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 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
  92 .Nm
  93 to print its version number and immediately exit.
  94 If
  95 .Fl V
  96 or
  97 .Fl -version
  98 is present, other options and arguments are ignored.
  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:
 103 .Bl -tag -width "#line-edit" -offset indent
 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:
 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
 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:
 147 .Pp
 148 .Bl -tag -width Ds -offset indent -compact
 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
 184 An action may be followed by an
 185 .Qq extra
 186 string.
 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.
 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:
 200 when less quits,
 201 first character of the extra string is used as its exit status.
 202 .Pp
 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 \eeF    forw-until-hilite
 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
 278 &       filter
 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
 323 input file with the action
 324 .Qq invalid .
 325 Alternatively, a key may be defined
 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.
 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.
 347 For example, failure to provide a
 348 .Qq quit
 349 command can lead to frustration.
 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.
 360 .Pp
 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
 392 ^G      abort
 393 .Ed
 394 .Sh ENVIRONMENT SECTION
 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.
 400 Each line consists of an environment variable name, an equals sign
 401 .Pq Sq =
 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.
 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.
 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
 413 The following input file sets the -i option whenever less is run:
 414 .Bd -literal -offset indent
 415 #env
 416 LESS = -i
 417 .Ed
 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
 444 .Sh SEE ALSO
 445 .Xr less 1
 446 .Sh AUTHORS
 447 .An Mark Nudelman