page: Page through a file

Package: system

Usage

page files

Parameters

files: The list of files. If omitted, text is read from the standard input.

map_cc = yes: Map non-printing control characters into printable form, e.g., BEL (ctrl/G, ASCII 7) is printed as "^G".

clear_screen = no: If set, the screen is cleared before each page is written.

first_page = 1: The first page to be printed. Pages are defined by form feed characters embedded in the text.

prompt = "": Optional prompt string for the end-of-page prompt. If no prompt string is given the name of the file being paged is used.

device = "terminal": The output device. The special device text may be specified to represent standout mode with upper case rather than reverse video characters.

Description

Page displays a file on the terminal, one page of text at a time, pausing between successive pages of output until a key is typed on the terminal. Pages are normally broken when the screen fills, but may also be delimited by form feed characters embedded in the input text. A prompt is printed after each page of text naming the current file, showing the percentage of the file which has been displayed, and the numeric order of the file within the file list if a file template was given.

When the end of page prompt is displayed any of the following command keystrokes may be entered. Command keystrokes are input in raw mode, i.e., no carriage return is required to pass the command to the program.

.               go to the beginning of the current file    [BOF]
:               colon escape (see below)
?               display a one-line command summary
G               go to the end of the current file          [EOF]
N,<ctrl/n>      go to the next file
P,<ctrl/p>      go back to the previous file
b               back up one page
d               scroll down half a page of text
e               edit the current file
f,space         advance to the next page
j,return        scroll down one line
k               back up one line
n               search for the next occurrence of a pattern
q               quit
u               back up half a screen

<ctrl/c>        quit (interrupt)
<ctrl/z>        quit (EOF)
<ctrl/d>        quit (EOF)

If an unrecognized keystroke is entered the terminal will beep. The following colon commands are recognized in addition to the single keystroke commands described above.

:!<clcmd>       send a command to the CL (:!! for host command)
:/<pattern>     advance to line matching the given pattern
:file <fname>   display file "fname" (may be abbreviated)
:help           print summary of colon commands
:line [+/-]N    goto line N (relative move if +/- given)
:spool <fname>  spool output to the named file

The :clcmd facility is used to send commands to the CL from within the context of the pager. For example, ":!cl" will temporarily suspend the pager, allowing CL commands to be entered until the command "bye" is entered, causing execution of the pager to resume. Note that since the page task resides in the system process x_system.e, it will be necessary for the CL to connect a second system process if the command issued calls another task in the system package, since the first system process will still be running, i.e., executing the page task. This is harmless, but the second process may be removed from the process cache with flprcache if desired, after exiting the original page task.

The sequence ":/" followed by a pattern will cause the current input stream to be searched for the next occurrence of the pattern given. A pattern once entered is retained indefinitely and may be used in subsequent searches by typing the single keystroke `n', without need to reenter the pattern. Searching stops at the end of the current file, requiring a `.' to wrap back around to the beginning of the file, or a `N' to advance to the next file.

The :file command is used to change the current position within the file list specified by files, and may not be used to page a file not specified in the initial template. Note that the filename may be abbreviated, and that searching stops with the first file lexically greater than or equal to the given string (hence ":file x" might return file "y").

The :line N command may be used to randomly position to the indicated line within the current file. If the line number argument N is preceded by a plus or minus the argument is taken to be an offset from the current position.

The :spool command is used to spool output to a file. Each time a file line is printed on the screen, it is appended to the named file as well. One can interactively position to the desired line of the file and then turn on spooling to extract a portion of the file or stream being displayed. A subsequent :spool command with no filename will turn spooling off. Issuing a :spool to begin spooling on a new file when already spooling to some other file will cause the old spool file to be closed.

Examples

1. Page through all of the files in the directory "lib" which have the extension ".h".

cl> page lib$*.h

2. Use help to format the text in the file "doc$spp.hlp", displaying the formatted document beginning on page 5 (the entire document has to be formatted first so it takes a minute or so to get any output).

cl> help doc$spp.hlp fi+ | page first=5

3. Run rfits to print a long format listing of the headers of a series of FITS images from a magnetic tape, directing the output through page so that it does not flash by when you aren't looking.

cl> rfits mta make- long+ | page

Bugs

Since page does not currently buffer any input text, backwards motions and absolute line positioning are not permitted when paging the standard input.