Initial commit

1 files changed, 258 insertions, 0 deletions

diff --git a/pkg/system/help/lroff/lroff.hlp b/pkg/system/help/lroff/lroff.hlp
new file mode 100644
index 00000000..6607977b
--- /dev/null
+++ b/pkg/system/help/lroff/lroff.hlp
@@ -0,0 +1,258 @@
+.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