This module is believed to contain source code proprietary to AT&T.
Use and redistribution is subject to the Berkeley Software License
Agreement and your Software Agreement with AT&T (Western Electric).

@(#)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 hy, several variants may be set. A hyphenation indicator 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 (\e(em), or hyphenation indicator characters\ \(emsuch as mother-in-law\(em\ are always subject to splitting after those characters, whether or not automatic hyphenation is on or off. .h1 .bt &nh hyphenate - E \ Automatic hyphenation is turned off. .bt &hyN on,N=1 on,N=1 E \ Automatic hyphenation is turned on for N\|\(>=1, or off for N=\|0. If N=\|2, last lines (ones that will cause a trap) are not hyphenated. For N=\|4 and 8, the last and first two characters respectively of a word are not split off. These values are additive; i.|e. N=\|14 will invoke all three restrictions. .bt &hc|c \e% \e% E Hyphenation indicator character is set to c or to the default \e%. The indicator does not appear in the output. .bt &hw|word1|... ignored - Specify hyphenation points in words with imbedded minus signs. Versions of a word with terminal s are implied; i.|e. dig-it implies dig-its. This list is examined initially and after each suffix stripping. The space available is small\(emabout 128 characters. .mh Three Part Titles. .pg The titling function tl provides for automatic placement of three fields at the left, center, and right of a line with a title-length specifiable with lt. tl may be used anywhere, and is independent of the normal text collecting process. A common use is in header and footer macros. .h1 .bt &tl|\'left\|\'center\|\'right\|\' - - \ The strings left, center, and right 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 %) is found within any of the fields it is replaced by the current page number having the format assigned to register %. Any character may be used as the string delimiter. .bt &pc|c % off - The page number character is set to c, or removed. The page-number register remains %. .bt &lt|\(+-N 6.5\|in previous E,m Length of title set to \(+-N. The line-length and the title-length are independent. Indents do not apply to titles; page-offsets do. .mh Output Line Numbering. .pg .nm 1 3 Automatic sequence numbering of output lines may be requested with nm. 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 tl are not numbered. Numbering can be temporarily suspended with nn, or with an .nm followed by a later .nm|+0. In addition, a line number indent I, and the number-text separation S may be specified in digit-spaces. Further, it can be specified that only those line numbers that are multiples of some number M are to be printed (the others will appear as blank number fields).

.nm .h1 .bt &nm|\(+-N|M|S|I off E \ Line number mode. If \(+-N is given, line numbering is turned on, and the next output line numbered is numbered \(+-N. Default values are M=\|1, S=\|1, and I=\|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 ln. .bt &nn|N - N=1 E The next N text output lines are not numbered. .pg .nm +0 As an example, the paragraph portions of this section are numbered with M=\|3: \fB.nm|1|3 was placed at the beginning; \fB.nm was placed at the end of the first paragraph; and .nm|+0 was placed in front of this paragraph; and .nm finally placed at the end. Line lengths were also changed (by \ew\'0000\'u) to keep the right side aligned. Another example is \fB.nm|+5|5|x|3 which turns on numbering with the line number of the next line to be five greater than the last numbered line, with M=\|5, with spacing S untouched, and with the indent I set to 3.

.nm .mh Conditional Acceptance of Input .pg In the following, c is a one-character, built-in condition name, ! signifies not, N is a numerical expression, string1 and string2 are strings delimited by any non-blank, non-numeric character not in the strings, and anything represents what is conditionally accepted. .h1 .bt &if|c|anything - - If condition c true, accept anything as input; in multi-line case use \e{anything\|\e}. .bt &if|!c|anything - - If condition c false, accept anything. .bt &if|N|anything - u If expression N > 0, accept anything. .bt &if|!N|anything - u If expression N \(<= 0, accept anything. .bt &if|\|\'string1\|\'string2\|\'|anything - If string1 identical to string2, accept anything. .bt &if|!\|\'string1\|\'string2\|\'|anything - If string1 not identical to string2, accept anything. .bt &ie|c|anything - u If portion of if-else; all above forms (like if). .bt &el|anything - - Else portion of if-else. .pg The built-in condition names are:

Condition

Name True If

o Current page number is odd

e Current page number is even

t Formatter is \*(TR

n Formatter is \*(NR

If the condition c is true, or if the number N is greater than zero, or if the strings compare identically (including motions and character size and font), anything is accepted as input. If a ! precedes the condition, number, or string comparison, the sense of the acceptance is reversed. .pg Any spaces between the condition and the beginning of anything are skipped over. The anything 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 \e{ and the last line must end with a right delimiter \e}. .pg The request ie (if-else) is identical to if except that the acceptance state is remembered. A subsequent and matching el (else) request then uses the reverse sense of that state. ie|-|el pairs may be nested. .pg Some examples are: .x1 &if e .tl \'\|Even Page %\'\'\' .x2 which outputs a title if the page number is even; and .x1 &ie \en%>1 \e{\e \'sp 0.5i &tl \'\|Page %\'\'\' \'sp ~\|1.2i|\e} &el .sp ~\|2.5i .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 environment, which can be switched by the user. The environment parameters are those associated with requests noting E in their Notes 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 &ev|N N\(eq0 previous - Environment switched to environment 0\(<=N\(<=2. Switching is done in push-down fashion so that restoring a previous environment must be done with .ev rather than specific reference. .mh Insertions from the Standard Input .pg The input can be temporarily switched to the system standard input with rd, which will switch back when two newlines in a row are found (the extra blank line is not used). This mechanism is intended for insertions in form-letter-like documentation. On \s-1UNIX\s+1, the standard input can be the user's keyboard, a pipe, or a file. .h1 .bt &rd|prompt - prompt=\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, prompt (or a \s-1BEL\s+1) is written onto the user's terminal. rd behaves like a macro, and arguments may be placed after prompt. .bt &ex - - - 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 while output is being printed on the terminal, the command line option -q will turn off the echoing of keyboard input and prompt only with \s-1BEL\s+1. The regular input and insertion input cannot 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 nx (\(sc19); the process would ultimately be ended by an ex in the insertion file. .mh Input\(slOutput File Switching .pg The (read-only) number register .c contains the input line number in the current input file. The number register c. is a general register serving the same purpose. .h1 .bt &so|filename - - Switch source file. The top input (file reading) level is switched to filename. The effect of an so encountered in a macro occurs immediately. When the new file ends, input is again taken from the original file. so's may be nested. .bt &nx|filename end-of-file - Next file is filename. The current file is considered ended, and the input is immediately switched to filename. .bt &pi|program - - Pipe output to program (\*(NR only). This request must occur before any printing occurs. No arguments are transmitted to program. .mh Miscellaneous .pg .h1 .bt .mc \s12\(br\s0 &mc|c|N - off E,m \ Specifies that a margin character c appear a distance N to the right of the right margin after each non-empty text line (except those produced by tl). If the output line is too-long (as can happen in nofill mode) the character will be appended to the line. If N is not given, the previous N is used; the initial N is 0.2|inches in \*(NR and 1\|em in \*(TR. The margin character used with this paragraph was a 12-point box-rule.

.mc .bt &tm|string - newline - \ After skipping initial blanks, string (rest of the line) is read in copy mode and written on the user's terminal. (see \(sc21). .bt &ig|yy - .yy=.. - Ignore \ input lines. ig behaves exactly like de (\(sc7) except that the input is discarded. The input is read in copy mode, and any auto-incremented registers will be affected. .bt &pm|t - all - \ Print macros. The names and sizes of all of the defined macros and strings are printed on the user's terminal; if t is given, only the total of the sizes is printed. The sizes is given in blocks of 128 characters. .bt &ab|string - - - \ Print string on standard error and terminate immediately. The default string is "User Abort". Does not cause a break. Only output preceding the last break is written. .bt .lg 0 &fl - - B \c .lg Flush output buffer. Used in interactive debugging to force output. .mh Output and Error Messages. .pg The output from tm, pm, ab and the prompt from rd, as well as various error messages are written onto \s-1UNIX\s+1's standard error output. The latter is different from the standard output, where \*(NR formatted output goes. By default, both are written onto the user's terminal, but they can be independently redirected. .pg Various error 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 word overflow, caused by a word that is too large to fit into the word buffer (in fill mode), and line overflow, 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. .vs 12 .bp