pg(1)

NAME

pg — file perusal filter for soft-copy terminals

SYNOPSIS

pg [- number] [-p string] [-cefnrs] [+ linenumber] [+/ pattern] [file ...]

Remarks

pg and more are both used in similar situations (see more(1)). Text highlighting features supported by more are not available from pg. However, pg has some useful features not provided by more.

DESCRIPTION

pg is a text file filter that allows the examination of files one screenful at a time on a soft-copy terminal. If - is used as a file argument, or pg detects NULL arguments in the comand line, the standard input is used. Each screenful is followed by a prompt. To display a new page, press Return. Other possibilities are enumerated below.

This command is different from other paginators such as more in that it can back up for reviewing something that has already passed. The method for doing this is explained below.

In order to determine terminal attributes, pg scans the terminfo data base for the terminal type specified by the environment variable TERM (see terminfo(4)). If TERM is not defined, terminal type dumb is assumed.

Options

pg recognizes the following command line options:

-number: number is an integer specifying the size (in lines) of the window that pg is to use instead of the default (on a terminal containing 24 lines, the default window size is 23).
-p string: Causes pg to use string as the prompt. If the prompt string contains a %d, the first occurrence of %d in the prompt is replaced by the current page number when the prompt is issued. The default prompt string is a colon (:).
-c: Home the cursor and clear the screen before displaying each page. This option is ignored if clear_screen is not defined in the terminfo data base for this terminal type.
-e: Causes pg to not pause at the end of each file.
-f: Normally, pg splits lines longer than the screen width, but some sequences of characters in the text being displayed (such as escape sequences for underlining) generate undesirable results. The -f option inhibits pg from splitting lines.
-n: Normally, commands must be terminated by a new-line character. This option causes an automatic end-of-command as soon as a command letter is entered.
-r: Restricted mode. The shell escape is disallowed. pg will print an error message but does not exit.
-s: Causes pg to print all messages and prompts in standout mode (usually inverse video).
+linenumber: Start display at linenumber.
+/pattern/: Start up at the first line containing text that matches the regular expression pattern.

pg looks in the environment variable PG to preset any flags desired. For example, if you prefer to view files using the -c mode of operation, the POSIX-shell command sequence PG='-c' ; export PG or the C-shell command setenv PG -c causes all invocations of pg, including invocations by programs such as man and msgs, to use this mode. The command sequence to set up the PG environment variable is normally placed in the user .profile or .cshrc file. No form of quoting is provided, so the string and pattern arguments are limited to single word.

The responses that can be typed when pg pauses can be divided into three categories: those causing further perusal, those that search, and those that modify the perusal environment.

Commands that cause further perusal normally take a preceding address, an optionally signed number indicating the point from which further text should be displayed. This address is interpreted either in pages or lines, depending on the command. A signed address specifies a point relative to the current page or line; an unsigned address specifies an address relative to the beginning of the file. Each command has a default address that is used if none is provided.

Perusal commands and their defaults are as follows:

(+1)<newline> or <blank>: Displays one page. The address is specified in pages.
(+1) l: With a relative address, pg simulates scrolling the screen, forward or backward, the number of lines specified. With an absolute address pg prints a screenful beginning at the specified line.
(+1) d or ^D: Simulates scrolling a half-screen forward or backward.
if: Skip i screens of text.
iz: Same as newline except that i , if present, becomes the new default number of lines per screenful.

The following perusal commands take no address:

. or ^L: Typing a single period causes the current page of text to be redisplayed.
$: Displays the last windowful in the file. Use with caution when the input is a pipe.

The following commands are available for searching for text patterns in the text. The Basic Regular Expression syntax (see regexp(5)) is supported. The terminal /, ^, or ? can be omitted from the pattern search commands. Regular expressions must always be terminated by a new-line character, even if the -n option is specified.

i/pattern/: Search forward for the ith (default i=1) occurrence of pattern. Searching begins immediately after the current page and continues to the end of the current file, without wrap-around.
i^pattern^
i?pattern?: Search backwards for the ith (default i=1) occurrence of 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 cannot properly handle the ?.

After searching, pg normally displays the line found at the top of the screen. This can be modified by appending m or b to the search command to leave the line found in the middle or at the bottom of the window from now on. The suffix t can be used to restore the original situation.

pg users can modify the perusal environment with the following commands:

in: Begin perusing the ith next file in the command line. The i is an unsigned number, default value is 1.
ip: Begin perusing the ith previous file in the command line. i is an unsigned number, default is 1.
iw: Display another window of text. If i is present, set the window size to i.
s filename: Save the input in the named file. Only the current file being perused is saved. The white space between the s and filename is optional. This command must always be terminated by a new-line character, even if the -n option is specified.
h: Help by displaying an abbreviated summary of available commands.
q or Q: Quit pg.
!command: command is passed to the shell, whose name is taken from the SHELL environment variable. If this is not available, the default shell is used. This command must always be terminated by a new-line character, even if the -n option is specified.

At any time when the output is being sent to the terminal, the user can press the quit key (normally CTRL-\), the interrupt (break) key or the DEL key. This causes pg to stop sending output, and display the prompt. The user may then enter one of the commands in the normal manner. Unfortunately, some output is lost when this is done, due to the fact that any characters waiting in the terminal's output queue are flushed when the quit signal occurs.

If the standard output is not a terminal, pg is functionally equivalent to cat (see cat(1)), except that a header is printed before each file if more than one file is specified.

EXTERNAL INFLUENCES

Environment Variables

LC_COLLATE determines the collating sequence used in evaluating regular expressions.

LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, and the characters matched by character class expressions in regular expressions.

LANG determines the language in which messages are displayed.

If LC_COLLATE or LC_CTYPE is not specified in the environment or is set to the empty string, the value of LANG is used as a default for each unspecified or empty variable. If LANG is not specified or is set to the empty string, a default of "C" (see lang(5)) is used instead of LANG. If any internationalization variable contains an invalid setting, pg behaves as if all internationalization variables are set to "C". See environ(5).

International Code Set Support

Single- and multi-byte character code sets are supported.

EXAMPLES

To use pg when reading system news:

news | pg -p "(Page %d):" 

WARNINGS

If terminal tabs are not set every eight positions, undesirable results may occur.

When using pg as a filter with another command that changes the terminal I/O options (such as crypt(1)), terminal settings may not be restored correctly.

While waiting for terminal input, pg responds to BREAK, DEL, and ^ by terminating execution. Between prompts, however, these signals interrupt pg's current task and place the user in prompt mode. These should be used with caution when input is being read from a pipe, because an interrupt is likely to terminate the other commands in the pipeline.

Users of more will find that the z and f commands are available, and that the terminal /, ^, or ? can be omitted from the pattern search commands.

FILES

/usr/share/lib/terminfo/?/*: terminal information data base
/tmp/pg*: temporary file when input is from a pipe

STANDARDS CONFORMANCE

pg: SVID2, SVID3, XPG2, XPG3