path: root/pkg/system/help/lroff/lroff.hlp

.help lroff Nov83 "Online Help Utilities"
.ih
NAME
\fBlroff\fR -- line oriented text formatter
.ih
PURPOSE
\fBLroff\fR is a simple text formatter used by the IRAF on-line Help command,
and other utilities (MANPAGE, LIST), to format text.  
\fBLroff\fR style documentation text may be embedded in program source files.
\fBlroff\fR is line oriented, rather than page oriented,
and is implemented as a library procedure rather than as a task.
.ih
USAGE
status = lroff (input, output, left_margin, right_margin)
.ih
PARAMETERS
.ls input
An integer procedure, called by \fBlroff\fR to get lines of input,
which takes the \fBlroff\fR 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).
.le
.ls output
A procedure, called by \fBlroff\fR to output formatted lines of text,
which takes the \fBlroff\fR output buffer as an argument ("output (buffer)").
.le
.ls left_margin
The first column to be filled (>= 1).
.le
.ls right_margin
The last column to be filled.
.le
.ls status
ERR is returned if meaningless margins are specified, or if an unrecoverable
error occurs during processing.
.le
.ih
DESCRIPTION
\fBLroff\fR 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 \fBhelp\fR utility), or may be in a separate file.
The input text consists
of a mixture of lines of text and \fBlroff\fR directives.
\fBLroff\fR 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 \fBlroff\fR,
except at the end of a line.
\fBlroff\fR 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, \fBlroff\fR will properly
format ordinary paragraphs of text, and single line section headers,
without need for embedded directives.

Since the i/o routines used by \fBlroff\fR 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
\fBlroff\fR directives, to be intercepted by the user supplied INPUT procedure.
See the Manpage command for an example.


DIRECTIVES

Most of the \fBlroff\fR 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.

.ih
EXAMPLE
.sp
Many examples of the use of the \fBlroff\fR command directives in help text
can be found by browsing about in source listings.
A brief example is included here for convenient reference.
.sp
The ".help" directive, used to mark the beginning
of a block of help text, is used by HELP and MANPAGE rather than \fBlroff\fR.
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.
.sp
The \fBlroff\fR-format help text fragment
.sp
.ls
.nf
.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
.fi
.sp 2
.le
would be converted by \fBlroff\fR (as called from Help) into something like
the following.  Remember that the margins are runtime arguments to \fBlroff\fR.
Help does not print a header line, or break pages.
.sp 2
.in 8
NAME
.in 5
stcopy -- copy a string.
.in -5
.sp 2
PURPOSE
.in 5
Stcopy  is  used  to  copy  an  EOS delimited character
string.  The EOS delimiter MUST be present.
.in -5
.sp 2
USAGE
.in 5
stcopy (from, to, maxchar)
.in -5
.sp 2
PARAMETERS
.in 5
.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
.in -5
.sp 2
DESCRIPTION
.sp
.ih
SEE ALSO
help

The reader should note that MANPAGE, which is page oriented,
recognizes the following directives in addition to those recognized
by \fBlroff\fR: 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 \fBlroff\fR text, as they will be ignored by \fBlroff\fR if not
intercepted by the procedure calling \fBlroff\fR.

.ih
REQUEST SUMMARY
.sp
.nf
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.
.fi
.endhelp