pg(C) 06 January 1993 pg(C) Name pg - paginate display for soft-copy terminals Syntax pg [ -number ] [ -p string ] [ -cefns ] [ +linenumber ] [ +/pattern/ ] [ files ... ] Description The pg command is a filter which allows the examination of files one screenful at a time on a terminal. (The dash (-) command line option and/or NULL arguments indicate that pg should read from the standard input.) Each screenful is followed by a prompt. If you press the <Return> key, another page is displayed; other possibilities are listed below. This command is different from previous paginators because it allows you to back up and review something that has already passed. To determine terminal attributes, pg scans the termcap(F) database for the terminal type specified by the environment variable TERM. If TERM is not defined, the terminal type dumb is assumed. The command line options are: -number Specifies 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 will be replaced by the current page number when the prompt is issued. The default prompt string is a colon (:). -c Homes the cursor and clears the screen before displaying each page. This option is ignored if cl (clear screen) is not defined for this terminal type in the termcap(F) database. -e Causes pg not to pause at the end of each file. -f Inhibits pg from splitting lines. In the absence of the -f option, pg splits lines longer than the screen width, but some sequences of characters in the displayed text (for exam- ple, escape sequences for underlining) give undesirable results. -n Normally, commands must be terminated by pressing the <Return> key (ASCII newline character). This option causes an automatic end of command as soon as a command letter is entered. -s Causes pg to display all messages and prompts in standout mode (usually inverse video). +linenumber Starts up at linenumber. +/pattern/ Starts up at the first line containing the regular expression pattern. The responses that may be entered when pg pauses can be divided into three categories: those that cause further perusal, those that search, and those that modify the perusal environment. Commands which cause further perusal normally take a preceding address (an optionally signed number indicating the point from which further text should be displayed). pg interprets this address in either pages or lines depending on the command. A signed address specifies a point rela- tive to the current page or line, and an unsigned address specifies an address relative to the beginning of the file. Each command has a default address if no address is provided. The perusal commands and their defaults are as follows: (+1) <Return> Causes one page to be displayed. The address is specified in pages. (+1) l With a signed address, causes pg to simulate scrolling the screen, forward or backward, the number of lines specified. With an unsigned address this command displays a full screen of text beginning at the specified line. (+1) d or <Ctrl>d Simulates scrolling half a screen forward or backward. The following perusal commands take no address: . or <Ctrl>l Causes the current page of text to be redisplayed. $ Displays the last screen of text in the file. Use with cau- tion when the input is a pipe. The following commands are available for searching for text patterns in the text. The regular expressions described in ed(C) are available. They must always be terminated by a newline character, even if the -n option is specified. i /pattern/ Search forward for the ith (default i=1) occurrence of pat- tern. 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 pat- tern. Searching begins immediately before the current page and continues to the beginning of the current file, without wrap-around. The caret (^) notation is useful for terminals which will not properly handle the question mark (?). After searching, pg displays the line found at the top of the screen. You can modify this 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. Use the suffix t to restore the original situation. The following commands modify the environment of perusal: i n Begins perusing the ith next file in the command line. The default value of i is 1. i p Begins perusing the ith previous file in the command line. The default value of i is 1. i w Displays another window of text. If i is present, set the window size to i. s filename Saves 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 newline character, even if the -n option is specified. h Help displays 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 ter- minated by a newline character, even if the -n option is specified. At any time when output is being sent to the terminal, the user can press the QUIT key (normally <Ctrl>\) or the INTERRUPT key (normally <Break>). This causes pg to stop sending output, and display the prompt. The user may then enter one of the above commands in the normal manner. Unfor- tunately, 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. If the standard output is not a terminal, then pg acts just like cat(C), except that a header is printed before each file (if there is more than one). Examples To use pg to read system news, enter: news | pg -p "(Page %d):" Files /etc/termcap Terminal information database /tmp/pg* Temporary file when input is from a pipe See also cat(C), ed(C), grep(C), more(C) and termcap(F). Notes 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, terminal settings may not be restored correctly. While waiting for terminal input, pg responds to <Ctrl><Break> and <Del> by terminating execution. Between prompts, however, these signals inter- rupt pg's current task and place you in prompt mode. Use these signals with caution when input is being read from a pipe, since an interrupt is likely to terminate the other commands in the pipeline. The z and f commands used with more(C) are available, and the terminal slash (/), caret (^), or question mark (?) may be omitted from the searching commands. Standards conformance pg is conformant with: AT&T SVID Issue 2; and X/Open Portability Guide, Issue 3, 1989.