lroff: Lroff (line-roff) text formatter

Package: softools

Purpose

Lroff is a simple text formatter used by the IRAF on-line Help command, and other utilities (MANPAGE, LIST), to format text. Lroff style documentation text may be embedded in program source files. lroff is line oriented, rather than page oriented, and is implemented as a library procedure rather than as a task.

Usage

status = lroff (input, output, left_margin, right_margin)

Parameters

input

An integer procedure, called by lroff to get lines of input, which takes the lroff input buffer as an argument, and which returns EOF upon End of File (like GETLINE). Each line of input must be terminated by a newline and an EOS (End Of String marker).

output

A procedure, called by lroff to output formatted lines of text, which takes the lroff output buffer as an argument ("output (buffer)").

left_margin

The first column to be filled (>= 1).

right_margin

The last column to be filled.

status

ERR is returned if meaningless margins are specified, or if an unrecoverable error occurs during processing.

Description

Lroff input may be bracketed by ".help" and ".endhelp" directives in the actual source file of the program being documented (if intended as input to the help utility), or may be in a separate file. The input text consists of a mixture of lines of text and lroff directives. Lroff recognizes only a few directives, summarized in the "Request Summary" below. Whenever a directive performs the same function as a UNIX TROFF directive, the name is the same. Unrecognized directives are ignored, and are not passed on to the output. Directives must be left justified and preceeded by a period.

Help text need not be formatted unless desired. Filling and justification are NOT ENABLED unless a legal directive (other than ".nf") is given on the line immediately following the ".help" directive.

While filling, embedded whitespace in text IS significant to lroff, except at the end of a line. lroff recognizes no special characters. Blank lines cause a break, and are passed on to the output (a blank line is equivalent to ".sp"). Case is not significant in command directives. Control characters embedded in text will be passed on to the output.

Since both whitespace and blank lines are significant, lroff will properly format ordinary paragraphs of text, and single line section headers, without need for embedded directives.

Since the i/o routines used by lroff are parameterized, pagination can be achieved by having the user supplied OUTPUT procedure count output lines. Similarly, pagination control directives can be added to the list of lroff directives, to be intercepted by the user supplied INPUT procedure. See the Manpage command for an example.

DIRECTIVES

Most of the lroff directives function the same as in the UNIX text formatters. For the benefit of readers without experience with UNIX, "filling" means collecting words of text until an output line has been filled, and "justification" refers to adding extra spaces between words to cause the output line to be both left and right justified (as in this paragraph). Filling is disabled with NF, and resumes following a FI. While filling is disabled, only the control directives FI and RJ will be recognized. Justification is enabled with JU, and disabled with NJ. The filling of an output line may be stopped, and the line output, with BR. SP (or a blank line) does the same thing, outputting one or more blank lines as well. CE causes the current line to be broken, and outputs the next line of input, centered.

The directive ".rj text" breaks the current line, and outputs the next line of input, unfilled, with "text" right justified on the same line. RJ is especially useful for numbering equations. The RJ directive is recognized whether or not filling is in effect.

SH and IH may be used for section headers. Both cause a break, followed by a couple blank lines, followed by the next line of input, left justified on the output line. The left margin is reset to its initial value. If IH is used, the text following the section header will be indented one level in from the left margin. The number of lines of blank lines before the heading, and the amount of indentation, are optional arguments. The default values are shown in the request summary below. If values other than the defaults are desired, they need only be supplied as arguments once. Succeeding calls will continue to use the new values.

The IH and LS directives are especially useful in help text (manual pages). LS with a label string is useful for parameter lists, as shown in the example below. LS without a label string is used for relative indenting. A following LE restores the previous level of indentation.

The LS directive has the form ".ls [n] [stuff]", where "n" (optional) is the amount by which the following text is to be indented, and "stuff" is the (optional) label for the indented text block. LS causes a break, followed by one blank line, then the label string (if given), left justified. If the length of "stuff" is less than N-1 characters, the text block will start filling on the same line, otherwise on the next line. The indented text block may contain anything, including additional LS directives if nesting is desired. A matching LE eventually terminates the block, restoring the previous level of indentation.

The LS directive takes the most recent argument as the new default indentation, allowing the argument to be omitted in subsequent calls. To keep the current default value from being changed, use a negative argument.

Example

Many examples of the use of the lroff command directives in help text can be found by browsing about in source listings. A brief example is included here for convenient reference.
The ".help" directive, used to mark the beginning of a block of help text, is used by HELP and MANPAGE rather than lroff. The (optional) arguments to ".help" are the keyword name of the help text block, and two strings. The keyword argument may be a list of the form ".help keyw1, keyw2, ..., keywn", if more than one keyword is appropriate. The first keyword in the list is placed in the header of a manual page, followed by the first string, in parenthesis. The second string, if given, is centered in the header line. The strings need not be delimited unless they contain whitespace.
The lroff-format help text fragment

.help stcopy   2       "string utilities"
.ih
NAME
stcopy -- copy a string.
.ih
PURPOSE
Stcopy is used to copy an EOS delimited character
string.  The EOS delimiter MUST be present.
.ih
USAGE
stcopy (from, to, maxchar)
.ih
PARAMETERS
.ls from
The input string.
.le
.ls to
The output string, of length no less than "maxchar"
characters (excluding the EOS).
.le
.ls maxchar
The maximum number of characters to be copied.
Note that "maxchar" does not include the EOS.
Thus, the destination string must contain storage
for at least (maxchar + 1) characters.
.le
.ih
DESCRIPTION
...

would be converted by lroff (as called from Help) into something like the following. Remember that the margins are runtime arguments to lroff. Help does not print a header line, or break pages.

NAME
stcopy -- copy a string.

PURPOSE
Stcopy is used to copy an EOS delimited character string. The EOS delimiter MUST be present.

USAGE
stcopy (from, to, maxchar)

PARAMETERS

from

The input string.

to

The output string, of length no less than "maxchar" characters (excluding the EOS).

maxchar

The maximum number of characters to be copied. Note that "maxchar" does not include the EOS. Thus, the destination string must contain storage for at least (maxchar + 1) characters.

DESCRIPTION
...

See also

help

The reader should note that MANPAGE, which is page oriented, recognizes the following directives in addition to those recognized by lroff: BP (break page), and KS, KE (start and end keep). MANPAGE also omits blank lines at the top of a page. These directives may safely be included in lroff text, as they will be ignored by lroff if not intercepted by the procedure calling lroff.

Request summary

Request Initial Default  Break          Meaning

  .fi     yes             yes   Begin filling output lines.
  .nf     no              yes   Stop filling output lines.
  .ju     yes             no    Right justify output lines.
  .nj     no              no    Don't right justify.
  .rj text                yes   Rt justify text on next line.
  .sh n           n=2     yes   Skip n lines, start section.
  .ih m n       m=2,n=5   yes   Like SH, but indent n spaces.
  .br                     yes   Stop filling current line.
  .ce                     yes   Center following line.
  .sp n           n=1     yes   Space "n" lines.
  .in n   n=0     n=0     yes   Set left margin to "current+n".
  .ls n label     n=8     yes   Begin labeled text block.
  .le                     yes   End labeled text block.

additional directives provided by MANPAGE:

  .bp                     yes   Start a new page of output.
  .tp n   n=4             yes   Break page if < n lines left.
  .ks                     yes   Begin saving output.
  .ke                     yes   Output saved text all on one page.