From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001 From: Joe Hunkeler Date: Tue, 11 Aug 2015 16:51:37 -0400 Subject: Repatch (from linux) of OSX IRAF --- pkg/system/help/lroff/lroff.hlp | 258 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 258 insertions(+) create mode 100644 pkg/system/help/lroff/lroff.hlp (limited to 'pkg/system/help/lroff/lroff.hlp') 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 -- cgit