From the IRAF Help pages:
LROFF (Nov83) Online Help Utilities LROFF (Nov83)
NAME
lroff -- line oriented text formatter
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 convienent 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" vlines.
.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.
FTOOLS HELP DESK If FTOOLS has been useful in your research, please reference this site (http://heasarc.gsfc.nasa.gov/ftools) and use the ASCL reference for HEASoft [ascl:1408.004] or the ASCL reference for the original FTOOLs paper [ascl:9912.002]: Blackburn, J. K. 1995, in ASP Conf. Ser., Vol. 77, Astronomical Data Analysis Software and Systems IV, ed. R. A. Shaw, H. E. Payne, and J. J. E. Hayes (San Francisco: ASP), 367. Web page maintained by: Bryan K. Irby |
