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