From: jmc Date: Thu, 1 May 2014 18:59:15 +0000 (+0000) Subject: options first, then pager commands; also remove one non-standard Sh; X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=2efc7d2dfce4ddb6a224c09d3095f21248cc0c3a;p=openbsd options first, then pager commands; also remove one non-standard Sh; --- diff --git a/usr.bin/less/less.1 b/usr.bin/less/less.1 index 962934a8477..4c00d29993b 100644 --- a/usr.bin/less/less.1 +++ b/usr.bin/less/less.1 @@ -1,4 +1,4 @@ -.\" $OpenBSD: less.1,v 1.35 2014/05/01 18:53:22 jmc Exp $ +.\" $OpenBSD: less.1,v 1.36 2014/05/01 18:59:15 jmc Exp $ .\" .\" Copyright (C) 1984-2012 Mark Nudelman .\" @@ -81,377 +81,7 @@ and Commands may be preceded by a decimal number, called N in the descriptions below. The number is used by some commands, as indicated. -.Sh COMMANDS -In the following descriptions, ^X means control-X. -ESC stands for the ESCAPE key; for example ESC-v means the -two character sequence "ESCAPE", then "v". -.Bl -tag -width XXXX -.It Ic h | H -Help: display a summary of these commands. -If you forget all the other commands, remember this one. -.It Ic SPACE | ^V | f | ^F -Scroll forward N lines, default one window (see option -z below). -If N is more than the screen size, only the final screenful is displayed. -Warning: some systems use ^V as a special literalization character. -.It Ic z -Like SPACE, but if N is specified, it becomes the new window size. -.It Ic ESC-SPACE -Like SPACE, but scrolls a full screenful, even if it reaches -end-of-file in the process. -.It Ic ENTER | RETURN | ^N | e | ^E | j | ^J -Scroll forward N lines, default 1. -The entire N lines are displayed, even if N is more than the screen size. -.It Ic d | ^D -Scroll forward N lines, default one half of the screen size. -If N is specified, it becomes the new default for subsequent d and u commands. -.It Ic b | ^B | ESC-v -Scroll backward N lines, default one window (see option -z below). -If N is more than the screen size, only the final screenful is displayed. -.It Ic w -Like ESC-v, but if N is specified, it becomes the new window size. -.It Ic y | ^Y | ^P | k | ^K -Scroll backward N lines, default 1. -The entire N lines are displayed, even if N is more than the screen size. -Warning: some systems use ^Y as a special job control character. -.It Ic u | ^U -Scroll backward N lines, default one half of the screen size. -If N is specified, it becomes the new default for subsequent d and u commands. -.It Ic ESC-) | RIGHTARROW -Scroll horizontally right N characters, default half the screen width -(see the -# option). -If a number N is specified, it becomes the default for future -RIGHTARROW and LEFTARROW commands. -While the text is scrolled, it acts as though the -S option (chop lines) -were in effect. -.It Ic ESC-( | LEFTARROW -Scroll horizontally left N -characters, default half the screen width (see the -# option). -If a number N is specified, it becomes the default for future -RIGHTARROW and LEFTARROW commands. -.It Ic r | ^R | ^L -Repaint the screen. -.It Ic R -Repaint the screen, discarding any buffered input. -Useful if the file is changing while it is being viewed. -.It Ic F -Scroll forward, and keep trying to read when the end of file is reached. -Normally this command would be used when already at the end of the file. -It is a way to monitor the tail of a file which is growing -while it is being viewed. -(The behavior is similar to the "tail -f" command.) -.It Ic ESC-F -Like F, but as soon as a line is found which matches -the last search pattern, the terminal bell is rung -and forward scrolling stops. -.It Ic g | < | ESC-< -Go to line N in the file, default 1 (beginning of file). -(Warning: this may be slow if N is large.) -.It Ic G | > | ESC-> -Go to line N in the file, default the end of the file. -(Warning: this may be slow if N is large, -or if N is not specified and standard input, rather than a file, -is being read.) -.It Ic p | % -Go to a position N percent into the file. -N should be between 0 and 100, and may contain a decimal point. -.It Ic P -Go to the line containing byte offset N in the file. -.It Ic { -If a left curly bracket appears in the top line displayed -on the screen, the { command will go to the matching right curly bracket. -The matching right curly bracket is positioned on the bottom -line of the screen. -If there is more than one left curly bracket on the top line, a number N -may be used to specify the N-th bracket on the line. -.It Ic } -If a right curly bracket appears in the bottom line displayed on the screen, -the } command will go to the matching left curly bracket. -The matching left curly bracket is positioned on the top -line of the screen. -If there is more than one right curly bracket on the top line, -a number N may be used to specify the N-th bracket on the line. -.It Ic \&( -Like {, but applies to parentheses rather than curly brackets. -.It Ic \&) -Like }, but applies to parentheses rather than curly brackets. -.It Ic \&[ -Like {, but applies to square brackets rather than curly brackets. -.It Ic \&] -Like }, but applies to square brackets rather than curly brackets. -.It Ic ESC-^F -Followed by two characters, acts like {, -but uses the two characters as open and close brackets, respectively. -For example, "ESC ^F < >" could be used to -go forward to the > which matches the < in the top displayed line. -.It Ic ESC-^B -Followed by two characters, acts like }, -but uses the two characters as open and close brackets, respectively. -For example, "ESC ^B < >" could be used to -go backward to the < which matches the > in the bottom displayed line. -.It Ic m -Followed by any lowercase letter, marks the current position with that letter. -.It Ic ' -(Single quote.) -Followed by any lowercase letter, returns to the position which -was previously marked with that letter. -Followed by another single quote, returns to the position at -which the last "large" movement command was executed. -Followed by a ^ or $, jumps to the beginning or end of the file respectively. -Marks are preserved when a new file is examined, -so the ' command can be used to switch between input files. -.It Ic ^X^X -Same as single quote. -.It Ic /pattern -Search forward in the file for the N-th line containing the pattern. -N defaults to 1. -The pattern is a regular expression, as recognized by -the regular expression library supplied by your system. -The search starts at the first line displayed -(but see the -a and -j options, which change this). -.Pp -Certain characters are special if entered at the beginning of the pattern; -they modify the type of search rather than become part of the pattern: -.Bl -tag -width Ds -.It Ic ^N | \&! -Search for lines which do NOT match the pattern. -.It Ic ^E | * -Search multiple files. -That is, if the search reaches the END of the current file -without finding a match, -the search continues in the next file in the command line list. -.It Ic ^F | @ -Begin the search at the first line of the FIRST file -in the command line list, -regardless of what is currently displayed on the screen -or the settings of the -a or -j options. -.It Ic ^K -Highlight any text which matches the pattern on the current screen, -but don't move to the first match (KEEP current position). -.It Ic ^R -Don't interpret regular expression metacharacters; -that is, do a simple textual comparison. -.El -.It Ic ?pattern -Search backward in the file for the N-th line containing the pattern. -The search starts at the line immediately before the top line displayed. -.Pp -Certain characters are special, as in the / command: -.Bl -tag -width Ds -.It Ic ^N | \&! -Search for lines which do NOT match the pattern. -.It Ic ^E | * -Search multiple files. -That is, if the search reaches the beginning of the current file -without finding a match, -the search continues in the previous file in the command line list. -.It Ic ^F | @ -Begin the search at the last line of the last file -in the command line list, -regardless of what is currently displayed on the screen -or the settings of the -a or -j options. -.It Ic ^K -As in forward searches. -.It Ic ^R -As in forward searches. -.El -.It Ic ESC-/pattern -Same as "/*". -.It Ic ESC-?pattern -Same as "?*". -.It Ic n -Repeat previous search, for N-th line containing the last pattern. -If the previous search was modified by ^N, the search is made for the -N-th line NOT containing the pattern. -If the previous search was modified by ^E, the search continues -in the next (or previous) file if not satisfied in the current file. -If the previous search was modified by ^R, the search is done -without using regular expressions. -There is no effect if the previous search was modified by ^F or ^K. -.It Ic N -Repeat previous search, but in the reverse direction. -.It Ic ESC-n -Repeat previous search, but crossing file boundaries. -The effect is as if the previous search were modified by *. -.It Ic ESC-N -Repeat previous search, but in the reverse direction -and crossing file boundaries. -.It Ic ESC-u -Undo search highlighting. -Turn off highlighting of strings matching the current search pattern. -If highlighting is already off because of a previous ESC-u command, -turn highlighting back on. -Any search command will also turn highlighting back on. -(Highlighting can also be disabled by toggling the -G option; -in that case search commands do not turn highlighting back on.) -.It Ic &pattern -Display only lines which match the pattern; -lines which do not match the pattern are not displayed. -If pattern is empty (if you type & immediately followed by ENTER), -any filtering is turned off, and all lines are displayed. -While filtering is in effect, an ampersand is displayed at the -beginning of the prompt, -as a reminder that some lines in the file may be hidden. -.Pp -Certain characters are special as in the / command: -.Bl -tag -width Ds -.It Ic ^N | ! -Display only lines which do NOT match the pattern. -.It Ic ^R -Don't interpret regular expression metacharacters; -that is, do a simple textual comparison. -.El -.It Ic :e Op Ar filename -Examine a new file. -If the filename is missing, the "current" file (see the :n and :p commands -below) from the list of files in the command line is re-examined. -A percent sign (%) in the filename is replaced by the name of the -current file. -A pound sign (#) is replaced by the name of the previously examined file. -However, two consecutive percent signs are simply -replaced with a single percent sign. -This allows you to enter a filename that contains a percent sign -in the name. -Similarly, two consecutive pound signs are replaced with a single pound sign. -The filename is inserted into the command line list of files -so that it can be seen by subsequent :n and :p commands. -If the filename consists of several files, they are all inserted into -the list of files and the first one is examined. -If the filename contains one or more spaces, -the entire filename should be enclosed in double quotes -(also see the -" option). -.It Ic ^X^V | E -Same as :e. -Warning: some systems use ^V as a special literalization character. -On such systems, you may not be able to use ^V. -.It Ic :n -Examine the next file (from the list of files given in the command line). -If a number N is specified, the N-th next file is examined. -.It Ic :p -Examine the previous file in the command line list. -If a number N is specified, the N-th previous file is examined. -.It Ic :t -Go to the specified tag. -.It Ic :x -Examine the first file in the command line list. -If a number N is specified, the N-th file in the list is examined. -.It Ic :d -Remove the current file from the list of files. -.It Ic t -Go to the next tag, if there were more than one matches for the current tag. -See the \-t option for more details about tags. -.It Ic T -Go to the previous tag, if there were more than one matches for the current tag. -.It Ic = | ^G | :f -Prints some information about the file being viewed, including its name -and the line number and byte offset of the bottom line being displayed. -If possible, it also prints the length of the file, -the number of lines in the file -and the percent of the file above the last displayed line. -.It Ic \- -Followed by one of the command line option letters (see -.Sx OPTIONS -below), -this will change the setting of that option -and print a message describing the new setting. -If a ^P (CONTROL-P) is entered immediately after the dash, -the setting of the option is changed but no message is printed. -If the option letter has a numeric value (such as -b or -h), -or a string value (such as -P or -t), -a new value may be entered after the option letter. -If no new value is entered, a message describing -the current setting is printed and nothing is changed. -.It Ic \-\- -Like the \- command, but takes a long option name (see -.Sx OPTIONS -below) -rather than a single option letter. -You must press ENTER or RETURN after typing the option name. -A ^P immediately after the second dash suppresses printing of a -message describing the new setting, as in the \- command. -.It Ic \-+ -Followed by one of the command line option letters this will reset the -option to its default setting and print a message describing the new setting. -(The "\-+X" command does the same thing as "\-+X" on the command line.) -This does not work for string-valued options. -.It Ic \-\-+ -Like the \-+ command, but takes a long option name -rather than a single option letter. -.It Ic \-! -Followed by one of the command line option letters, this will reset the -option to the "opposite" of its default setting and print a message -describing the new setting. -This does not work for numeric or string-valued options. -.It Ic \-\-! -Like the \-! command, but takes a long option name -rather than a single option letter. -.It Ic _ -(Underscore.) -Followed by one of the command line option letters, -this will print a message describing the current setting of that option. -The setting of the option is not changed. -.It Ic __ -(Double underscore.) -Like the _ (underscore) command, but takes a long option name -rather than a single option letter. -You must press ENTER or RETURN after typing the option name. -.It Ic +cmd -Causes the specified cmd to be executed each time a new file is examined. -For example, +G causes -.Nm -to initially display each file starting at the end rather than the beginning. -.It Ic V -Prints the version number of -.Nm -being run. -.It Ic q | Q | :q | :Q | ZZ -Exits -.Nm less . -.El .Pp -The following -four -commands may or may not be valid, depending on your particular installation. -.Bl -tag -width XXXX -.It Ic v -Invokes an editor to edit the current file being viewed. -The editor is taken from the environment variable -.Ev VISUAL , -if defined, -or -.Ev EDITOR -if -.Ev VISUAL -is not defined, -or defaults to "vi" if neither -.Ev VISUAL -nor -.Ev EDITOR -is defined. -See also the discussion of LESSEDIT under the section on -.Sx PROMPTS -below. -.It Ic \&! Ar shell-command -Invokes a shell to run the shell-command given. -A percent sign (%) in the command is replaced by the name of the current file. -A pound sign (#) is replaced by the name of the previously examined file. -"!!" repeats the last shell command. -"!" with no shell command simply invokes a shell. -The shell is taken from the environment variable -.Ev SHELL , -or defaults to "sh". -.\" On MS-DOS and OS/2 systems, the shell is the normal command processor. -.It Ic | Ar shell-command - represents any mark letter. -Pipes a section of the input file to the given shell command. -The section of the file to be piped is between the first line on -the current screen and the position marked by the letter. - may also be ^ or $ to indicate beginning or end of file respectively. -If is . or newline, the current screen is piped. -.It Ic s Ar filename -Save the input to a file. -This only works if the input is a pipe, not an ordinary file. -.El -.Sh OPTIONS Command line options are described below. Most options may be changed while .Nm @@ -515,6 +145,8 @@ by preceding it with a backslash. If the --use-backslash option is not in effect, then backslashes are not treated specially, and there is no way to include a dollar sign in the option string. +.Pp +The options are as follows: .Bl -tag -width XXXX .It Fl \&? | -help This option displays a summary of the commands accepted by @@ -721,317 +353,687 @@ Causes .Nm to prompt even more verbosely than .Nm more . -.It Fl m | -long-prompt -Causes +.It Fl m | -long-prompt +Causes +.Nm +to prompt verbosely (like more), with the percent into the file. +By default, +.Nm +prompts with a colon. +.It Fl N | -LINE-NUMBERS +Causes a line number to be displayed at the beginning of each line in the +display. +.It Fl n | -line-numbers +Suppresses line numbers. +The default (to use line numbers) may cause +.Nm +to run more slowly in some cases, especially with a very large input file. +Suppressing line numbers with the -n option will avoid this problem. +Using line numbers means: the line number will be displayed in the verbose +prompt and in the = command, and the v command will pass the current line +number to the editor (see also the discussion of LESSEDIT in +.Sx PROMPTS +below). +.It Xo +.Fl O Ar logfile | +.Fl -LOG-FILE Ns = Ns Ar logfile +.Xc +The -O option is like -o, but it will overwrite an existing +file without asking for confirmation. +.Pp +If no log file has been specified, +the -o and -O options can be used from within +.Nm +to specify a log file. +Without a file name, they will simply report the name of the log file. +The "s" command is equivalent to specifying -o from within +.Nm less . +.It Xo +.Fl o Ar logfile | +.Fl -log-file Ns = Ns Ar logfile +.Xc +Causes +.Nm +to copy its input to the named file as it is being viewed. +This applies only when the input file is a pipe, not an ordinary file. +If the file already exists, +.Nm +will ask for confirmation before overwriting it. +.It Xo +.Fl P Ar prompt | +.Fl -prompt Ns = Ns Ar prompt +.Xc +Provides a way to tailor the three prompt styles to your own preference. +This option would normally be put in the +.Ev LESS +environment variable, rather than being typed in with each +.Nm +command. +Such an option must either be the last option in the +.Ev LESS +variable, or be terminated by a dollar sign. +-Ps followed by a string changes the default (short) prompt to that string. +-Pm changes the medium (-m) prompt. +-PM changes the long (-M) prompt. +-Ph changes the prompt for the help screen. +-P= changes the message printed by the = command. +-Pw changes the message printed while waiting for data (in the F command). +All prompt strings consist of a sequence of letters and special escape +sequences. +See the section on +.Sx PROMPTS +for more details. +.It Xo +.Fl p Ar pattern | +.Fl -pattern Ns = Ns Ar pattern +.Xc +The -p option on the command line is equivalent to specifying +/pattern; +that is, it tells +.Nm +to start at the first occurrence of pattern in the file. +.It Fl Q | -QUIET | -SILENT +Causes totally "quiet" operation: the terminal bell is never rung. +.It Fl q | -quiet | -silent +Causes moderately "quiet" operation: +the terminal bell is not rung if an attempt is made to scroll past the end +of the file or before the beginning of the file. +If the terminal has a "visual bell", it is used instead. +The bell will be rung on certain other errors, +such as typing an invalid character. +The default is to ring the terminal bell in all such cases. +.It Fl R | -RAW-CONTROL-CHARS +Like -r, but only ANSI "color" escape sequences are output in "raw" form. +Unlike -r, the screen appearance is maintained correctly in most cases. +ANSI "color" escape sequences are sequences of the form: +.Pp +.Dl ESC \&[ ... m +.Pp +where the "..." is zero or more color specification characters. +For the purpose of keeping track of screen appearance, +ANSI color escape sequences are assumed to not move the cursor. +You can make +.Nm +think that characters other than "m" can end ANSI color escape sequences +by setting the environment variable +.Ev LESSANSIENDCHARS +to the list of characters which can end a color escape sequence. +And you can make +.Nm +think that characters other than the standard ones may appear between +the ESC and the m by setting the environment variable +.Ev LESSANSIMIDCHARS +to the list of characters which can appear. +.It Fl r | -raw-control-chars +Causes "raw" control characters to be displayed. +The default is to display control characters using the caret notation; +for example, a control-A (octal 001) is displayed as "^A". +Warning: when the -r option is used, +.Nm +cannot keep track of the actual appearance of the screen +(since this depends on how the screen responds to +each type of control character). +Thus, various display problems may result, +such as long lines being split in the wrong place. +.It Fl S | -chop-long-lines +Causes lines longer than the screen width to be +chopped (truncated) rather than wrapped. +That is, the portion of a long line that does not fit in +the screen width is not shown. +The default is to wrap long lines; that is, display the remainder +on the next line. +.It Fl s | -squeeze-blank-lines +Causes consecutive blank lines to be squeezed into a single blank line. +.It Xo +.Fl T Ar tagsfile | +.Fl -tag-file Ns = Ns Ar tagsfile +.Xc +Specifies a tags file to be used instead of "tags". +.It Xo +.Fl t Ar tag | +.Fl -tag Ns = Ns Ar tag +.Xc +The -t option, followed immediately by a TAG, +will edit the file containing that tag. +For this to work, tag information must be available; +for example, there may be a file in the current directory called "tags", +which was previously built by +.Xr ctags 1 +or an equivalent command. +If the environment variable +.Ev LESSGLOBALTAGS +is set, it is taken to be the name of a command compatible with +.Xr global , +and that command is executed to find the tag. +(See +.Lk http://www.gnu.org/software/global/global.html ) . +The -t option may also be specified from within +.Nm +(using the \- command) as a way of examining a new file. +The command ":t" is equivalent to specifying -t from within +.Nm less . +.It Fl U | -UNDERLINE-SPECIAL +Causes backspaces, tabs and carriage returns to be +treated as control characters; +that is, they are handled as specified by the -r option. +.Pp +By default, if neither -u nor -U is given, backspaces which appear adjacent +to an underscore character are treated specially: +the underlined text is displayed +using the terminal's hardware underlining capability. +Also, backspaces which appear between two identical characters +are treated specially: +the overstruck text is printed +using the terminal's hardware boldface capability. +Other backspaces are deleted, along with the preceding character. +Carriage returns immediately followed by a newline are deleted. +Other carriage returns are handled as specified by the -r option. +Text which is overstruck or underlined can be searched for +if neither -u nor -U is in effect. +.It Fl u | -underline-special +Causes backspaces and carriage returns to be treated as printable characters; +that is, they are sent to the terminal when they appear in the input. +.It Fl V | -version +Displays the version number of +.Nm less . +.It Fl W | -HILITE-UNREAD +Like -w, but temporarily highlights the first new line after any +forward movement command larger than one line. +.It Fl w | -hilite-unread +Temporarily highlights the first "new" line after a forward movement +of a full page. +The first "new" line is the line immediately following the line previously +at the bottom of the screen. +Also highlights the target line after a g or p command. +The highlight is removed at the next command which causes movement. +The entire line is highlighted, unless the -J option is in effect, +in which case only the status column is highlighted. +.It Fl X | -no-init +Disables sending the termcap initialization and deinitialization strings +to the terminal. +This is sometimes desirable if the deinitialization string does +something unnecessary, like clearing the screen. +.It Xo +.Fl x Ar n Ns , Ns Ar ... | +.Fl -tabs Ns = Ns Ar n Ns , Ns Ar ... +.Xc +Sets tab stops. +If only one n is specified, tab stops are set at multiples of n. +If multiple values separated by commas are specified, tab stops are set at +those positions, and then continue with the same spacing as the last two. +For example, -x9,17 will set tabs at positions 9, 17, 25, 33, etc. +The default for n is 8. +.It Xo +.Fl y Ar n | +.Fl -max-forw-scroll Ns = Ns Ar n +.Xc +Specifies a maximum number of lines to scroll forward. +If it is necessary to scroll forward more than n lines, +the screen is repainted instead. +The -c or -C option may be used to repaint from the top of +the screen if desired. +By default, any forward movement causes scrolling. +.It Xo +.Fl z Ar n | +.Fl -window Ns = Ns Ar n +.Xc +Changes the default scrolling window size to n lines. +The default is one screenful. +The z and w commands can also be used to change the window size. +The "z" may be omitted for compatibility with some versions of +.Nm more . +If the number +.Ar n +is negative, it indicates +.Ar n +lines less than the current screen size. +For example, if the screen is 24 lines, -z-4 sets the +scrolling window to 20 lines. +If the screen is resized to 40 lines, +the scrolling window automatically changes to 36 lines. +.It Fl -follow-name +Normally, if the input file is renamed while an F command is executing, .Nm -to prompt verbosely (like more), with the percent into the file. -By default, +will continue to display the contents of the original file despite +its name change. +If --follow-name is specified, during an F command .Nm -prompts with a colon. -.It Fl N | -LINE-NUMBERS -Causes a line number to be displayed at the beginning of each line in the -display. -.It Fl n | -line-numbers -Suppresses line numbers. -The default (to use line numbers) may cause +will periodically attempt to reopen the file by name. +If the reopen succeeds and the file is a different file from the original +(which means that a new file has been created +with the same name as the original (now renamed) file), .Nm -to run more slowly in some cases, especially with a very large input file. -Suppressing line numbers with the -n option will avoid this problem. -Using line numbers means: the line number will be displayed in the verbose -prompt and in the = command, and the v command will pass the current line -number to the editor (see also the discussion of LESSEDIT in -.Sx PROMPTS -below). +will display the contents of that new file. +.It Fl -no-keypad +Disables sending the keypad initialization and deinitialization strings +to the terminal. +This is sometimes useful if the keypad strings make the numeric +keypad behave in an undesirable manner. +.It Fl -use-backslash +This option changes the interpretations of options which follow this one. +After the --use-backslash option, any backslash in an option string is +removed and the following character is taken literally. +This allows a dollar sign to be included in option strings. .It Xo -.Fl O Ar logfile | -.Fl -LOG-FILE Ns = Ns Ar logfile +.Ar -cc | +.Fl -quotes Ns = Ns Ar cc .Xc -The -O option is like -o, but it will overwrite an existing -file without asking for confirmation. +Changes the filename quoting character. +This may be necessary if you are trying to name a file +which contains both spaces and quote characters. +Followed by a single character, this changes the quote character to that +character. +Filenames containing a space should then be surrounded by that character +rather than by double quotes. +Followed by two characters, changes the open quote to the first character, +and the close quote to the second character. +Filenames containing a space should then be preceded by the open quote +character and followed by the close quote character. +Note that even after the quote characters are changed, this option +remains -" (a dash followed by a double quote). +.It Fl ~ | -tilde +Normally lines after end of file are displayed as a single tilde (~). +This option causes lines after end of file to be displayed as blank lines. +.It Fl # | -shift +Specifies the default number of positions to scroll horizontally +in the RIGHTARROW and LEFTARROW commands. +If the number specified is zero, it sets the default number of +positions to one half of the screen width. +Alternately, the number may be specified as a fraction of the width +of the screen, starting with a decimal point: .5 is half of the +screen width, .3 is three tenths of the screen width, and so on. +If the number is specified as a fraction, the actual number of +scroll positions is recalculated if the terminal window is resized, +so that the actual scroll remains at the specified fraction +of the screen width. +.It Fl - +A command line argument of "--" marks the end of option arguments. +Any arguments following this are interpreted as filenames. +This can be useful when viewing a file whose name begins with a "-" or "+". +.It Cm + +If a command line option begins with +, +the remainder of that option is taken to be an initial command to +.Nm less . +For example, +G tells +.Nm +to start at the end of the file rather than the beginning, +and +/xyz tells it to start at the first occurrence of "xyz" in the file. +As a special case, + acts like +g; +that is, it starts the display at the specified line number +(however, see the caveat under the "g" command above). +If the option starts with ++, the initial command applies to +every file being viewed, not just the first one. +The + command described previously +may also be used to set (or change) an initial command for every file. +.El +.Sh COMMANDS +In the following descriptions, ^X means control-X. +ESC stands for the ESCAPE key; for example ESC-v means the +two character sequence "ESCAPE", then "v". +.Bl -tag -width XXXX +.It Ic h | H +Help: display a summary of these commands. +If you forget all the other commands, remember this one. +.It Ic SPACE | ^V | f | ^F +Scroll forward N lines, default one window (see option -z below). +If N is more than the screen size, only the final screenful is displayed. +Warning: some systems use ^V as a special literalization character. +.It Ic z +Like SPACE, but if N is specified, it becomes the new window size. +.It Ic ESC-SPACE +Like SPACE, but scrolls a full screenful, even if it reaches +end-of-file in the process. +.It Ic ENTER | RETURN | ^N | e | ^E | j | ^J +Scroll forward N lines, default 1. +The entire N lines are displayed, even if N is more than the screen size. +.It Ic d | ^D +Scroll forward N lines, default one half of the screen size. +If N is specified, it becomes the new default for subsequent d and u commands. +.It Ic b | ^B | ESC-v +Scroll backward N lines, default one window (see option -z below). +If N is more than the screen size, only the final screenful is displayed. +.It Ic w +Like ESC-v, but if N is specified, it becomes the new window size. +.It Ic y | ^Y | ^P | k | ^K +Scroll backward N lines, default 1. +The entire N lines are displayed, even if N is more than the screen size. +Warning: some systems use ^Y as a special job control character. +.It Ic u | ^U +Scroll backward N lines, default one half of the screen size. +If N is specified, it becomes the new default for subsequent d and u commands. +.It Ic ESC-) | RIGHTARROW +Scroll horizontally right N characters, default half the screen width +(see the -# option). +If a number N is specified, it becomes the default for future +RIGHTARROW and LEFTARROW commands. +While the text is scrolled, it acts as though the -S option (chop lines) +were in effect. +.It Ic ESC-( | LEFTARROW +Scroll horizontally left N +characters, default half the screen width (see the -# option). +If a number N is specified, it becomes the default for future +RIGHTARROW and LEFTARROW commands. +.It Ic r | ^R | ^L +Repaint the screen. +.It Ic R +Repaint the screen, discarding any buffered input. +Useful if the file is changing while it is being viewed. +.It Ic F +Scroll forward, and keep trying to read when the end of file is reached. +Normally this command would be used when already at the end of the file. +It is a way to monitor the tail of a file which is growing +while it is being viewed. +(The behavior is similar to the "tail -f" command.) +.It Ic ESC-F +Like F, but as soon as a line is found which matches +the last search pattern, the terminal bell is rung +and forward scrolling stops. +.It Ic g | < | ESC-< +Go to line N in the file, default 1 (beginning of file). +(Warning: this may be slow if N is large.) +.It Ic G | > | ESC-> +Go to line N in the file, default the end of the file. +(Warning: this may be slow if N is large, +or if N is not specified and standard input, rather than a file, +is being read.) +.It Ic p | % +Go to a position N percent into the file. +N should be between 0 and 100, and may contain a decimal point. +.It Ic P +Go to the line containing byte offset N in the file. +.It Ic { +If a left curly bracket appears in the top line displayed +on the screen, the { command will go to the matching right curly bracket. +The matching right curly bracket is positioned on the bottom +line of the screen. +If there is more than one left curly bracket on the top line, a number N +may be used to specify the N-th bracket on the line. +.It Ic } +If a right curly bracket appears in the bottom line displayed on the screen, +the } command will go to the matching left curly bracket. +The matching left curly bracket is positioned on the top +line of the screen. +If there is more than one right curly bracket on the top line, +a number N may be used to specify the N-th bracket on the line. +.It Ic \&( +Like {, but applies to parentheses rather than curly brackets. +.It Ic \&) +Like }, but applies to parentheses rather than curly brackets. +.It Ic \&[ +Like {, but applies to square brackets rather than curly brackets. +.It Ic \&] +Like }, but applies to square brackets rather than curly brackets. +.It Ic ESC-^F +Followed by two characters, acts like {, +but uses the two characters as open and close brackets, respectively. +For example, "ESC ^F < >" could be used to +go forward to the > which matches the < in the top displayed line. +.It Ic ESC-^B +Followed by two characters, acts like }, +but uses the two characters as open and close brackets, respectively. +For example, "ESC ^B < >" could be used to +go backward to the < which matches the > in the bottom displayed line. +.It Ic m +Followed by any lowercase letter, marks the current position with that letter. +.It Ic ' +(Single quote.) +Followed by any lowercase letter, returns to the position which +was previously marked with that letter. +Followed by another single quote, returns to the position at +which the last "large" movement command was executed. +Followed by a ^ or $, jumps to the beginning or end of the file respectively. +Marks are preserved when a new file is examined, +so the ' command can be used to switch between input files. +.It Ic ^X^X +Same as single quote. +.It Ic /pattern +Search forward in the file for the N-th line containing the pattern. +N defaults to 1. +The pattern is a regular expression, as recognized by +the regular expression library supplied by your system. +The search starts at the first line displayed +(but see the -a and -j options, which change this). .Pp -If no log file has been specified, -the -o and -O options can be used from within -.Nm -to specify a log file. -Without a file name, they will simply report the name of the log file. -The "s" command is equivalent to specifying -o from within -.Nm less . -.It Xo -.Fl o Ar logfile | -.Fl -log-file Ns = Ns Ar logfile -.Xc -Causes -.Nm -to copy its input to the named file as it is being viewed. -This applies only when the input file is a pipe, not an ordinary file. -If the file already exists, -.Nm -will ask for confirmation before overwriting it. -.It Xo -.Fl P Ar prompt | -.Fl -prompt Ns = Ns Ar prompt -.Xc -Provides a way to tailor the three prompt styles to your own preference. -This option would normally be put in the -.Ev LESS -environment variable, rather than being typed in with each -.Nm -command. -Such an option must either be the last option in the -.Ev LESS -variable, or be terminated by a dollar sign. --Ps followed by a string changes the default (short) prompt to that string. --Pm changes the medium (-m) prompt. --PM changes the long (-M) prompt. --Ph changes the prompt for the help screen. --P= changes the message printed by the = command. --Pw changes the message printed while waiting for data (in the F command). -All prompt strings consist of a sequence of letters and special escape -sequences. -See the section on -.Sx PROMPTS -for more details. -.It Xo -.Fl p Ar pattern | -.Fl -pattern Ns = Ns Ar pattern -.Xc -The -p option on the command line is equivalent to specifying +/pattern; -that is, it tells -.Nm -to start at the first occurrence of pattern in the file. -.It Fl Q | -QUIET | -SILENT -Causes totally "quiet" operation: the terminal bell is never rung. -.It Fl q | -quiet | -silent -Causes moderately "quiet" operation: -the terminal bell is not rung if an attempt is made to scroll past the end -of the file or before the beginning of the file. -If the terminal has a "visual bell", it is used instead. -The bell will be rung on certain other errors, -such as typing an invalid character. -The default is to ring the terminal bell in all such cases. -.It Fl R | -RAW-CONTROL-CHARS -Like -r, but only ANSI "color" escape sequences are output in "raw" form. -Unlike -r, the screen appearance is maintained correctly in most cases. -ANSI "color" escape sequences are sequences of the form: +Certain characters are special if entered at the beginning of the pattern; +they modify the type of search rather than become part of the pattern: +.Bl -tag -width Ds +.It Ic ^N | \&! +Search for lines which do NOT match the pattern. +.It Ic ^E | * +Search multiple files. +That is, if the search reaches the END of the current file +without finding a match, +the search continues in the next file in the command line list. +.It Ic ^F | @ +Begin the search at the first line of the FIRST file +in the command line list, +regardless of what is currently displayed on the screen +or the settings of the -a or -j options. +.It Ic ^K +Highlight any text which matches the pattern on the current screen, +but don't move to the first match (KEEP current position). +.It Ic ^R +Don't interpret regular expression metacharacters; +that is, do a simple textual comparison. +.El +.It Ic ?pattern +Search backward in the file for the N-th line containing the pattern. +The search starts at the line immediately before the top line displayed. .Pp -.Dl ESC \&[ ... m +Certain characters are special, as in the / command: +.Bl -tag -width Ds +.It Ic ^N | \&! +Search for lines which do NOT match the pattern. +.It Ic ^E | * +Search multiple files. +That is, if the search reaches the beginning of the current file +without finding a match, +the search continues in the previous file in the command line list. +.It Ic ^F | @ +Begin the search at the last line of the last file +in the command line list, +regardless of what is currently displayed on the screen +or the settings of the -a or -j options. +.It Ic ^K +As in forward searches. +.It Ic ^R +As in forward searches. +.El +.It Ic ESC-/pattern +Same as "/*". +.It Ic ESC-?pattern +Same as "?*". +.It Ic n +Repeat previous search, for N-th line containing the last pattern. +If the previous search was modified by ^N, the search is made for the +N-th line NOT containing the pattern. +If the previous search was modified by ^E, the search continues +in the next (or previous) file if not satisfied in the current file. +If the previous search was modified by ^R, the search is done +without using regular expressions. +There is no effect if the previous search was modified by ^F or ^K. +.It Ic N +Repeat previous search, but in the reverse direction. +.It Ic ESC-n +Repeat previous search, but crossing file boundaries. +The effect is as if the previous search were modified by *. +.It Ic ESC-N +Repeat previous search, but in the reverse direction +and crossing file boundaries. +.It Ic ESC-u +Undo search highlighting. +Turn off highlighting of strings matching the current search pattern. +If highlighting is already off because of a previous ESC-u command, +turn highlighting back on. +Any search command will also turn highlighting back on. +(Highlighting can also be disabled by toggling the -G option; +in that case search commands do not turn highlighting back on.) +.It Ic &pattern +Display only lines which match the pattern; +lines which do not match the pattern are not displayed. +If pattern is empty (if you type & immediately followed by ENTER), +any filtering is turned off, and all lines are displayed. +While filtering is in effect, an ampersand is displayed at the +beginning of the prompt, +as a reminder that some lines in the file may be hidden. .Pp -where the "..." is zero or more color specification characters. -For the purpose of keeping track of screen appearance, -ANSI color escape sequences are assumed to not move the cursor. -You can make -.Nm -think that characters other than "m" can end ANSI color escape sequences -by setting the environment variable -.Ev LESSANSIENDCHARS -to the list of characters which can end a color escape sequence. -And you can make -.Nm -think that characters other than the standard ones may appear between -the ESC and the m by setting the environment variable -.Ev LESSANSIMIDCHARS -to the list of characters which can appear. -.It Fl r | -raw-control-chars -Causes "raw" control characters to be displayed. -The default is to display control characters using the caret notation; -for example, a control-A (octal 001) is displayed as "^A". -Warning: when the -r option is used, +Certain characters are special as in the / command: +.Bl -tag -width Ds +.It Ic ^N | ! +Display only lines which do NOT match the pattern. +.It Ic ^R +Don't interpret regular expression metacharacters; +that is, do a simple textual comparison. +.El +.It Ic :e Op Ar filename +Examine a new file. +If the filename is missing, the "current" file (see the :n and :p commands +below) from the list of files in the command line is re-examined. +A percent sign (%) in the filename is replaced by the name of the +current file. +A pound sign (#) is replaced by the name of the previously examined file. +However, two consecutive percent signs are simply +replaced with a single percent sign. +This allows you to enter a filename that contains a percent sign +in the name. +Similarly, two consecutive pound signs are replaced with a single pound sign. +The filename is inserted into the command line list of files +so that it can be seen by subsequent :n and :p commands. +If the filename consists of several files, they are all inserted into +the list of files and the first one is examined. +If the filename contains one or more spaces, +the entire filename should be enclosed in double quotes +(also see the -" option). +.It Ic ^X^V | E +Same as :e. +Warning: some systems use ^V as a special literalization character. +On such systems, you may not be able to use ^V. +.It Ic :n +Examine the next file (from the list of files given in the command line). +If a number N is specified, the N-th next file is examined. +.It Ic :p +Examine the previous file in the command line list. +If a number N is specified, the N-th previous file is examined. +.It Ic :t +Go to the specified tag. +.It Ic :x +Examine the first file in the command line list. +If a number N is specified, the N-th file in the list is examined. +.It Ic :d +Remove the current file from the list of files. +.It Ic t +Go to the next tag, if there were more than one matches for the current tag. +See the \-t option for more details about tags. +.It Ic T +Go to the previous tag, if there were more than one matches for the current tag. +.It Ic = | ^G | :f +Prints some information about the file being viewed, including its name +and the line number and byte offset of the bottom line being displayed. +If possible, it also prints the length of the file, +the number of lines in the file +and the percent of the file above the last displayed line. +.It Ic \- +Followed by one of the command line option letters (see +.Sx OPTIONS +below), +this will change the setting of that option +and print a message describing the new setting. +If a ^P (CONTROL-P) is entered immediately after the dash, +the setting of the option is changed but no message is printed. +If the option letter has a numeric value (such as -b or -h), +or a string value (such as -P or -t), +a new value may be entered after the option letter. +If no new value is entered, a message describing +the current setting is printed and nothing is changed. +.It Ic \-\- +Like the \- command, but takes a long option name (see +.Sx OPTIONS +below) +rather than a single option letter. +You must press ENTER or RETURN after typing the option name. +A ^P immediately after the second dash suppresses printing of a +message describing the new setting, as in the \- command. +.It Ic \-+ +Followed by one of the command line option letters this will reset the +option to its default setting and print a message describing the new setting. +(The "\-+X" command does the same thing as "\-+X" on the command line.) +This does not work for string-valued options. +.It Ic \-\-+ +Like the \-+ command, but takes a long option name +rather than a single option letter. +.It Ic \-! +Followed by one of the command line option letters, this will reset the +option to the "opposite" of its default setting and print a message +describing the new setting. +This does not work for numeric or string-valued options. +.It Ic \-\-! +Like the \-! command, but takes a long option name +rather than a single option letter. +.It Ic _ +(Underscore.) +Followed by one of the command line option letters, +this will print a message describing the current setting of that option. +The setting of the option is not changed. +.It Ic __ +(Double underscore.) +Like the _ (underscore) command, but takes a long option name +rather than a single option letter. +You must press ENTER or RETURN after typing the option name. +.It Ic +cmd +Causes the specified cmd to be executed each time a new file is examined. +For example, +G causes .Nm -cannot keep track of the actual appearance of the screen -(since this depends on how the screen responds to -each type of control character). -Thus, various display problems may result, -such as long lines being split in the wrong place. -.It Fl S | -chop-long-lines -Causes lines longer than the screen width to be -chopped (truncated) rather than wrapped. -That is, the portion of a long line that does not fit in -the screen width is not shown. -The default is to wrap long lines; that is, display the remainder -on the next line. -.It Fl s | -squeeze-blank-lines -Causes consecutive blank lines to be squeezed into a single blank line. -.It Xo -.Fl T Ar tagsfile | -.Fl -tag-file Ns = Ns Ar tagsfile -.Xc -Specifies a tags file to be used instead of "tags". -.It Xo -.Fl t Ar tag | -.Fl -tag Ns = Ns Ar tag -.Xc -The -t option, followed immediately by a TAG, -will edit the file containing that tag. -For this to work, tag information must be available; -for example, there may be a file in the current directory called "tags", -which was previously built by -.Xr ctags 1 -or an equivalent command. -If the environment variable -.Ev LESSGLOBALTAGS -is set, it is taken to be the name of a command compatible with -.Xr global , -and that command is executed to find the tag. -(See -.Lk http://www.gnu.org/software/global/global.html ) . -The -t option may also be specified from within +to initially display each file starting at the end rather than the beginning. +.It Ic V +Prints the version number of .Nm -(using the \- command) as a way of examining a new file. -The command ":t" is equivalent to specifying -t from within +being run. +.It Ic q | Q | :q | :Q | ZZ +Exits .Nm less . -.It Fl U | -UNDERLINE-SPECIAL -Causes backspaces, tabs and carriage returns to be -treated as control characters; -that is, they are handled as specified by the -r option. +.El .Pp -By default, if neither -u nor -U is given, backspaces which appear adjacent -to an underscore character are treated specially: -the underlined text is displayed -using the terminal's hardware underlining capability. -Also, backspaces which appear between two identical characters -are treated specially: -the overstruck text is printed -using the terminal's hardware boldface capability. -Other backspaces are deleted, along with the preceding character. -Carriage returns immediately followed by a newline are deleted. -Other carriage returns are handled as specified by the -r option. -Text which is overstruck or underlined can be searched for -if neither -u nor -U is in effect. -.It Fl u | -underline-special -Causes backspaces and carriage returns to be treated as printable characters; -that is, they are sent to the terminal when they appear in the input. -.It Fl V | -version -Displays the version number of -.Nm less . -.It Fl W | -HILITE-UNREAD -Like -w, but temporarily highlights the first new line after any -forward movement command larger than one line. -.It Fl w | -hilite-unread -Temporarily highlights the first "new" line after a forward movement -of a full page. -The first "new" line is the line immediately following the line previously -at the bottom of the screen. -Also highlights the target line after a g or p command. -The highlight is removed at the next command which causes movement. -The entire line is highlighted, unless the -J option is in effect, -in which case only the status column is highlighted. -.It Fl X | -no-init -Disables sending the termcap initialization and deinitialization strings -to the terminal. -This is sometimes desirable if the deinitialization string does -something unnecessary, like clearing the screen. -.It Xo -.Fl x Ar n Ns , Ns Ar ... | -.Fl -tabs Ns = Ns Ar n Ns , Ns Ar ... -.Xc -Sets tab stops. -If only one n is specified, tab stops are set at multiples of n. -If multiple values separated by commas are specified, tab stops are set at -those positions, and then continue with the same spacing as the last two. -For example, -x9,17 will set tabs at positions 9, 17, 25, 33, etc. -The default for n is 8. -.It Xo -.Fl y Ar n | -.Fl -max-forw-scroll Ns = Ns Ar n -.Xc -Specifies a maximum number of lines to scroll forward. -If it is necessary to scroll forward more than n lines, -the screen is repainted instead. -The -c or -C option may be used to repaint from the top of -the screen if desired. -By default, any forward movement causes scrolling. -.It Xo -.Fl z Ar n | -.Fl -window Ns = Ns Ar n -.Xc -Changes the default scrolling window size to n lines. -The default is one screenful. -The z and w commands can also be used to change the window size. -The "z" may be omitted for compatibility with some versions of -.Nm more . -If the number -.Ar n -is negative, it indicates -.Ar n -lines less than the current screen size. -For example, if the screen is 24 lines, -z-4 sets the -scrolling window to 20 lines. -If the screen is resized to 40 lines, -the scrolling window automatically changes to 36 lines. -.It Fl -follow-name -Normally, if the input file is renamed while an F command is executing, -.Nm -will continue to display the contents of the original file despite -its name change. -If --follow-name is specified, during an F command -.Nm -will periodically attempt to reopen the file by name. -If the reopen succeeds and the file is a different file from the original -(which means that a new file has been created -with the same name as the original (now renamed) file), -.Nm -will display the contents of that new file. -.It Fl -no-keypad -Disables sending the keypad initialization and deinitialization strings -to the terminal. -This is sometimes useful if the keypad strings make the numeric -keypad behave in an undesirable manner. -.It Fl -use-backslash -This option changes the interpretations of options which follow this one. -After the --use-backslash option, any backslash in an option string is -removed and the following character is taken literally. -This allows a dollar sign to be included in option strings. -.It Xo -.Ar -cc | -.Fl -quotes Ns = Ns Ar cc -.Xc -Changes the filename quoting character. -This may be necessary if you are trying to name a file -which contains both spaces and quote characters. -Followed by a single character, this changes the quote character to that -character. -Filenames containing a space should then be surrounded by that character -rather than by double quotes. -Followed by two characters, changes the open quote to the first character, -and the close quote to the second character. -Filenames containing a space should then be preceded by the open quote -character and followed by the close quote character. -Note that even after the quote characters are changed, this option -remains -" (a dash followed by a double quote). -.It Fl ~ | -tilde -Normally lines after end of file are displayed as a single tilde (~). -This option causes lines after end of file to be displayed as blank lines. -.It Fl # | -shift -Specifies the default number of positions to scroll horizontally -in the RIGHTARROW and LEFTARROW commands. -If the number specified is zero, it sets the default number of -positions to one half of the screen width. -Alternately, the number may be specified as a fraction of the width -of the screen, starting with a decimal point: .5 is half of the -screen width, .3 is three tenths of the screen width, and so on. -If the number is specified as a fraction, the actual number of -scroll positions is recalculated if the terminal window is resized, -so that the actual scroll remains at the specified fraction -of the screen width. -.It Fl - -A command line argument of "--" marks the end of option arguments. -Any arguments following this are interpreted as filenames. -This can be useful when viewing a file whose name begins with a "-" or "+". -.It Cm + -If a command line option begins with +, -the remainder of that option is taken to be an initial command to -.Nm less . -For example, +G tells -.Nm -to start at the end of the file rather than the beginning, -and +/xyz tells it to start at the first occurrence of "xyz" in the file. -As a special case, + acts like +g; -that is, it starts the display at the specified line number -(however, see the caveat under the "g" command above). -If the option starts with ++, the initial command applies to -every file being viewed, not just the first one. -The + command described previously -may also be used to set (or change) an initial command for every file. +The following +four +commands may or may not be valid, depending on your particular installation. +.Bl -tag -width XXXX +.It Ic v +Invokes an editor to edit the current file being viewed. +The editor is taken from the environment variable +.Ev VISUAL , +if defined, +or +.Ev EDITOR +if +.Ev VISUAL +is not defined, +or defaults to "vi" if neither +.Ev VISUAL +nor +.Ev EDITOR +is defined. +See also the discussion of LESSEDIT under the section on +.Sx PROMPTS +below. +.It Ic \&! Ar shell-command +Invokes a shell to run the shell-command given. +A percent sign (%) in the command is replaced by the name of the current file. +A pound sign (#) is replaced by the name of the previously examined file. +"!!" repeats the last shell command. +"!" with no shell command simply invokes a shell. +The shell is taken from the environment variable +.Ev SHELL , +or defaults to "sh". +.\" On MS-DOS and OS/2 systems, the shell is the normal command processor. +.It Ic | Ar shell-command + represents any mark letter. +Pipes a section of the input file to the given shell command. +The section of the file to be piped is between the first line on +the current screen and the position marked by the letter. + may also be ^ or $ to indicate beginning or end of file respectively. +If is . or newline, the current screen is piped. +.It Ic s Ar filename +Save the input to a file. +This only works if the input is a pipe, not an ordinary file. .El .Sh LINE EDITING When entering command line at the bottom of the screen