417 lines
15 KiB
Plaintext
417 lines
15 KiB
Plaintext
.\" Copyright (C) Caldera International Inc. 2001-2002. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions are
|
|
.\" met:
|
|
.\"
|
|
.\" Redistributions of source code and documentation must retain the above
|
|
.\" copyright notice, this list of conditions and the following
|
|
.\" disclaimer.
|
|
.\"
|
|
.\" Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\"
|
|
.\" This product includes software developed or owned by Caldera
|
|
.\" International, Inc. Neither the name of Caldera International, Inc.
|
|
.\" nor the names of other contributors may be used to endorse or promote
|
|
.\" products derived from this software without specific prior written
|
|
.\" permission.
|
|
.\"
|
|
.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
|
|
.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
.\" DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
|
|
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
|
|
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
|
|
.\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
|
|
.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)m4 8.1 (Berkeley) 8/14/93
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.tr |
|
|
.mh
|
|
Hyphenation.
|
|
.pg
|
|
The automatic hyphenation may be switched off and on.
|
|
When switched on with \fBhy\fR,
|
|
several variants may be set.
|
|
A \fIhyphenation indicator\fR character may be imbedded in a word to
|
|
specify desired hyphenation points,
|
|
or may be prepended to suppress hyphenation.
|
|
In addition,
|
|
the user may specify a small exception word list.
|
|
.pg
|
|
Only words that consist of a central alphabetic string
|
|
surrounded by (usually null) non-alphabetic strings
|
|
are considered candidates for automatic hyphenation.
|
|
Words that were input containing hyphens
|
|
(minus),
|
|
em-dashes (\fB\e(em\fR),
|
|
or hyphenation indicator characters\
|
|
\(emsuch as mother-in-law\(em\
|
|
are \fIalways\fR subject to splitting after those characters,
|
|
whether or not automatic hyphenation is on or off.
|
|
.h1
|
|
.bt
|
|
\fB&nh\fR hyphenate - E \
|
|
Automatic hyphenation is turned off.
|
|
.bt
|
|
\fB&hy\fIN\fR on,\fIN=\fR1 on,\fIN=\fR1 E \
|
|
Automatic hyphenation is turned on
|
|
for \fIN\fR\|\(>=1, or off for \fIN=\fR\|0.
|
|
If \fIN=\fR\|2, \fIlast\fR lines (ones that will cause a trap)
|
|
are not hyphenated.
|
|
For \fIN=\fR\|4 and 8, the last and first two characters
|
|
respectively of a word are not split off.
|
|
These values are additive;
|
|
i.|e. \fIN=\fR\|14 will invoke all three restrictions.
|
|
.bt
|
|
\fB&hc\fI|c\fR \fB\e% \e%\fR E Hyphenation indicator character is set
|
|
to \fIc\fR or to the default \fB\e%\fR.
|
|
The indicator does not appear in the output.
|
|
.bt
|
|
\fB&hw\fI|word1|...\fR ignored - Specify hyphenation points in words
|
|
with imbedded minus signs.
|
|
Versions of a word with terminal \fIs\fR are implied;
|
|
i.|e. \fIdig\-it\fR implies \fIdig\-its\fR.
|
|
This list is examined initially \fIand\fR after
|
|
each suffix stripping.
|
|
The space available is small\(emabout 128 characters.
|
|
.mh
|
|
Three Part Titles.
|
|
.pg
|
|
The titling function \fBtl\fR provides for automatic placement
|
|
of three fields at the left, center, and right of a line
|
|
with a title-length
|
|
specifiable with \fBlt\fR.
|
|
\fBtl\fR may be used anywhere, and is independent of the
|
|
normal text collecting process.
|
|
A common use is in header and footer macros.
|
|
.h1
|
|
.bt
|
|
\fB&tl\fI|\'left\|\'center\|\'right\|\'\fR - - \
|
|
The strings \fIleft\fR, \fIcenter\fR, and \fIright\fR are
|
|
respectively left-adjusted, centered, and right-adjusted
|
|
in the current title-length.
|
|
Any of the strings may be empty,
|
|
and overlapping is permitted.
|
|
If the page-number character (initially \fB%\fR) is found within any of the fields it is replaced
|
|
by the current page number having the format assigned to register \fB%\fR.
|
|
Any character may be used as the string delimiter.
|
|
.bt
|
|
\fB&pc\fI|c\fR \fB%\fR off - The page number character is set to \fIc\fR,
|
|
or removed.
|
|
The page-number register remains \fB%\fR.
|
|
.bt
|
|
\fB<\fI|\(+-N\fR 6.5\|in previous E,\fBm\fR Length of title set to \fI\(+-N\fR.
|
|
The line-length and the title-length are \fIindependent\fR.
|
|
Indents do not apply to titles; page-offsets do.
|
|
.mh
|
|
Output Line Numbering.
|
|
.pg
|
|
.ll -\w'0000'u
|
|
.nm 1 3
|
|
Automatic sequence numbering of output lines may be
|
|
requested with \fBnm\fR.
|
|
When in effect,
|
|
a three-digit, arabic number plus a digit-space
|
|
is prepended to output text lines.
|
|
The text lines are thus offset by four digit-spaces,
|
|
and otherwise retain their line length;
|
|
a reduction in line length may be desired to keep the right margin
|
|
aligned with an earlier margin.
|
|
Blank lines, other vertical spaces, and lines generated by \fBtl\fR
|
|
are \fInot\fR numbered.
|
|
Numbering can be temporarily suspended with \fBnn\fR,
|
|
or with an \fB.nm\fR followed by a later \fB.nm|+0\fR.
|
|
In addition,
|
|
a line number indent \fII\fR, and the number-text separation \fIS\fR
|
|
may be specified in digit-spaces.
|
|
Further, it can be specified that only those line numbers that are
|
|
multiples of some number \fIM\fR are to be printed (the others will appear
|
|
as blank number fields).
|
|
.br
|
|
.nm
|
|
.ll
|
|
.h1
|
|
.bt
|
|
\fB&nm\fI|\(+-N|M|S|I\fR off E \
|
|
Line number mode.
|
|
If \fI\(+-N\fR is given,
|
|
line numbering is turned on,
|
|
and the next output line numbered is numbered \fI\(+-N\fR.
|
|
Default values are \fIM=\fR\|1, \fIS=\fR\|1, and \fII=\fR\|0.
|
|
Parameters corresponding to missing arguments are unaffected;
|
|
a non-numeric argument is considered missing.
|
|
In the absence of all arguments, numbering is turned off;
|
|
the next line number is preserved for possible further use
|
|
in number register \fBln\fR.
|
|
.bt
|
|
\fB&nn\fI|N\fR - \fIN=\fR1 E The next \fIN\fR text output lines are not
|
|
numbered.
|
|
.pg
|
|
.ll -\w'0000'u
|
|
.nm +0
|
|
As an example, the paragraph portions of this section
|
|
are numbered with \fIM=\fR\|3:
|
|
\&\fB.nm|1|3\fR was placed at the beginning;
|
|
\&\fB.nm\fR was placed at the end of the first paragraph;
|
|
and \fB.nm|+0\fR was placed in front of this paragraph;
|
|
and \fB.nm\fR finally placed at the end.
|
|
Line lengths were also changed (by \fB\ew\'0000\'u\fR) to keep the right side aligned.
|
|
Another example is
|
|
\&\fB.nm|+5|5|x|3\fR which turns on numbering with the line number of the next
|
|
line to be five greater than the last numbered line,
|
|
with \fIM=\fR\|5, with spacing \fIS\fR untouched, and with the indent \fII\fR set to 3.
|
|
.br
|
|
.ll
|
|
.nm
|
|
.mh
|
|
Conditional Acceptance of Input
|
|
.pg
|
|
In the following,
|
|
\fIc\fR is a one-character, built-in \fIcondition\fR name,
|
|
\fB!\fR signifies \fInot\fR,
|
|
\fIN\fR is a numerical expression,
|
|
\fIstring1\fR and \fIstring2\fR are strings delimited by any non-blank, non-numeric character \fInot\fR in the strings,
|
|
and
|
|
\fIanything\fR represents what is conditionally accepted.
|
|
.h1
|
|
.bt
|
|
\fB&if\fI|c|anything\fR - - If condition \fIc\fR true, accept \fIanything\fR as input;
|
|
in multi-line case use \fI\e{anything\|\e}\fR.
|
|
.bt
|
|
\fB&if|!\fIc|anything\fR - - If condition \fIc\fR false, accept \fIanything\fR.
|
|
.bt
|
|
\fB&if\fI|N|anything\fR - \fBu\fR If expression \fIN\fR > 0, accept \fIanything\fR.
|
|
.bt
|
|
\fB&if|!\fIN|anything\fR - \fBu\fR If expression \fIN\fR \(<= 0, accept \fIanything\fR.
|
|
.bt
|
|
\fB&if\fI|\|\'string1\|\'string2\|\'|anything\fR - If \fIstring1\fR identical to \fIstring2\fR,
|
|
accept \fIanything\fR.
|
|
.bt
|
|
\fB&if|!\fI\|\'string1\|\'string2\|\'|anything\fR - If \fIstring1\fR not identical to \fIstring2\fR,
|
|
accept \fIanything\fR.
|
|
.bt
|
|
\fB&ie\fI|c|anything\fR - \fBu\fR If portion of if-else; all above forms (like \fBif\fR).
|
|
.bt
|
|
\fB&el\fI|anything\fR - - Else portion of if-else.
|
|
.pg
|
|
The built-in condition names are:
|
|
.TS
|
|
center box;
|
|
c2|c
|
|
c2|c
|
|
c2|l.
|
|
Condition
|
|
Name True If
|
|
_
|
|
\fBo\fR Current page number is odd
|
|
\fBe\fR Current page number is even
|
|
\fBt\fR Formatter is \*(TR
|
|
\fBn\fR Formatter is \*(NR
|
|
.TE
|
|
If the condition \fIc\fR is \fItrue\fR, or if the number \fIN\fR is greater than zero,
|
|
or if the strings compare identically (including motions and character size and font),
|
|
\fIanything\fR is accepted as input.
|
|
If a \fB!\fR precedes the condition, number, or string comparison,
|
|
the sense of the acceptance is reversed.
|
|
.pg
|
|
Any spaces between the condition and the beginning of \fIanything\fR are skipped over.
|
|
The \fIanything\fR can be either a single input line (text, macro, or whatever)
|
|
or a number of input lines.
|
|
In the multi-line case,
|
|
the first line must begin with a left delimiter \fB\e{\fR and
|
|
the last line must end with a right delimiter \fB\e}\fR.
|
|
.pg
|
|
The request \fBie\fR (if-else) is identical to \fBif\fR
|
|
except that the acceptance state is remembered.
|
|
A subsequent and matching \fBel\fR (else) request then uses the reverse sense of that state.
|
|
\fBie\fR|-|\fBel\fR pairs may be nested.
|
|
.pg
|
|
Some examples are:
|
|
.x1
|
|
.ft B
|
|
.ne 1
|
|
&if e .tl \'\|Even Page %\'\'\'
|
|
.ft R
|
|
.x2
|
|
which outputs a title if the page number is even; and
|
|
.x1
|
|
.ft B
|
|
.ne 3.1
|
|
&ie \en%>1 \e{\e
|
|
\&\'sp 0.5i
|
|
&tl \'\|Page %\'\'\'
|
|
\&\'sp ~\|1.2i|\e}
|
|
&el .sp ~\|2.5i
|
|
.ft R
|
|
.x2
|
|
which treats page 1 differently from other pages.
|
|
.mh
|
|
Environment Switching.
|
|
.pg
|
|
A number of the parameters that
|
|
control the text processing are gathered together into an
|
|
\fIenvironment\fR, which can be switched by the user.
|
|
The environment parameters are those associated
|
|
with requests noting E in their \fINotes\fR column;
|
|
in addition, partially collected lines and words are in the environment.
|
|
Everything else is global; examples are page-oriented parameters,
|
|
diversion-oriented parameters, number registers, and macro and string definitions.
|
|
All environments are initialized with default parameter values.
|
|
.h1
|
|
.bt
|
|
\fB&ev\fI|N\fR \fIN\(eq\fR0 previous - Environment switched to
|
|
environment 0\(<=\fIN\fR\(<=2.
|
|
Switching is done in push-down fashion so that
|
|
restoring a previous environment \fImust\fR be done with \fB.ev\fR
|
|
rather than specific reference.
|
|
.mh
|
|
Insertions from the Standard Input
|
|
.pg
|
|
The input can be temporarily switched to the system \fIstandard input\fR
|
|
with \fBrd\fR,
|
|
which will switch back when \fItwo\fR newlines
|
|
in a row are found (the \fIextra\fR blank line is not used).
|
|
This mechanism is intended for insertions in form-letter-like documentation.
|
|
On \s-1UNIX\s+1, the \fIstandard input\fR can be the user's keyboard,
|
|
a \fIpipe\fR, or a \fIfile\fR.
|
|
.h1
|
|
.bt
|
|
\fB&rd\fI|prompt\fR - \fIprompt=\fR\s-1BEL\s+1 \
|
|
Read insertion from the standard input until two newlines in a row are found.
|
|
If the standard input is the user's keyboard, \fIprompt\fR (or a \s-1BEL\s+1)
|
|
is written onto the user's terminal.
|
|
\fBrd\fR behaves like a macro,
|
|
and arguments may be placed after \fIprompt\fR.
|
|
.bt
|
|
\fB&ex\fR - - - Exit from \*(NR\(sl\*(TR.
|
|
Text processing is terminated exactly as if all input had ended.
|
|
.pg
|
|
If insertions are to be
|
|
taken from the terminal keyboard \fIwhile\fR output is being printed
|
|
on the terminal, the command line option \fB\-q\fR will turn off the echoing
|
|
of keyboard input and prompt only with \s-1BEL\s+1.
|
|
The regular input and insertion input \fIcannot\fR
|
|
simultaneously come from the standard input.
|
|
.pg
|
|
As an example,
|
|
multiple copies of a form letter may be prepared by entering the insertions
|
|
for all the copies in one file to be used as the standard input,
|
|
and causing the file containing the letter to reinvoke itself using \fBnx\fR (\(sc19);
|
|
the process would ultimately be ended by an \fBex\fR in the insertion file.
|
|
.mh
|
|
Input\(slOutput File Switching
|
|
.pg
|
|
The (read-only) number register \fB.c\fR contains the input line number in
|
|
the current input file. The number register \fBc.\fR is a general register
|
|
serving the same purpose.
|
|
.h1
|
|
.bt
|
|
\fB&so\fI|filename\fR - - Switch source file.
|
|
The top input (file reading) level is switched to \fIfilename\fR.
|
|
The effect of an \fBso\fR encountered in a macro
|
|
occurs immediately.
|
|
When the new file ends,
|
|
input is again taken from the original file.
|
|
\fBso\fR's may be nested.
|
|
.bt
|
|
\fB&nx\fI|filename\fR end-of-file - Next file is \fIfilename\fR.
|
|
The current file is considered ended, and the input is immediately switched
|
|
to \fIfilename\fR.
|
|
.bt
|
|
\fB&pi\fI|program\fR - - Pipe output to \fIprogram\fR (\*(NR only).
|
|
This request must occur \fIbefore\fR any printing occurs.
|
|
No arguments are transmitted to \fIprogram\fR.
|
|
.mh
|
|
Miscellaneous
|
|
.pg
|
|
.h1
|
|
.bt
|
|
.mc \s12\(br\s0
|
|
\fB&mc\fI|c|N\fR - off E,\fBm\fR \
|
|
Specifies that a \fImargin\fR character \fIc\fR appear a distance
|
|
\fIN\fR to the right of the right margin
|
|
after each non-empty text line (except those produced by \fBtl\fR).
|
|
If the output line is too-long (as can happen in nofill mode)
|
|
the character will be appended to the line.
|
|
If \fIN\fR is not given, the previous \fIN\fR is used; the initial \fIN\fR is
|
|
0.2|inches in \*(NR and 1\|em in \*(TR.
|
|
The margin character used with this paragraph was a 12-point box-rule.
|
|
.br
|
|
.mc
|
|
.bt
|
|
\fB&tm\fI|string\fR - newline - \
|
|
After skipping initial blanks, \fIstring\fR (rest of the line) is read in \fIcopy mode\fR
|
|
and written on the user's terminal. (see \(sc21).
|
|
.bt
|
|
\fB&ig\fI|yy\fR - \fI.yy=\fB..\fR - Ignore \
|
|
input lines.
|
|
\fBig\fR behaves exactly like \fBde\fR (\(sc7) except that the
|
|
input is discarded.
|
|
The input is read in \fIcopy mode\fR, and any auto-incremented
|
|
registers will be affected.
|
|
.bt
|
|
\fB&pm\fI|t\fR - all - \
|
|
Print macros.
|
|
The names and sizes of all of the defined macros and strings are printed
|
|
on the user's terminal;
|
|
if \fIt\fR is given, only the total of the sizes is printed.
|
|
The sizes is given in \fIblocks\fR
|
|
of 128 characters.
|
|
.bt
|
|
\fB&ab\fI|string\fR - - - \
|
|
Print \fIstring\fR on standard error and terminate immediately. The
|
|
default \fIstring\fR is "User Abort". Does not cause a break. Only output
|
|
preceding the last break is written.
|
|
.bt
|
|
.lg 0
|
|
\fB&fl\fR - - B \c
|
|
.lg
|
|
Flush output buffer.
|
|
Used in interactive debugging to force output.
|
|
.mh
|
|
Output and Error Messages.
|
|
.pg
|
|
The output from \fBtm\fR, \fBpm\fR, \fBab\fR and the prompt from \fBrd\fR,
|
|
as well as various \fIerror\fR messages are written onto
|
|
\s-1UNIX\s+1's \fIstandard error\fR output.
|
|
The latter is different from the \fIstandard output\fR,
|
|
where \*(NR formatted output goes.
|
|
By default, both are written onto the user's terminal,
|
|
but they can be independently redirected.
|
|
.pg
|
|
Various \fIerror\fR conditions may occur during
|
|
the operation of \*(NR and \*(TR.
|
|
Certain less serious errors having only local impact do not
|
|
cause processing to terminate.
|
|
Two examples are \fIword overflow\fR, caused by a word that is too large
|
|
to fit into the word buffer (in fill mode), and
|
|
\fIline overflow\fR, caused by an output line that grew too large
|
|
to fit in the line buffer;
|
|
in both cases, a message is printed, the offending excess
|
|
is discarded,
|
|
and the affected word or line is marked at the point of truncation
|
|
with a \(** in \*(NR and a \(lh in \*(TR.
|
|
The philosophy is to continue processing, if possible,
|
|
on the grounds that output useful for debugging may be produced.
|
|
If a serious error occurs, processing terminates,
|
|
and an appropriate message is printed.
|
|
Examples are the inability to create, read, or write files,
|
|
and the exceeding of certain internal limits that
|
|
make future output unlikely to be useful.
|
|
.ps 10
|
|
.vs 12
|
|
.ft R
|
|
.bp
|