Annotation of src/usr.bin/less/less.1, Revision 1.22
1.22 ! jmc 1: .\" $OpenBSD: less.1,v 1.21 2011/02/03 22:11:22 jmc Exp $
1.1 millert 2: .\"
3: .\" Copyright (C) 2002 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.7 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.7 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.7 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: .\"
1.22 ! jmc 26: .Dd $Mdocdate: February 3 2011 $
1.1 millert 27: .Dt LESS 1
28: .Os
29: .Sh NAME
30: .Nm less , more
1.11 jmc 31: .Nd view files
1.1 millert 32: .Sh SYNOPSIS
1.18 jmc 33: .Nm less \*(Ba more
1.6 jmc 34: .Fl \&?
1.18 jmc 35: .Nm less \*(Ba more
1.1 millert 36: .Fl -help
1.18 jmc 37: .Nm less \*(Ba more
1.1 millert 38: .Fl V
1.18 jmc 39: .Nm less \*(Ba more
1.1 millert 40: .Fl -version
1.18 jmc 41: .Nm less \*(Ba more
1.1 millert 42: .Bk -words
1.12 jmc 43: .Op Fl Oo Cm + Oc Ns Cm aBCcdEeFfGgIiJLMmNnQqRrSsUuVWwX~
1.1 millert 44: .Op Fl b Ar space
45: .Op Fl h Ar lines
46: .Op Fl j Ar line
47: .Op Fl k Ar keyfile
1.12 jmc 48: .Op Fl O | o Ar logfile
49: .Op Fl P Ar prompt
1.1 millert 50: .Op Fl p Ar pattern
1.12 jmc 51: .Op Fl T Ar tagsfile
1.1 millert 52: .Op Fl t Ar tag
53: .Op Fl x Ar tab,...
54: .Op Fl y Ar lines
1.18 jmc 55: .Op Fl Oo Cm z Oc Ar lines
1.1 millert 56: .Op Fl # Ar shift
1.18 jmc 57: .Xo Oo Cm \&+ Ns Oo Ns Cm \&+ Ns
1.1 millert 58: .Oc Ar cmd
59: .Oc
60: .Xc
61: .Op Fl -
62: .Op Ar filename ...
63: .Ek
64: .\" (See the
65: .\" .Sx OPTIONS
66: .\" section for alternate option syntax with long option names.)
67: .Sh DESCRIPTION
68: .Nm
69: is a program similar to the traditional
70: .Xr more 1 ,
71: but which allows backward movement in the file as well as forward movement.
72: Also,
73: .Nm
74: does not have to read the entire input file before starting,
75: so with large input files it starts up faster than text editors like
76: .Xr vi 1 .
77: .Nm
78: uses termcap (or terminfo on some systems),
79: so it can run on a variety of terminals.
80: There is even limited support for hardcopy terminals.
81: (On a hardcopy terminal, lines which should be printed at the top
82: of the screen are prefixed with a caret.)
83: .Pp
84: This version of
85: .Nm
86: also acts as
87: .Xr more 1
88: if it is called as
89: .Nm more .
90: In this mode, the differences are in the prompt and that
91: .Nm more
92: exits by default when it gets to the end of the file.
93: Commands are based on both traditional
94: .Nm more
95: and
96: .Xr vi 1 .
97: Commands may be preceded by a decimal number,
98: called N in the descriptions below.
99: The number is used by some commands, as indicated.
100: .Sh COMMANDS
101: In the following descriptions, ^X means control-X.
102: ESC stands for the ESCAPE key; for example ESC-v means the
103: two character sequence "ESCAPE", then "v".
104: .Bl -tag -width XXXX
105: .It Ic h | H
106: Help: display a summary of these commands.
107: If you forget all the other commands, remember this one.
108: .It Ic SPACE | ^V | f | ^F
109: Scroll forward N lines, default one window (see option -z below).
110: If N is more than the screen size, only the final screenful is displayed.
111: Warning: some systems use ^V as a special literalization character.
112: .It Ic z
113: Like SPACE, but if N is specified, it becomes the new window size.
114: .It Ic ESC-SPACE
115: Like SPACE, but scrolls a full screensful, even if it reaches
116: end-of-file in the process.
1.22 ! jmc 117: .It Ic RETURN | ^N | e | ^E | j | ^J
1.1 millert 118: Scroll forward N lines, default 1.
119: The entire N lines are displayed, even if N is more than the screen size.
120: .It Ic d | ^D
121: Scroll forward N lines, default one half of the screen size.
122: If N is specified, it becomes the new default for subsequent d and u commands.
123: .It Ic b | ^B | ESC-v
124: Scroll backward N lines, default one window (see option -z below).
125: If N is more than the screen size, only the final screenful is displayed.
126: .It Ic w
127: Like ESC-v, but if N is specified, it becomes the new window size.
1.22 ! jmc 128: .It Ic y | ^Y | ^P | k | ^K
1.1 millert 129: Scroll backward N lines, default 1.
130: The entire N lines are displayed, even if N is more than the screen size.
131: Warning: some systems use ^Y as a special job control character.
132: .It Ic u | ^U
133: Scroll backward N lines, default one half of the screen size.
134: If N is specified, it becomes the new default for subsequent d and u commands.
135: .It Ic ESC-) | RIGHTARROW
136: Scroll horizontally right N characters, default half the screen width
137: (see the -# option).
138: If a number N is specified, it becomes the default for future
139: RIGHTARROW and LEFTARROW commands.
140: While the text is scrolled, it acts as though the -S option (chop lines)
141: were in effect.
142: .It Ic ESC-( | LEFTARROW
143: Scroll horizontally left N
144: characters, default half the screen width (see the -# option).
145: If a number N is specified, it becomes the default for future
146: RIGHTARROW and LEFTARROW commands.
147: .It Ic r | ^R | ^L
148: Repaint the screen.
149: .It Ic R
150: Repaint the screen, discarding any buffered input.
151: Useful if the file is changing while it is being viewed.
152: .It Ic F
153: Scroll forward, and keep trying to read when the end of file is reached.
154: Normally this command would be used when already at the end of the file.
155: It is a way to monitor the tail of a file which is growing
156: while it is being viewed.
157: (The behavior is similar to the "tail -f" command.)
158: .It Ic g | < | ESC-<
159: Go to line N in the file, default 1 (beginning of file).
160: (Warning: this may be slow if N is large.)
161: .It Ic G | > | ESC->
162: Go to line N in the file, default the end of the file.
163: (Warning: this may be slow if N is large,
164: or if N is not specified and standard input, rather than a file,
165: is being read.)
166: .It Ic p | %
167: Go to a position N percent into the file.
168: N should be between 0 and 100.
169: .It Ic {
170: If a left curly bracket appears in the top line displayed
171: on the screen, the { command will go to the matching right curly bracket.
172: The matching right curly bracket is positioned on the bottom
173: line of the screen.
174: If there is more than one left curly bracket on the top line, a number N
175: may be used to specify the N-th bracket on the line.
176: .It Ic }
177: If a right curly bracket appears in the bottom line displayed on the screen,
178: the } command will go to the matching left curly bracket.
179: The matching left curly bracket is positioned on the top
180: line of the screen.
181: If there is more than one right curly bracket on the top line,
182: a number N may be used to specify the N-th bracket on the line.
183: .It Ic \&(
184: Like {, but applies to parentheses rather than curly brackets.
185: .It Ic \&)
186: Like }, but applies to parentheses rather than curly brackets.
187: .It Ic \&[
188: Like {, but applies to square brackets rather than curly brackets.
189: .It Ic \&]
190: Like }, but applies to square brackets rather than curly brackets.
191: .It Ic ESC-^F
192: Followed by two characters, acts like {,
193: but uses the two characters as open and close brackets, respectively.
194: For example, "ESC ^F < >" could be used to
195: go forward to the > which matches the < in the top displayed line.
196: .It Ic ESC-^B
197: Followed by two characters, acts like },
198: but uses the two characters as open and close brackets, respectively.
199: For example, "ESC ^B < >" could be used to
200: go backward to the < which matches the > in the bottom displayed line.
201: .It Ic m
202: Followed by any lowercase letter, marks the current position with that letter.
203: .It Ic '
204: (Single quote.)
205: Followed by any lowercase letter, returns to the position which
206: was previously marked with that letter.
207: Followed by another single quote, returns to the position at
208: which the last "large" movement command was executed.
209: Followed by a ^ or $, jumps to the beginning or end of the file respectively.
210: Marks are preserved when a new file is examined,
211: so the ' command can be used to switch between input files.
212: .It Ic ^X^X
213: Same as single quote.
214: .It Ic /pattern
215: Search forward in the file for the N-th line containing the pattern.
216: N defaults to 1.
217: The pattern is a regular expression, as recognized by
218: .Xr ed 1 .
219: The search starts at the second line displayed
220: (but see the -a and -j options, which change this).
221: .Pp
222: Certain characters are special if entered at the beginning of the pattern;
223: they modify the type of search rather than become part of the pattern:
224: .Bl -tag -width Ds
1.6 jmc 225: .It Ic ^N | \&!
1.1 millert 226: Search for lines which do NOT match the pattern.
227: .It Ic ^E | *
228: Search multiple files.
229: That is, if the search reaches the END of the current file
230: without finding a match,
231: the search continues in the next file in the command line list.
232: .It Ic ^F | @
233: Begin the search at the first line of the FIRST file
234: in the command line list,
235: regardless of what is currently displayed on the screen
236: or the settings of the -a or -j options.
237: .It Ic ^K
238: Highlight any text which matches the pattern on the current screen,
239: but don't move to the first match (KEEP current position).
240: .It Ic ^R
241: Don't interpret regular expression metacharacters;
242: that is, do a simple textual comparison.
243: .El
244: .It Ic ?pattern
245: Search backward in the file for the N-th line containing the pattern.
246: The search starts at the line immediately before the top line displayed.
247: .Pp
248: Certain characters are special, as in the / command:
249: .Bl -tag -width Ds
1.6 jmc 250: .It Ic ^N | \&!
1.1 millert 251: Search for lines which do NOT match the pattern.
252: .It Ic ^E | *
253: Search multiple files.
254: That is, if the search reaches the beginning of the current file
255: without finding a match,
256: the search continues in the previous file in the command line list.
257: .It Ic ^F | @
258: Begin the search at the last line of the last file
259: in the command line list,
260: regardless of what is currently displayed on the screen
261: or the settings of the -a or -j options.
262: .It Ic ^K
263: As in forward searches.
264: .It Ic ^R
265: As in forward searches.
266: .El
267: .It Ic ESC-/pattern
268: Same as "/*".
269: .It Ic ESC-?pattern
270: Same as "?*".
271: .It Ic n
272: Repeat previous search, for N-th line containing the last pattern.
273: If the previous search was modified by ^N, the search is made for the
274: N-th line NOT containing the pattern.
275: If the previous search was modified by ^E, the search continues
276: in the next (or previous) file if not satisfied in the current file.
277: If the previous search was modified by ^R, the search is done
278: without using regular expressions.
279: There is no effect if the previous search was modified by ^F or ^K.
280: .It Ic N
281: Repeat previous search, but in the reverse direction.
282: .It Ic ESC-n
283: Repeat previous search, but crossing file boundaries.
284: The effect is as if the previous search were modified by *.
285: .It Ic ESC-N
286: Repeat previous search, but in the reverse direction
287: and crossing file boundaries.
288: .It Ic ESC-u
289: Undo search highlighting.
290: Turn off highlighting of strings matching the current search pattern.
291: If highlighting is already off because of a previous ESC-u command,
292: turn highlighting back on.
293: Any search command will also turn highlighting back on.
294: (Highlighting can also be disabled by toggling the -G option;
295: in that case search commands do not turn highlighting back on.)
296: .It Ic :e Op Ar filename
297: Examine a new file.
298: If the filename is missing, the "current" file (see the :n and :p commands
299: below) from the list of files in the command line is re-examined.
300: A percent sign (%) in the filename is replaced by the name of the
301: current file.
302: A pound sign (#) is replaced by the name of the previously examined file.
303: However, two consecutive percent signs are simply
304: replaced with a single percent sign.
305: This allows you to enter a filename that contains a percent sign
306: in the name.
307: Similarly, two consecutive pound signs are replaced with a single pound sign.
308: The filename is inserted into the command line list of files
309: so that it can be seen by subsequent :n and :p commands.
310: If the filename consists of several files, they are all inserted into
311: the list of files and the first one is examined.
312: If the filename contains one or more spaces,
313: the entire filename should be enclosed in double quotes
314: (also see the -" option).
315: .It Ic ^X^V | E
316: Same as :e.
317: Warning: some systems use ^V as a special literalization character.
318: On such systems, you may not be able to use ^V.
319: .It Ic :n
320: Examine the next file (from the list of files given in the command line).
321: If a number N is specified, the N-th next file is examined.
322: .It Ic :p
323: Examine the previous file in the command line list.
324: If a number N is specified, the N-th previous file is examined.
325: .It Ic :t
326: Go to the specified tag.
327: .It Ic :x
328: Examine the first file in the command line list.
329: If a number N is specified, the N-th file in the list is examined.
330: .It Ic :d
331: Remove the current file from the list of files.
332: .It Ic t
333: Go to the next tag, if there were more than one matches for the current tag.
334: See the \-t option for more details about tags.
335: .It Ic T
336: Go to the previous tag, if there were more than one matches for the current tag.
337: .It Ic = | ^G | :f
338: Prints some information about the file being viewed, including its name
339: and the line number and byte offset of the bottom line being displayed.
340: If possible, it also prints the length of the file,
341: the number of lines in the file
342: and the percent of the file above the last displayed line.
343: .It Ic \-
344: Followed by one of the command line option letters (see
345: .Sx OPTIONS
346: below),
347: this will change the setting of that option
348: and print a message describing the new setting.
349: If a ^P (CONTROL-P) is entered immediately after the dash,
350: the setting of the option is changed but no message is printed.
351: If the option letter has a numeric value (such as -b or -h),
352: or a string value (such as -P or -t),
353: a new value may be entered after the option letter.
354: If no new value is entered, a message describing
355: the current setting is printed and nothing is changed.
356: .It Ic \-\-
357: Like the \- command, but takes a long option name (see
358: .Sx OPTIONS
359: below)
360: rather than a single option letter.
361: You must press RETURN after typing the option name.
362: A ^P immediately after the second dash suppresses printing of a
363: message describing the new setting, as in the \- command.
364: .It Ic \-+
365: Followed by one of the command line option letters this will reset the
366: option to its default setting and print a message describing the new setting.
367: (The "\-+X" command does the same thing as "\-+X" on the command line.)
368: This does not work for string-valued options.
369: .It Ic \-\-+
370: Like the \-+ command, but takes a long option name
371: rather than a single option letter.
372: .It Ic \-!
373: Followed by one of the command line option letters, this will reset the
374: option to the "opposite" of its default setting and print a message
375: describing the new setting.
376: This does not work for numeric or string-valued options.
377: .It Ic \-\-!
378: Like the \-! command, but takes a long option name
379: rather than a single option letter.
380: .It Ic _
381: (Underscore.)
382: Followed by one of the command line option letters,
383: this will print a message describing the current setting of that option.
384: The setting of the option is not changed.
385: .It Ic __
386: (Double underscore.)
387: Like the _ (underscore) command, but takes a long option name
388: rather than a single option letter.
389: You must press RETURN after typing the option name.
390: .It Ic +cmd
391: Causes the specified cmd to be executed each time a new file is examined.
392: For example, +G causes
393: .Nm
394: to initially display each file starting at the end rather than the beginning.
395: .It Ic V
396: Prints the version number of
397: .Nm
398: being run.
1.22 ! jmc 399: .It Ic q | Q | :q | :Q | ZZ
1.1 millert 400: Exits
401: .Nm less .
402: .El
403: .Pp
404: The following
405: four
406: commands may or may not be valid, depending on your particular installation.
407: .Bl -tag -width XXXX
408: .It Ic v
409: Invokes an editor to edit the current file being viewed.
410: The editor is taken from the environment variable
411: .Ev VISUAL ,
412: if defined,
413: or
414: .Ev EDITOR
415: if
416: .Ev VISUAL
417: is not defined,
418: or defaults to "vi" if neither
419: .Ev VISUAL
420: nor
421: .Ev EDITOR
422: is defined.
423: See also the discussion of LESSEDIT under the section on
424: .Sx PROMPTS
425: below.
1.6 jmc 426: .It Ic \&! Ar shell-command
1.1 millert 427: Invokes a shell to run the shell-command given.
428: A percent sign (%) in the command is replaced by the name of the current file.
429: A pound sign (#) is replaced by the name of the previously examined file.
430: "!!" repeats the last shell command.
431: "!" with no shell command simply invokes a shell.
432: The shell is taken from the environment variable
433: .Ev SHELL ,
434: or defaults to "sh".
435: .\" On MS-DOS and OS/2 systems, the shell is the normal command processor.
1.22 ! jmc 436: .It Ic | <m> Ar shell-command
1.1 millert 437: <m> represents any mark letter.
438: Pipes a section of the input file to the given shell command.
439: The section of the file to be piped is between the first line on
440: the current screen and the position marked by the letter.
441: <m> may also be ^ or $ to indicate beginning or end of file respectively.
442: If <m> is . or newline, the current screen is piped.
443: .It Ic s Ar filename
444: Save the input to a file.
445: This only works if the input is a pipe, not an ordinary file.
446: .El
447: .Sh OPTIONS
448: Command line options are described below.
449: Most options may be changed while
450: .Nm
451: is running, via the "\-" command.
452: .Pp
453: Most options may be given in one of two forms:
454: either a dash followed by a single letter, or two dashes followed by a
455: long option name.
456: A long option name may be abbreviated as long as the abbreviation is
457: unambiguous.
458: For example, --quit-at-eof may be abbreviated --quit, but not
459: --qui, since both --quit-at-eof and --quiet begin with --qui.
460: Some long option names are in uppercase, such as --QUIT-AT-EOF, as
461: distinct from --quit-at-eof.
462: Such option names need only have their first letter capitalized;
463: the remainder of the name may be in either case.
464: For example, --Quit-at-eof is equivalent to --QUIT-AT-EOF.
465: .Pp
466: Options are also taken from the environment variable
467: .Ev LESS
468: if the command is
469: .Nm less ,
470: or from the environment variable
471: .Ev MORE
472: if the command is
473: .Nm more .
474: For example, to avoid typing "less -options ..." each time
475: .Nm
476: is invoked, you might tell
477: .Xr csh 1 :
478: .Pp
479: .Dl setenv LESS "-options"
480: .Pp
481: or if you use
482: .Xr sh 1 :
483: .Pp
484: .Dl LESS="-options"; export LESS
485: .Pp
486: .\" On MS-DOS, you don't need the quotes, but you should replace any
487: .\" percent signs in the options string by double percent signs.
488: .\" .Pp
489: The environment variable is parsed before the command line,
490: so command line options override the
491: .Ev LESS
492: environment variable.
493: If an option appears in the
494: .Ev LESS
495: variable, it can be reset to its default value on the command line by
496: beginning the command line option with "\-+".
497: .Pp
498: For options like -P which take a following string,
499: a dollar sign ($) must be used to signal the end of the string.
500: For example, to separate a prompt value from any other options
501: with dollar sign between them:
502: .Pp
503: .Dl LESS="-Ps--More--$-C -e"
504: .Bl -tag -width XXXX
1.6 jmc 505: .It Fl \&? | -help
1.1 millert 506: This option displays a summary of the commands accepted by
507: .Nm
508: (the same as the h command).
509: (Depending on how your shell interprets the question mark,
510: it may be necessary to quote the question mark, thus: "-\e?".)
511: .It Fl a | -search-skip-screen
512: Causes searches to start after the last line displayed on the screen,
513: thus skipping all lines displayed on the screen.
514: By default, searches start at the second line on the screen
515: (or after the last found line; see the -j option).
1.12 jmc 516: .It Fl B | -auto-buffers
517: By default, when data is read from a pipe,
518: buffers are allocated automatically as needed.
519: If a large amount of data is read from the pipe, this can cause
520: a large amount of memory to be allocated.
521: The -B option disables this automatic allocation of buffers for pipes,
522: so that only 64K (or the amount of space specified by the -b option)
523: is used for the pipe.
524: Warning: use of -B can result in erroneous display, since only the
525: most recently viewed part of the file is kept in memory;
526: any earlier data is lost.
1.1 millert 527: .It Xo
528: .Fl b Ns Ar n |
1.8 jmc 529: .Fl -buffers Ns = Ns Ar n
1.1 millert 530: .Xc
531: Specifies the amount of buffer space
532: .Nm
533: will use for each file, in units of kilobytes (1024 bytes).
534: By default 64K of buffer space is used for each file
535: (unless the file is a pipe; see the -B option).
536: The -b option specifies instead that n kilobytes of
537: buffer space should be used for each file.
538: If n is -1, buffer space is unlimited; that is,
539: the entire file is read into memory.
1.12 jmc 540: .It Fl C | -CLEAR-SCREEN
541: The -C option is like -c, but the screen is cleared before it is repainted.
1.1 millert 542: .It Fl c | -clear-screen
543: Causes full screen repaints to be painted from the top line down.
544: By default,
545: full screen repaints are done by scrolling from the bottom of the screen.
546: .It Fl d | -dumb No (less only)
547: The -d option suppresses the error message
548: normally displayed if the terminal is dumb;
549: that is, lacks some important capability,
550: such as the ability to clear the screen or scroll backward.
551: The -d option does not otherwise change the behavior of
552: .Nm
553: on a dumb terminal.
554: This option is on by default when invoked as
555: .Nm more .
556: .It Fl d No (more only)
557: The -d option causes the default prompt to include the
558: basic directions ``[Press space to continue, 'q' to quit.]''.
559: The -d option also causes the message ``[Press 'h' for instructions.]'' to be
560: displayed when an invalid command is entered (normally, the bell is rung).
561: This option is useful in environments where users may not be experienced
562: with pagers.
563: .\" .It Fl Dxcolor or --color=xcolor"
564: .\" [MS-DOS only]
565: .\" Sets the color of the text displayed.
566: .\" x is a single character which selects the type of text whose color is
567: .\" being set: n=normal, s=standout, d=bold, u=underlined, k=blink.
568: .\" color is a pair of numbers separated by a period.
569: .\" The first number selects the foreground color and the second selects
570: .\" the background color of the text.
571: .\" A single number N is the same as N.0.
1.12 jmc 572: .It Fl E | -QUIT-AT-EOF
573: Causes
574: .Nm
575: to automatically exit the first time it reaches end-of-file.
1.1 millert 576: .It Fl e | -quit-at-eof
577: Causes
578: .Nm
579: to automatically exit the second time it reaches end-of-file.
580: By default, the only way to exit
581: .Nm
582: is via the "q" command.
1.12 jmc 583: .It Fl F | -quit-if-one-screen
1.1 millert 584: Causes
585: .Nm
1.12 jmc 586: to automatically exit if the entire file can be displayed on the first screen.
1.1 millert 587: .It Fl f | -force
588: Forces non-regular files to be opened.
589: (A non-regular file is a directory or a device special file.)
590: Also suppresses the warning message when a binary file is opened.
591: By default,
592: .Nm
593: will refuse to open non-regular files.
1.12 jmc 594: .It Fl G | -HILITE-SEARCH
595: The -G option suppresses all highlighting of strings found by search commands.
1.1 millert 596: .It Fl g | -hilite-search
597: Normally,
598: .Nm
599: will highlight ALL strings which match the last search command.
600: The -g option changes this behavior to highlight only the particular string
601: which was found by the last search command.
602: This can cause
603: .Nm
604: to run somewhat faster than the default.
605: .It Xo
606: .Fl h Ns Ar n |
1.8 jmc 607: .Fl -max-back-scroll Ns = Ns Ar n
1.1 millert 608: .Xc
609: Specifies a maximum number of lines to scroll backward.
610: If it is necessary to scroll backward more than n lines,
611: the screen is repainted in a forward direction instead.
612: (If the terminal does not have the ability to scroll backward, -h0 is implied.)
1.12 jmc 613: .It Fl I | -IGNORE-CASE
614: Like -i, but searches ignore case even if the pattern contains uppercase
615: letters.
1.1 millert 616: .It Fl i | -ignore-case
617: Causes searches to ignore case; that is,
618: uppercase and lowercase are considered identical.
619: This option is ignored if any uppercase letters appear in the search pattern;
620: in other words,
621: if a pattern contains uppercase letters, then that search does not ignore case.
1.12 jmc 622: .It Fl J | -status-column
623: Displays a status column at the left edge of the screen.
624: The status column shows the lines that matched the current search.
625: The status column is also used if the -w or -W option is in effect.
1.1 millert 626: .It Xo
627: .Fl j Ns Ar n |
1.8 jmc 628: .Fl -jump-target Ns = Ns Ar n
1.1 millert 629: .Xc
630: Specifies a line on the screen where the "target" line is to be positioned.
631: A target line is the object of a text search,
632: tag search, jump to a line number,
633: jump to a file percentage, or jump to a marked position.
634: The screen line is specified by a number: the top line on the screen
635: is 1, the next is 2, and so on.
636: The number may be negative to specify a line relative to the bottom
637: of the screen: the bottom line on the screen is -1, the second
638: to the bottom is -2, and so on.
639: If the -j option is used, searches begin at the line immediately
640: after the target line.
641: For example, if "-j4" is used, the target line is the
642: fourth line on the screen, so searches begin at the fifth line on the screen.
643: .It Xo
644: .Fl k Ns Ar filename |
1.8 jmc 645: .Fl -lesskey-file Ns = Ns Ar filename
1.1 millert 646: .Xc
647: Causes
648: .Nm
649: to open and interpret the named file as a
650: .Xr lesskey 1
651: file.
652: Multiple -k options may be specified.
653: If the
654: .Ev LESSKEY
655: or
656: .Ev LESSKEY_SYSTEM
657: environment variable is set, or if a lesskey file is found in a standard place
658: (see
659: .Sx KEY BINDINGS ) ,
660: it is also used as a lesskey file.
661: .It Fl L | -no-lessopen
662: Ignore the
663: .Ev LESSOPEN
664: environment variable (see the
665: .Sx INPUT PREPROCESSOR
666: section below).
667: This option can be set from within
668: .Nm less ,
669: but it will apply only to files opened subsequently, not to the
670: file which is currently open.
671: When invoked as
672: .Nm more ,
673: the
674: .Ev LESSOPEN
675: environment variable is ignored by default.
1.12 jmc 676: .It Fl M | -LONG-PROMPT
677: Causes
678: .Nm
679: to prompt even more verbosely than
680: .Nm more .
1.1 millert 681: .It Fl m | -long-prompt
682: Causes
683: .Nm
684: to prompt verbosely (like more), with the percent into the file.
685: By default,
686: .Nm
687: prompts with a colon.
1.12 jmc 688: .It Fl N | -LINE-NUMBERS
689: Causes a line number to be displayed at the beginning of each line in the
690: display.
1.1 millert 691: .It Fl n | -line-numbers
692: Suppresses line numbers.
693: The default (to use line numbers) may cause
694: .Nm
695: to run more slowly in some cases, especially with a very large input file.
696: Suppressing line numbers with the -n option will avoid this problem.
697: Using line numbers means: the line number will be displayed in the verbose
698: prompt and in the = command, and the v command will pass the current line
699: number to the editor (see also the discussion of LESSEDIT in
700: .Sx PROMPTS
701: below).
702: .It Xo
703: .Fl O Ns Ar filename |
1.8 jmc 704: .Fl -LOG-FILE Ns = Ns Ar filename
1.1 millert 705: .Xc
706: The -O option is like -o, but it will overwrite an existing
707: file without asking for confirmation.
708: .Pp
709: If no log file has been specified,
710: the -o and -O options can be used from within
711: .Nm
712: to specify a log file.
713: Without a file name, they will simply report the name of the log file.
714: The "s" command is equivalent to specifying -o from within
715: .Nm less .
716: .It Xo
1.12 jmc 717: .Fl o Ns Ar filename |
718: .Fl -log-file Ns = Ns Ar filename
1.1 millert 719: .Xc
1.12 jmc 720: Causes
721: .Nm
722: to copy its input to the named file as it is being viewed.
723: This applies only when the input file is a pipe, not an ordinary file.
724: If the file already exists,
1.1 millert 725: .Nm
1.12 jmc 726: will ask for confirmation before overwriting it.
1.1 millert 727: .It Xo
728: .Fl P Ns Ar prompt |
1.8 jmc 729: .Fl -prompt Ns = Ns Ar prompt
1.1 millert 730: .Xc
731: Provides a way to tailor the three prompt styles to your own preference.
732: This option would normally be put in the
733: .Ev LESS
734: environment variable, rather than being typed in with each
735: .Nm
736: command.
737: Such an option must either be the last option in the
738: .Ev LESS
739: variable, or be terminated by a dollar sign.
740: -Ps followed by a string changes the default (short) prompt to that string.
741: -Pm changes the medium (-m) prompt.
742: -PM changes the long (-M) prompt.
743: -Ph changes the prompt for the help screen.
744: -P= changes the message printed by the = command.
745: -Pw changes the message printed while waiting for data (in the F command).
746: All prompt strings consist of a sequence of letters and special escape
747: sequences.
748: See the section on
749: .Sx PROMPTS
750: for more details.
1.12 jmc 751: .It Xo
752: .Fl p Ns Ar pattern |
753: .Fl -pattern Ns = Ns Ar pattern
754: .Xc
755: The -p option on the command line is equivalent to specifying +/pattern;
756: that is, it tells
757: .Nm
758: to start at the first occurrence of pattern in the file.
759: .It Fl Q | -QUIET | -SILENT
760: Causes totally "quiet" operation: the terminal bell is never rung.
1.1 millert 761: .It Fl q | -quiet | -silent
762: Causes moderately "quiet" operation:
763: the terminal bell is not rung if an attempt is made to scroll past the end
764: of the file or before the beginning of the file.
765: If the terminal has a "visual bell", it is used instead.
766: The bell will be rung on certain other errors,
767: such as typing an invalid character.
768: The default is to ring the terminal bell in all such cases.
769: .It Fl R | -RAW-CONTROL-CHARS
770: Like -r, but tries to keep track of the screen appearance where possible.
771: This works only if the input consists of normal text and possibly some
772: ANSI "color" escape sequences, which are sequences of the form:
773: .Pp
1.18 jmc 774: .Dl ESC \&[ ... m
1.1 millert 775: .Pp
776: where the "..." is zero or more characters other than "m".
777: For the purpose of keeping track of screen appearance,
778: all control characters and all ANSI color escape sequences are
779: assumed to not move the cursor.
780: You can make
781: .Nm
782: think that characters other than "m" can end ANSI color escape sequences
783: by setting the environment variable
784: .Ev LESSANSIENDCHARS
785: to the list of characters which can end a color escape sequence.
1.12 jmc 786: .It Fl r | -raw-control-chars
787: Causes "raw" control characters to be displayed.
788: The default is to display control characters using the caret notation;
789: for example, a control-A (octal 001) is displayed as "^A".
790: Warning: when the -r option is used,
791: .Nm
792: cannot keep track of the actual appearance of the screen
793: (since this depends on how the screen responds to
794: each type of control character).
795: Thus, various display problems may result,
796: such as long lines being split in the wrong place.
1.1 millert 797: .It Fl S | -chop-long-lines
798: Causes lines longer than the screen width to be chopped rather than folded.
799: That is, the portion of a long line that does not fit in
800: the screen width is not shown.
801: The default is to fold long lines; that is, display the remainder
802: on the next line.
1.12 jmc 803: .It Fl s | -squeeze-blank-lines
804: Causes consecutive blank lines to be squeezed into a single blank line.
805: .It Xo
806: .Fl T Ns Ar tagsfile |
807: .Fl -tag-file Ns = Ns Ar tagsfile
808: .Xc
809: Specifies a tags file to be used instead of "tags".
1.1 millert 810: .It Xo
811: .Fl t Ns Ar tag |
1.8 jmc 812: .Fl -tag Ns = Ns Ar tag
1.1 millert 813: .Xc
814: The -t option, followed immediately by a TAG,
815: will edit the file containing that tag.
816: For this to work, tag information must be available;
817: for example, there may be a file in the current directory called "tags",
818: which was previously built by
819: .Xr ctags 1
820: or an equivalent command.
821: If the environment variable
822: .Ev LESSGLOBALTAGS
823: is set, it is taken to be the name of a command compatible with
824: .Xr global ,
825: and that command is executed to find the tag.
826: (See http://www.gnu.org/software/global/global.html).
827: The -t option may also be specified from within
828: .Nm
829: (using the \- command) as a way of examining a new file.
830: The command ":t" is equivalent to specifying -t from within
831: .Nm less .
832: .It Fl U | -UNDERLINE-SPECIAL
833: Causes backspaces, tabs and carriage returns to be
834: treated as control characters;
835: that is, they are handled as specified by the -r option.
836: .Pp
837: By default, if neither -u nor -U is given, backspaces which appear adjacent
838: to an underscore character are treated specially:
839: the underlined text is displayed
840: using the terminal's hardware underlining capability.
841: Also, backspaces which appear between two identical characters
842: are treated specially:
843: the overstruck text is printed
844: using the terminal's hardware boldface capability.
845: Other backspaces are deleted, along with the preceding character.
846: Carriage returns immediately followed by a newline are deleted.
847: Other carriage returns are handled as specified by the -r option.
848: Text which is overstruck or underlined can be searched for
849: if neither -u nor -U is in effect.
1.12 jmc 850: .It Fl u | -underline-special
851: Causes backspaces and carriage returns to be treated as printable characters;
852: that is, they are sent to the terminal when they appear in the input.
1.1 millert 853: .It Fl V | -version
854: Displays the version number of
855: .Nm less .
1.12 jmc 856: .It Fl W | -HILITE-UNREAD
857: Like -w, but temporarily highlights the first new line after any
858: forward movement command larger than one line.
1.1 millert 859: .It Fl w | -hilite-unread
860: Temporarily highlights the first "new" line after a forward movement
861: of a full page.
862: The first "new" line is the line immediately following the line previously
863: at the bottom of the screen.
864: Also highlights the target line after a g or p command.
865: The highlight is removed at the next command which causes movement.
866: The entire line is highlighted, unless the -J option is in effect,
867: in which case only the status column is highlighted.
1.12 jmc 868: .It Fl X | -no-init
869: Disables sending the termcap initialization and deinitialization strings
870: to the terminal.
871: This is sometimes desirable if the deinitialization string does
872: something unnecessary, like clearing the screen.
1.1 millert 873: .It Xo
874: .Fl x Ns Ar n,... |
1.8 jmc 875: .Fl -tabs Ns = Ns Ar n,...
1.1 millert 876: .Xc
877: Sets tab stops.
878: If only one n is specified, tab stops are set at multiples of n.
879: If multiple values separated by commas are specified, tab stops are set at
880: those positions, and then continue with the same spacing as the last two.
881: For example, -x9,17 will set tabs at positions 9, 17, 25, 33, etc.
882: The default for n is 8.
883: .It Xo
884: .Fl y Ns Ar n |
1.8 jmc 885: .Fl -max-forw-scroll Ns = Ns Ar n
1.1 millert 886: .Xc
887: Specifies a maximum number of lines to scroll forward.
888: If it is necessary to scroll forward more than n lines,
889: the screen is repainted instead.
890: The -c or -C option may be used to repaint from the top of
891: the screen if desired.
892: By default, any forward movement causes scrolling.
893: .It Xo
894: .Fl Oo Cm z Oc Ns Ar n |
1.8 jmc 895: .Fl -window Ns = Ns Ar n
1.1 millert 896: .Xc
897: Changes the default scrolling window size to n lines.
898: The default is one screenful.
899: The z and w commands can also be used to change the window size.
900: The "z" may be omitted for compatibility with
901: .Nm more .
902: If the number
903: .Ar n
904: is negative, it indicates
905: .Ar n
906: lines less than the current screen size.
907: For example, if the screen is 24 lines, -z-4 sets the
908: scrolling window to 20 lines.
909: If the screen is resized to 40 lines,
910: the scrolling window automatically changes to 36 lines.
1.12 jmc 911: .It Fl -no-keypad
912: Disables sending the keypad initialization and deinitialization strings
913: to the terminal.
914: This is sometimes useful if the keypad strings make the numeric
915: keypad behave in an undesirable manner.
1.1 millert 916: .It Xo
917: .Ar -cc |
1.8 jmc 918: .Fl -quotes Ns = Ns Ar cc
1.1 millert 919: .Xc
920: Changes the filename quoting character.
921: This may be necessary if you are trying to name a file
922: which contains both spaces and quote characters.
923: Followed by a single character, this changes the quote character to that
924: character.
925: Filenames containing a space should then be surrounded by that character
926: rather than by double quotes.
927: Followed by two characters, changes the open quote to the first character,
928: and the close quote to the second character.
929: Filenames containing a space should then be preceded by the open quote
930: character and followed by the close quote character.
931: Note that even after the quote characters are changed, this option
932: remains -" (a dash followed by a double quote).
933: .It Fl ~ | -tilde
934: Normally lines after end of file are displayed as a single tilde (~).
935: This option causes lines after end of file to be displayed as blank lines.
936: .It Fl # | -shift
937: Specifies the default number of positions to scroll horizontally
938: in the RIGHTARROW and LEFTARROW commands.
939: If the number specified is zero, it sets the default number of
940: positions to one half of the screen width.
941: .It Fl -
942: A command line argument of "--" marks the end of option arguments.
943: Any arguments following this are interpreted as filenames.
944: This can be useful when viewing a file whose name begins with a "-" or "+".
945: .It Cm +
946: If a command line option begins with +,
947: the remainder of that option is taken to be an initial command to
948: .Nm less .
949: For example, +G tells
950: .Nm
951: to start at the end of the file rather than the beginning,
952: and +/xyz tells it to start at the first occurrence of "xyz" in the file.
953: As a special case, +<number> acts like +<number>g;
954: that is, it starts the display at the specified line number
955: (however, see the caveat under the "g" command above).
956: If the option starts with ++, the initial command applies to
957: every file being viewed, not just the first one.
958: The + command described previously
959: may also be used to set (or change) an initial command for every file.
960: .El
961: .Sh LINE EDITING
962: When entering command line at the bottom of the screen
963: (for example, a filename for the :e command,
964: or the pattern for a search command),
965: certain keys can be used to manipulate the command line.
966: Most commands have an alternate form in [ brackets ] which can be used if
967: a key does not exist on a particular keyboard.
968: .\" (The bracketed forms do not work in the MS-DOS version.)
969: Any of these special keys may be entered literally by preceding
970: it with the "literal" character, either ^V or ^A.
971: A backslash itself may also be entered literally by entering two backslashes.
972: .Bl -tag -width Ds
973: .It LEFTARROW [ ESC-h ]
974: Move the cursor one space to the left.
975: .It RIGHTARROW [ ESC-l ]
976: Move the cursor one space to the right.
977: .It ^LEFTARROW [ ESC-b or ESC-LEFTARROW ]
978: (That is, CONTROL and LEFTARROW simultaneously.)
979: Move the cursor one word to the left.
980: .It ^RIGHTARROW [ ESC-w or ESC-RIGHTARROW ]
981: (That is, CONTROL and RIGHTARROW simultaneously.)
982: Move the cursor one word to the right.
983: .It HOME [ ESC-0 ]
984: Move the cursor to the beginning of the line.
985: .It END [ ESC-$ ]
986: Move the cursor to the end of the line.
987: .It BACKSPACE
988: Delete the character to the left of the cursor,
989: or cancel the command if the command line is empty.
990: .It DELETE or [ ESC-x ]
991: Delete the character under the cursor.
992: .It ^BACKSPACE [ ESC-BACKSPACE ]
993: (That is, CONTROL and BACKSPACE simultaneously.)
994: Delete the word to the left of the cursor.
995: .It ^DELETE [ ESC-X or ESC-DELETE ]
996: (That is, CONTROL and DELETE simultaneously.)
997: Delete the word under the cursor.
998: .It UPARROW [ ESC-k ]
999: Retrieve the previous command line.
1000: .It DOWNARROW [ ESC-j ]
1001: Retrieve the next command line.
1002: .It TAB
1003: Complete the partial filename to the left of the cursor.
1004: If it matches more than one filename, the first match
1005: is entered into the command line.
1006: Repeated TABs will cycle through the other matching filenames.
1007: If the completed filename is a directory, a "/" is appended to the filename.
1008: .\" (On MS-DOS systems, a "\e" is appended.)
1009: The environment variable
1010: .Ev LESSSEPARATOR
1011: can be used to specify a different character to append to a directory name.
1012: .It BACKTAB [ ESC-TAB ]
1013: Like TAB, but cycles in the reverse direction through the matching filenames.
1014: .It ^L
1015: Complete the partial filename to the left of the cursor.
1016: If it matches more than one filename, all matches are entered into
1017: the command line (if they fit).
1018: .\" .It ^U (Unix and OS/2) or ESC (MS-DOS)
1019: .It ^U
1020: Delete the entire command line,
1021: or cancel the command if the command line is empty.
1022: If you have changed your line-kill character to something
1023: other than ^U, that character is used instead of ^U.
1024: .El
1025: .Sh KEY BINDINGS
1026: You may define your own
1027: .Nm
1028: commands by using the program
1029: .Xr lesskey 1
1030: to create a lesskey file.
1031: This file specifies a set of command keys and an action
1032: associated with each key.
1033: You may also use lesskey
1034: to change the line-editing keys (see
1035: .Sx LINE EDITING ) ,
1036: and to set environment variables.
1037: If the environment variable
1038: .Ev LESSKEY
1039: is set,
1040: .Nm
1041: uses that as the name of the lesskey file.
1042: Otherwise,
1043: .Nm
1044: looks for a lesskey file called "$HOME/.less".
1045: .\" On MS-DOS and Windows systems,
1046: .\" .I less
1047: .\" looks for a lesskey file called "$HOME/_less", and if it is not found there,
1048: .\" then looks for a lesskey file called "_less" in any directory specified
1049: .\" in the PATH environment variable.
1050: .\" On OS/2 systems,
1051: .\" .I less
1052: .\" looks for a lesskey file called "$HOME/less.ini", and if it is not found,
1053: .\" then looks for a lesskey file called "less.ini" in any directory specified
1054: .\" in the INIT environment variable, and if it not found there,
1055: .\" then looks for a lesskey file called "less.ini" in any directory specified
1056: .\" in the PATH environment variable.
1057: See the
1058: .Xr lesskey 1
1059: manual page for more details.
1060: .Pp
1061: A system-wide lesskey file may also be set up to provide key bindings.
1062: If a key is defined in both a local lesskey file and in the
1063: system-wide file, key bindings in the local file take precedence over
1064: those in the system-wide file.
1065: If the environment variable
1066: .Ev LESSKEY_SYSTEM
1067: is set,
1068: .Nm
1069: uses that as the name of the system-wide lesskey file.
1070: Otherwise,
1071: .Nm
1072: looks in a standard place for the system-wide lesskey file:
1073: On
1074: .Ox ,
1075: the system-wide lesskey file is
1076: .Pa /etc/sysless .
1077: .\" On Unix systems, the system-wide lesskey file is /usr/local/etc/sysless.
1078: .\" (However, if
1079: .\" .Nm less
1080: .\" was built with a different sysconf directory than /usr/local/etc,
1081: .\" that directory is where the sysless file is found.)
1082: .\" On MS-DOS and Windows systems, the system-wide lesskey file is c:\e_sysless.
1083: .\" On OS/2 systems, the system-wide lesskey file is c:\esysless.ini.
1084: .Sh INPUT PREPROCESSOR
1085: You may define an "input preprocessor" for
1086: .Nm less .
1087: Before
1088: .Nm less
1089: opens a file, it first gives your input preprocessor a chance to modify the
1090: way the contents of the file are displayed.
1091: An input preprocessor is simply an executable program (or shell script),
1092: which writes the contents of the file to a different file,
1093: called the replacement file.
1094: The contents of the replacement file are then displayed
1095: in place of the contents of the original file.
1096: However, it will appear to the user as if the original file is opened;
1097: that is,
1098: .Nm less
1099: will display the original filename as the name of the current file.
1100: .Pp
1101: An input preprocessor receives one command line argument, the original filename,
1102: as entered by the user.
1103: It should create the replacement file, and when finished
1104: print the name of the replacement file to its standard output.
1105: If the input preprocessor does not output a replacement filename,
1106: .Nm
1107: uses the original file, as normal.
1108: The input preprocessor is not called when viewing standard input.
1109: To set up an input preprocessor, set the
1110: .Ev LESSOPEN
1111: environment variable to a command line which will invoke your
1112: input preprocessor.
1113: This command line should include one occurrence of the string "%s",
1114: which will be replaced by the filename
1115: when the input preprocessor command is invoked.
1116: .Pp
1117: When
1118: .Nm
1119: closes a file opened in such a way, it will call another program,
1120: called the input postprocessor,
1121: which may perform any desired clean-up action (such as deleting the
1122: replacement file created by
1123: .Ev LESSOPEN ) .
1124: This program receives two command line arguments, the original filename
1125: as entered by the user, and the name of the replacement file.
1126: To set up an input postprocessor, set the
1127: .Ev LESSCLOSE
1128: environment variable to a command line which will invoke your
1129: input postprocessor.
1130: It may include two occurrences of the string "%s";
1131: the first is replaced with the original name of the file and the second
1132: with the name of the replacement file, which was output by
1133: .Ev LESSOPEN .
1134: .Pp
1135: For example, these two scripts will allow you
1136: to keep files in compressed format, but still let
1137: .Nm
1138: view them directly:
1139: .Pp
1140: lessopen.sh:
1141: .Bd -literal -offset indent
1142: #! /bin/sh
1143: case "$1" in
1144: *.Z) uncompress -c $1 >/tmp/less.$$ 2>/dev/null
1145: if [ -s /tmp/less.$$ ]; then
1146: echo /tmp/less.$$
1147: else
1148: rm -f /tmp/less.$$
1149: fi
1150: ;;
1151: esac
1152: .Ed
1153: .Pp
1154: lessclose.sh:
1155: .Bd -literal -offset indent
1156: #! /bin/sh
1157: rm $2
1158: .Ed
1159: .Pp
1160: To use these scripts, put them both where they can be executed and
1161: set LESSOPEN="lessopen.sh\ %s", and LESSCLOSE="lessclose.sh\ %s\ %s".
1162: More complex LESSOPEN and LESSCLOSE scripts may be written
1163: to accept other types of compressed files, and so on.
1164: .Pp
1165: It is also possible to set up an input preprocessor to
1166: pipe the file data directly to
1167: .Nm less ,
1168: rather than putting the data into a replacement file.
1169: This avoids the need to decompress the entire file before starting to view it.
1170: An input preprocessor that works this way is called an input pipe.
1171: An input pipe, instead of writing the name of a replacement file on
1172: its standard output,
1173: writes the entire contents of the replacement file on its standard output.
1174: If the input pipe does not write any characters on its standard output,
1175: then there is no replacement file and
1176: .Nm
1177: uses the original file, as normal.
1178: To use an input pipe, make the first character in the
1179: .Ev LESSOPEN
1180: environment variable a vertical bar (|) to signify that the
1181: input preprocessor is an input pipe.
1182: .Pp
1183: For example, this script will work like the previous example scripts:
1184: .Pp
1185: lesspipe.sh:
1186: .Bd -literal -offset indent
1187: #! /bin/sh
1188: case "$1" in
1189: *.Z) uncompress -c $1 2>/dev/null
1190: ;;
1191: esac
1192: .Ed
1193: .Pp
1194: To use this script, put it where it can be executed and set
1195: LESSOPEN="|lesspipe.sh %s".
1196: When an input pipe is used, a LESSCLOSE postprocessor can be used,
1197: but it is usually not necessary since there is no replacement file to clean up.
1198: In this case, the replacement file name passed to the LESSCLOSE
1199: postprocessor is "-".
1200: .Sh NATIONAL CHARACTER SETS
1201: There are three types of characters in the input file:
1202: .Bl -tag -width "control characters"
1203: .It normal characters
1204: Can be displayed directly to the screen.
1205: .It control characters
1206: Should not be displayed directly, but are expected to be found
1207: in ordinary text files (such as backspace and tab).
1208: .It binary characters
1209: Should not be displayed directly and are not expected to be found
1210: in text files.
1211: .El
1212: .Pp
1213: A "character set" is simply a description of which characters are to
1214: be considered normal, control, and binary.
1215: The
1216: .Ev LESSCHARSET
1217: environment variable may be used to select a character set.
1218: Possible values for
1219: .Ev LESSCHARSET
1220: are:
1221: .Bl -tag -width "IBM-1047"
1222: .It ascii
1223: BS, TAB, NL, CR, and formfeed are control characters,
1224: all chars with values between 32 and 126 are normal,
1225: and all others are binary.
1226: .It iso8859
1227: Selects an ISO 8859 character set.
1228: This is the same as ASCII, except characters between 160 and 255 are
1229: treated as normal characters.
1230: .It latin1
1231: Same as iso8859.
1232: .It latin9
1233: Same as iso8859.
1234: .It dos
1235: Selects a character set appropriate for MS-DOS.
1236: .It ebcdic
1237: Selects an EBCDIC character set.
1238: .It IBM-1047
1.17 sobrado 1239: Selects an EBCDIC character set used by OS/390
1240: .Ux
1241: Services.
1.1 millert 1242: This is the EBCDIC analogue of latin1.
1243: You get similar results by setting either LESSCHARSET=IBM-1047 or
1244: LC_CTYPE=en_US in your environment.
1245: .It koi8-r
1246: Selects a Russian character set.
1247: .It next
1248: Selects a character set appropriate for NeXT computers.
1249: .It utf-8
1250: Selects the UTF-8 encoding of the ISO 10646 character set.
1251: .El
1252: .Pp
1253: In special cases, it may be desired to tailor
1254: .Nm
1255: to use a character set other than the ones definable by LESSCHARSET.
1256: In this case, the environment variable
1257: .Ev LESSCHARDEF
1258: can be used to define a character set.
1259: It should be set to a string where each character in the string represents
1260: one character in the character set.
1261: The character "." is used for a normal character, "c" for control,
1262: and "b" for binary.
1263: A decimal number may be used for repetition.
1264: For example, "bccc4b." would mean character 0 is binary,
1265: 1, 2 and 3 are control, 4, 5, 6 and 7 are binary, and 8 is normal.
1266: All characters after the last are taken to be the same as the last,
1267: so characters 9 through 255 would be normal.
1268: (This is an example, and does not necessarily
1269: represent any real character set.)
1270: .Pp
1271: This table shows the value of LESSCHARDEF which is equivalent
1272: to each of the possible values for LESSCHARSET:
1273: .Bd -literal -offset indent
1274: ascii 8bcccbcc18b95.b
1275: dos 8bcccbcc12bc5b95.b.
1276: ebcdic 5bc6bcc7bcc41b.9b7.9b5.b..8b6.10b6.b9.7b
1277: 9.8b8.17b3.3b9.7b9.8b8.6b10.b.b.b.
1278: IBM-1047 4cbcbc3b9cbccbccbb4c6bcc5b3cbbc4bc4bccbc
1279: 191.b
1280: iso8859 8bcccbcc18b95.33b.
1281: koi8-r 8bcccbcc18b95.b128.
1282: latin1 8bcccbcc18b95.33b.
1283: next 8bcccbcc18b95.bb125.bb
1284: .Ed
1285: .Pp
1286: If neither LESSCHARSET nor LESSCHARDEF is set,
1287: but the string "UTF-8" is found in the
1.21 jmc 1288: .Ev LC_ALL , LC_CTYPE
1.1 millert 1289: or
1290: .Ev LANG
1291: environment variables, then the default character set is utf-8.
1292: .Pp
1293: If that string is not found, but your system supports the
1294: setlocale interface,
1295: .Nm
1296: will use setlocale to determine the character set.
1297: setlocale is controlled by setting the
1298: .Ev LANG
1299: or
1300: .Ev LC_CTYPE
1301: environment variables.
1302: .Pp
1303: Finally, if the
1304: setlocale interface is also not available, the default character set is latin1.
1305: .Pp
1306: Control and binary characters are displayed in standout (reverse video).
1307: Each such character is displayed in caret notation if possible
1308: (e.g. ^A for control-A).
1309: Caret notation is used only if inverting the 0100 bit results in a
1310: normal printable character.
1311: Otherwise, the character is displayed as a hex number in angle brackets.
1312: This format can be changed by setting the
1313: .Ev LESSBINFMT
1314: environment variable.
1315: LESSBINFMT may begin with a "*" and one character to select
1316: the display attribute:
1317: "*k" is blinking, "*d" is bold, "*u" is underlined, "*s" is standout,
1318: and "*n" is normal.
1319: If LESSBINFMT does not begin with a "*", normal attribute is assumed.
1320: The remainder of LESSBINFMT is a string which may include one
1321: printf-style escape sequence (a % followed by x, X, o, d, etc.).
1322: For example, if LESSBINFMT is "*u[%x]", binary characters
1323: are displayed in underlined hexadecimal surrounded by brackets.
1324: The default if no LESSBINFMT is specified is "*s<%X>".
1325: .Sh PROMPTS
1326: The -P option allows you to tailor the prompt to your preference.
1327: The string given to the -P option replaces the specified prompt string.
1328: Certain characters in the string are interpreted specially.
1329: The prompt mechanism is rather complicated to provide flexibility,
1330: but the ordinary user need not understand the details of constructing
1331: personalized prompt strings.
1332: .Pp
1333: A percent sign followed by a single character is expanded
1334: according to what the following character is:
1335: .Bl -tag -width Ds
1336: .It %b Ns Ar X
1337: Replaced by the byte offset into the current input file.
1338: The b is followed by a single character (shown as
1339: .Ar X
1340: above) which specifies the line whose byte offset is to be used.
1341: If the character is a "t", the byte offset of the top line in the
1342: display is used,
1343: an "m" means use the middle line,
1344: a "b" means use the bottom line,
1345: a "B" means use the line just after the bottom line,
1346: and a "j" means use the "target" line, as specified by the -j option.
1.4 jmc 1347: .It \&%B
1.1 millert 1348: Replaced by the size of the current input file.
1349: .It %c
1350: Replaced by the column number of the text appearing in the first
1351: column of the screen.
1352: .It %d Ns Ar X
1353: Replaced by the page number of a line in the input file.
1354: The line to be used is determined by the
1355: .Ar X ,
1356: as with the %b option.
1.4 jmc 1357: .It \&%D
1.1 millert 1358: Replaced by the number of pages in the input file,
1359: or equivalently, the page number of the last line in the input file.
1360: .It %E
1361: Replaced by the name of the editor (from the
1362: .Ev VISUAL
1363: environment variable, or the
1364: .Ev EDITOR
1365: environment variable if
1366: .Ev VISUAL
1367: is not defined).
1368: See the discussion of the LESSEDIT feature below.
1369: .It %f
1370: Replaced by the name of the current input file.
1371: .It %i
1372: Replaced by the index of the current file in the list of
1373: input files.
1374: .It %l Ns Ar X
1375: Replaced by the line number of a line in the input file.
1376: The line to be used is determined by the
1377: .Ar X ,
1378: as with the %b option.
1379: .It %L
1380: Replaced by the line number of the last line in the input file.
1381: .It %m
1382: Replaced by the total number of input files.
1383: .It %p Ns Ar X
1384: Replaced by the percent into the current input file, based on byte offsets.
1385: The line used is determined by the
1386: .Ar X ,
1387: as with the %b option.
1.4 jmc 1388: .It \&%P Ns Ar X
1.1 millert 1389: Replaced by the percent into the current input file, based on line numbers.
1390: The line used is determined by the
1391: .Ar X ,
1392: as with the %b option.
1393: .It %s
1394: Same as %B.
1395: .It %t
1396: Causes any trailing spaces to be removed.
1397: Usually used at the end of the string, but may appear anywhere.
1398: .It %x
1399: Replaced by the name of the next input file in the list.
1400: .El
1401: .Pp
1402: If any item is unknown (for example, the file size if input is a pipe),
1403: a question mark is printed instead.
1404: .Pp
1405: The format of the prompt string can be changed depending on certain conditions.
1406: A question mark followed by a single character acts like an "IF":
1407: depending on the following character, a condition is evaluated.
1408: If the condition is true, any characters following the question mark
1409: and condition character, up to a period, are included in the prompt.
1410: If the condition is false, such characters are not included.
1411: A colon appearing between the question mark and the
1412: period can be used to establish an "ELSE": any characters between
1413: the colon and the period are included in the string, if and only if
1414: the IF condition is false.
1415: Condition characters (which follow a question mark) may be:
1416: .Bl -tag -width Ds
1417: .It ?a
1418: True if any characters have been included in the prompt so far.
1419: .It ?b Ns Ar X
1420: True if the byte offset of the specified line is known.
1421: .It ?B
1422: True if the size of the current input file is known.
1423: .It ?c
1424: True if the text is horizontally shifted (%c is not zero).
1425: .It ?d Ns Ar X
1426: True if the page number of the specified line is known.
1427: .It ?e
1428: True if at end-of-file.
1429: .It ?f
1430: True if there is an input filename
1431: (that is, if input is not a pipe).
1432: .It ?l Ns Ar X
1433: True if the line number of the specified line is known.
1434: .It ?L
1435: True if the line number of the last line in the file is known.
1436: .It ?m
1437: True if there is more than one input file.
1438: .It ?n
1439: True if this is the first prompt in a new input file.
1440: .It ?p Ns Ar X
1441: True if the percent into the current input file, based on byte offsets,
1442: of the specified line is known.
1443: .It ?P Ns Ar X
1444: True if the percent into the current input file, based on line numbers,
1445: of the specified line is known.
1446: .It ?s
1447: Same as "?B".
1448: .It ?x
1449: True if there is a next input file
1450: (that is, if the current input file is not the last one).
1451: .El
1452: .Pp
1453: Any characters other than the special ones
1454: (question mark, colon, period, percent, and backslash)
1455: become literally part of the prompt.
1456: Any of the special characters may be included in the prompt literally
1457: by preceding it with a backslash.
1458: .Pp
1459: Some examples:
1460: .Pp
1461: .Dl ?f%f:Standard input.
1462: .Pp
1463: This prompt prints the filename, if known;
1464: otherwise the string "Standard input".
1465: .Pp
1466: .Dl ?f%f .?ltLine %lt:?pt%pt\e%:?btByte %bt:-...
1467: .Pp
1468: This prompt would print the filename, if known.
1469: The filename is followed by the line number, if known,
1470: otherwise the percent if known, otherwise the byte offset if known.
1471: Otherwise, a dash is printed.
1472: Notice how each question mark has a matching period,
1473: and how the % after the %pt
1474: is included literally by escaping it with a backslash.
1475: .Pp
1476: .Dl ?n?f%f\ .?m(file\ %i\ of\ %m)\ ..?e(END)\ ?x-\ Next\e:\ %x..%t
1477: .Pp
1478: This prints the filename if this is the first prompt in a file,
1479: followed by the "file N of N" message if there is more
1480: than one input file.
1481: Then, if we are at end-of-file, the string "(END)" is printed
1482: followed by the name of the next file, if there is one.
1483: Finally, any trailing spaces are truncated.
1484: This is the default prompt.
1485: For reference, here are the defaults for
1486: the other two prompts (-m and -M respectively).
1487: Each is broken into two lines here for readability only.
1488: .Bd -literal -offset indent
1.19 ray 1489: ?f%f\ .?m(file\ %i\ of\ %m)\ .?e(END)\ ?x-\ Next\e:\ %x.:
1.1 millert 1490: ?pB%pB\e%:byte\ %bB?s/%s...%t
1491:
1492: ?f%f\ .?n?m(file\ %i\ of\ %m)\ ..?ltlines\ %lt-%lb?L/%L.\ :
1493: byte\ %bB?s/%s.\ .?e(END)\ ?x-\ Next\e:\ %x.:?pB%pB\e%..%t
1494: .Ed
1495: .Pp
1496: And here is the default message produced by the = command:
1497: .Bd -literal -offset indent
1498: ?f%f\ .?m(file\ %i\ of\ %m)\ .?ltlines\ %lt-%lb?L/%L.\ .
1499: byte\ %bB?s/%s.\ ?e(END)\ :?pB%pB\e%..%t
1500: .Ed
1501: .Pp
1502: The prompt expansion features are also used for another purpose:
1503: if an environment variable
1504: .Ev LESSEDIT
1505: is defined, it is used as the command to be executed when the v command
1506: is invoked.
1507: The LESSEDIT string is expanded in the same way as the prompt strings.
1508: The default value for LESSEDIT is:
1509: .Pp
1510: .Dl %E\ ?lm+%lm.\ %f
1511: .Pp
1512: Note that this expands to the editor name, followed by a + and the
1513: line number, followed by the file name.
1514: If your editor does not accept the "+linenumber" syntax, or has other
1515: differences in invocation syntax, the
1516: .Ev LESSEDIT
1517: variable can be changed to modify this default.
1518: .Sh SECURITY
1519: When the environment variable
1520: .Ev LESSSECURE
1521: is set to 1,
1522: .Nm
1523: runs in a "secure" mode.
1524: This means these features are disabled:
1525: .Bl -tag -width Ds
1.6 jmc 1526: .It \&!
1.1 millert 1527: The shell command.
1528: .It |
1529: The pipe command.
1530: .It :e
1531: The examine command.
1532: .It v
1533: The editing command.
1534: .It s -o
1535: Log files.
1536: .It -k
1537: Use of lesskey files.
1538: .It -t
1539: Use of tags files.
1540: .It " "
1541: Metacharacters in filenames, such as "*".
1542: .It " "
1543: Filename completion (TAB, ^L).
1544: .El
1545: .Pp
1546: Less can also be compiled to be permanently in "secure" mode.
1.3 jmc 1547: .Sh ENVIRONMENT
1.1 millert 1548: Environment variables may be specified either in the system environment
1549: as usual, or in a
1550: .Xr lesskey 1
1551: file.
1552: If environment variables are defined in more than one place,
1553: variables defined in a local lesskey file take precedence over
1554: variables defined in the system environment, which take precedence
1555: over variables defined in the system-wide lesskey file.
1556: .Bl -tag -width Ds
1557: .It Ev COLUMNS
1558: Sets the number of columns on the screen.
1559: Takes precedence over the number of columns specified by the TERM variable.
1560: (But if you have a windowing system which supports TIOCGWINSZ or WIOCGETD,
1561: the window system's idea of the screen size takes precedence over the
1562: LINES and COLUMNS environment variables.)
1563: .It Ev EDITOR
1564: The name of the editor (used for the v command).
1565: .It Ev HOME
1566: Name of the user's home directory
1567: (used to find a lesskey file).
1568: .\" .It Ev "HOMEDRIVE, HOMEPATH"
1569: .\" Concatenation of the HOMEDRIVE and HOMEPATH environment variables is
1570: .\" the name of the user's home directory if the HOME variable is not set
1571: .\" (only in the Windows version).
1572: .\" .It Ev INIT
1573: .\" Name of the user's init directory
1574: .\" (used to find a lesskey file on OS/2 systems).
1575: .It Ev LANG
1576: Language for determining the character set.
1577: .It Ev LC_CTYPE
1578: Language for determining the character set.
1579: .It Ev LESS
1580: Options which are passed to
1581: .Nm
1582: automatically.
1583: .It Ev LESSANSIENDCHARS
1584: Characters which are assumed to end an ANSI color escape sequence
1585: (default "m").
1586: .It Ev LESSBINFMT
1587: Format for displaying non-printable, non-control characters.
1588: .It Ev LESSCHARDEF
1589: Defines a character set.
1590: .It Ev LESSCHARSET
1591: Selects a predefined character set.
1592: .It Ev LESSCLOSE
1593: Command line to invoke the (optional) input-postprocessor.
1594: .\" .It Ev LESSECHO
1595: .\" Name of the lessecho program (default "lessecho").
1596: .\" The lessecho program is needed to expand metacharacters, such as * and ?,
1597: .\" in filenames on Unix systems.
1598: .It Ev LESSEDIT
1599: Editor prototype string (used for the v command).
1600: See discussion under
1601: .Sx PROMPTS .
1602: .It Ev LESSGLOBALTAGS
1603: Name of the command used by the -t option to find global tags.
1604: Normally should be set to "global" if your system has the global command.
1605: If not set, global tags are not used.
1606: .It Ev LESSKEY
1607: Name of the default lesskey(1) file.
1608: .It Ev LESSKEY_SYSTEM
1609: Name of the default system-wide lesskey(1) file.
1610: .It Ev LESSMETACHARS
1611: List of characters which are considered "metacharacters" by the shell.
1612: .It Ev LESSMETAESCAPE
1613: Prefix which
1614: .Nm
1615: will add before each metacharacter in a command sent to the shell.
1616: If LESSMETAESCAPE is an empty string, commands containing
1617: metacharacters will not be passed to the shell.
1618: .It Ev LESSOPEN
1619: Command line to invoke the (optional) input-preprocessor.
1620: .It Ev LESSSECURE
1621: Runs less in "secure" mode.
1622: See discussion under
1623: .Sx SECURITY .
1624: .It Ev LESSSEPARATOR
1625: String to be appended to a directory name in filename completion.
1626: .It Ev LINES
1627: Sets the number of lines on the screen.
1628: Takes precedence over the number of lines specified by the TERM variable.
1629: (But if you have a windowing system which supports TIOCGWINSZ or WIOCGETD,
1630: the window system's idea of the screen size takes precedence over the
1631: LINES and COLUMNS environment variables.)
1632: .\" .It Ev PATH
1633: .\" User's search path (used to find a lesskey file
1634: .\" on MS-DOS and OS/2 systems).
1635: .It Ev SHELL
1636: The shell used to execute the ! command, as well as to expand filenames.
1637: .It Ev TERM
1638: The type of terminal on which
1639: .Nm
1640: is being run.
1641: .It Ev VISUAL
1642: The name of the editor (used for the v command).
1643: .El
1644: .Sh SEE ALSO
1645: .Xr lesskey 1
1.13 jmc 1646: .Sh STANDARDS
1647: The
1648: .Nm more
1649: utility is compliant with the
1.15 jmc 1650: .St -p1003.1-2008
1.16 jmc 1651: specification,
1652: though its presence is optional.
1.13 jmc 1653: .Pp
1654: The flags
1655: .Op Fl aBbCdEFfGghIJjkLMmNOoPQqRrSTUVWwXxyz~#
1656: are extensions to that specification.
1.7 jmc 1657: .Sh AUTHORS
1658: .An Mark Nudelman Aq markn@greenwoodsoftware.com
1659: .Pp
1660: Send bug reports or comments to the above address or to
1661: .Aq bug\-less@gnu.org .
1662: .Pp
1663: For more information, see the less homepage at
1664: .Pa http://www.greenwoodsoftware.com/less .
1665: .Sh CAVEATS
1.1 millert 1666: The = command and prompts (unless changed by -P)
1667: report the line numbers of the lines at the top and bottom of the screen,
1668: but the byte and percent of the line after the one at the bottom of the screen.
1669: .Pp
1670: If the :e command is used to name more than one file,
1671: and one of the named files has been viewed previously,
1672: the new files may be entered into the list in an unexpected order.
1673: .Pp
1674: On certain older terminals (the so-called "magic cookie" terminals),
1675: search highlighting will cause an erroneous display.
1676: On such terminals, search highlighting is disabled by default
1677: to avoid possible problems.
1678: .Pp
1679: In certain cases, when search highlighting is enabled and
1680: a search pattern begins with a ^,
1681: more text than the matching string may be highlighted.
1682: (This problem does not occur when
1683: .Nm
1684: is compiled to use the POSIX regular expression package.)
1685: .Pp
1686: When viewing text containing ANSI color escape sequences using the -R option,
1687: searching will not find text containing an embedded escape sequence.
1688: Also, search highlighting may change the color of some of the text
1689: which follows the highlighted text.
1690: .Pp
1691: On some systems, setlocale claims that ASCII characters 0 through 31 are
1692: control characters rather than binary characters.
1693: This causes
1694: .Nm
1695: to treat some binary files as ordinary, non-binary files.
1696: To workaround this problem, set the environment variable
1697: .Ev LESSCHARSET
1698: to "ascii" (or whatever character set is appropriate).
1699: .Pp
1700: See
1701: .Pa http://www.greenwoodsoftware.com/less
1702: for the latest list of known bugs in this version of
1703: .Nm less .