'\"macro stdmacro
.if n .pH g1.pg @(#)pg	40.6 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} pg 1 "Directory and File Management Utilities" "\&"
.if \nX=1 .ds x} pg 1 "Directory and File Management Utilities"
.if \nX=2 .ds x} pg 1 "" "\&"
.if \nX=3 .ds x} pg "" "" "\&"
.TH \*(x}
.SH NAME
\f4pg\f1 \- file perusal filter for \s-1CRT\s+1s
.SH SYNOPSIS
\f4pg\f1
[
.I \-number
] [
\f4\-p\f1
.I string
] [
\f4\-cefnrs\f1
] [
\f4+\f2linenumber\f1
] [
\f4+/\f2pattern\f4/\f1
] [
.I file\0...
]
.SH DESCRIPTION
.PP
The
\f4pg\fP
command is a filter that allows the examination
of
.I files
one screenful
at a time on a \s-1CRT\s+1.
(If no
.I file
is specified or if it encounters the file name
\f4\-\fP,
\f4pg\fP reads from standard input.)
Each screenful is followed by a prompt.
If the user types a carriage return, another page is displayed;
other possibilities are listed below.
.PP
This command is different from previous paginators
in that it allows you to back up
and review something that has already passed.
The method for doing this is explained below.
.PP
To determine terminal attributes,
\f4pg\fP
scans the
\f4terminfo\fP(4)
data base for the terminal type specified by the
environment variable
\f4TERM\f1.
If
\f4TERM\f1
is not defined,
the terminal type
\f4dumb\f1
is assumed.
.PP
The command line options are:
.TP
.I \-number
An integer specifying the size (in lines)
of the window that
\f4pg\fP
is to use instead of the default.
(On a terminal containing 24 lines, the default window size is 23).
.TP
\f4\-c\f1
Home the cursor and clear the screen before displaying each page.
This option is ignored if
\f4clear_screen\f1
is not defined for this terminal type in the
\f4terminfo\fP(4)
data base.
.TP
\f4\-e\f1
Causes
\f4pg\fP
.I not
to pause at the end of each file.
.TP
\f4\-f\f1
Normally,
\f4pg\fP
splits lines longer than the screen width,
but some sequences of characters
in the text being displayed
(e.g., escape sequences for underlining)
generate undesirable results.
The
\f4\-f\f1
option inhibits
\f4pg\fP
from splitting lines.
.TP
\f4\-n\f1
Normally, commands must be terminated by a
.RI < newline >
character.
This option causes an automatic end of command as soon as a command
letter is entered.
.TP
\f4\-p\f2 string\f1
Causes
\f4pg\fP
to use 
.I string
as the prompt.
If the prompt string contains a \f4%d\fP, the first occurrence
of \f4%d\fP' in the prompt will be replaced
by the current page number when the prompt is issued.
The default prompt string is
\f1``\f4:\f1''.
.TP
\f4\-r\f1
Restricted mode.
The shell escape is disallowed.
\f4pg\fP
will print an error message but does not exit.
.TP
\f4\-s\f1
Causes 
\f4pg\fP
to print all messages and prompts in standout
mode (usually inverse video).
.TP
\f4+\f2linenumber\f1
Start up at
.IR linenumber .
.TP
\f4+/\f2pattern\f4/\f1
Start up at the first line containing
the regular expression pattern.
.PP
The responses that may be typed when
\f4pg\fP
pauses can be divided
into three categories: those causing further perusal, those that
search, and those that modify the perusal environment.
.PP
Commands that cause further perusal normally take a preceding
.IR address ,
an optionally signed number indicating the point from which
further text should be displayed.
This
.I address
is interpreted in either pages or lines depending
on the command.
A signed
.I address
specifies a point relative to the current page
or line, and an unsigned
.I address
specifies an address relative
to the beginning of the file.
Each command has a default address that is used if none is provided.
.PP
The perusal commands and their defaults are as follows:
.TP
.RI (+1)< newline "> or <" blank >
This causes one page to be displayed.
The address is specified in pages.
.TP
\f1(+1) \f4l\f1
With a relative address
this causes
\f4pg\fP
to simulate scrolling the screen, forward or backward,
the number of lines specified.
With an absolute address
this command prints a screenful
beginning at the specified line.
.TP
\f1(+1) \f4d\f1 or \f4^D\f1
Simulates scrolling half a screen forward or backward.
.TP
\f2i\f4f\f1
Skip
.I i
screens of text.
.TP
\f2i\f4z\f1
Same as <\f2newline\f1> except that
.IR i ,
if present, becomes the new default number of lines per screenful.
.PP
The following perusal commands take no
.IR address .
.TP
\f4\&.\f1 or \f4^L\f1
Typing a single period causes the current page of text
to be redisplayed.
.TP
\f4$\f1
Displays the last windowful in the file.
Use with caution when the input is a pipe.
.PP
The following commands are available for searching for text patterns
in the text.
The regular expressions described in
\f4ed\fP(1)
are available.
They must always be terminated by a
.RI < newline >,
even if the
.I \-n
option is specified.
.TP
\f2i\f4/\f2pattern\f4/\f1
Search forward for the
.IR i th
(default
.IR i =1)
occurrence
of
.IR pattern .
Searching begins immediately after the current page and continues to the
end of the current file, without wrap-around.
.PP
\f2i\f4^\f2pattern\f4^\f1
.PD 0
.TP
\f2i\f4?\f2pattern\f4?\f1
Search backwards for the
.IR i th
(default
.IR i =1)
occurrence of
.IR pattern .
Searching begins immediately before the current page
and continues to the beginning of the current file, without
wrap-around.
The ^ notation is useful for Adds 100 terminals which will not properly
handle the ?.
.PD
.PP
After searching,
\f4pg\fP
will normally display the line found at the top of the screen.
This can be modified by appending
\f4m\f1
or
\f4b\f1
to the search
command to leave the line found in the middle or at the bottom of
the window from now on.
The suffix
\f4t\f1
can be used to restore the original situation.
.PP
The user of
\f4pg\fP
can modify the environment of perusal with the
following commands:
.TP
\f2i\f4n\f1
Begin perusing the
.IR i th
next file in the command line.
The
.I i
is an unsigned number, default value is 1.
.TP
\f2i\f4p\f1
Begin perusing the
.IR i th
previous file in the command line.
.I i
is an unsigned number, default is 1.
.TP
\f2i\f4w\f1
Display another window of text.
If
.I i
is present, set the window size to
.IR i .
.TP
\f4s \f2filename\f1
Save the input in the named file.
Only the current file being perused is saved.
The white space between the
\f4s\f1
and
.I filename
is optional.
This command must always be terminated by a
.RI < newline >,
even if the
.I \-n
option is specified.
.TP
\f4h\f1
Help by displaying an abbreviated summary of available commands.
.TP
\f4q\f1 or \f4Q\f1
Quit
\f4pg\fP.
.TP
\f4!\f2command\f1
.I Command
is passed to the shell, whose name is
taken from the
\f4SHELL\f1
environment variable.
If this is not available, the default shell is used.
This command must always be terminated by a
.RI < newline >,
even if the
.I \-n
option is specified.
.PP
At any time when output is being sent to the terminal, the user can hit
the quit key (normally \s-1CTRL\s+1-\\) or the interrupt (break) key.
This causes
\f4pg\fP
to stop sending output, and display the prompt.
The user may then enter one of the above commands in the normal manner.
Unfortunately, some output is lost when this is done, because
any characters waiting in the terminal's output queue are flushed
when the quit signal occurs.
.PP
If the standard output is not a terminal, then
\f4pg\fP
acts just like
\f4cat\fP(1),
except that a header is printed before each file (if there is
more than one).
.SH EXAMPLE
The following command line uses
\f4pg\fP
to read the system news:
.PP
.RS
.ft 4
news | pg \-p "(Page %d):"
.ft 1
.RE
.SH FILES
.PD 0
.TP 25
\f4/usr/share/lib/terminfo/?/\(**\fP
terminal information database
.TP
\f4/tmp/pg*\fP
temporary file when input is from a pipe
.PD
.SH SEE ALSO
\f4ed\fP(1),
\f4grep\fP(1),
\f4more\fP(1)
.br
\f4terminfo\fP(4) in the
.IR "System Administrator's Reference Manual" .
.SH NOTES
While waiting for terminal input,
\f4pg\fP
responds to
\s-1BREAK\s+1,
\s-1DEL\s+1,
and
\s-1CTRL\s+1-\\
by terminating execution.
Between prompts, however, these signals interrupt
\f4pg\fP's
current task and place the user in prompt mode.
These should be used with caution when input is being read from
a pipe, since an interrupt is likely to terminate the other
commands in the pipeline.
.PP
The terminal
\f4/\f1,
\f4^\f1,
or
\f4?\f1
may be omitted
from the searching commands.
.PP
If terminal tabs are not set every eight positions,
undesirable results may occur.
.PP
When using
\f4pg\fP
as a filter with another command that changes the terminal I/O options,
terminal settings may not be restored correctly.
.\"	@(#)pg.1	6.4 of 9/2/83
.Ee
