/share/doc/usd/21.troff/m4

  1.\" Copyright (C) Caldera International Inc. 2001-2002.  All rights reserved.
  2.\" 
  3.\" Redistribution and use in source and binary forms, with or without
  4.\" modification, are permitted provided that the following conditions are
  5.\" met:
  6.\" 
  7.\" Redistributions of source code and documentation must retain the above
  8.\" copyright notice, this list of conditions and the following
  9.\" disclaimer.
 10.\" 
 11.\" Redistributions in binary form must reproduce the above copyright
 12.\" notice, this list of conditions and the following disclaimer in the
 13.\" documentation and/or other materials provided with the distribution.
 14.\" 
 15.\" All advertising materials mentioning features or use of this software
 16.\" must display the following acknowledgement:
 17.\" 
 18.\" This product includes software developed or owned by Caldera
 19.\" International, Inc.  Neither the name of Caldera International, Inc.
 20.\" nor the names of other contributors may be used to endorse or promote
 21.\" products derived from this software without specific prior written
 22.\" permission.
 23.\" 
 24.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
 25.\" INTERNATIONAL, INC.  AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
 26.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 27.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 28.\" DISCLAIMED.  IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
 29.\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 32.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 33.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 34.\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 35.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 36.\"
 37.\"	@(#)m4	8.1 (Berkeley) 8/14/93
 38.\"
 39.\" $FreeBSD$
 40.tr |
 41.mh
 42Hyphenation.
 43.pg
 44The automatic hyphenation may be switched off and on.
 45When switched on with \fBhy\fR,
 46several variants may be set.
 47A \fIhyphenation indicator\fR character may be imbedded in a word to
 48specify desired hyphenation points,
 49or may be prepended to suppress hyphenation.
 50In addition,
 51the user may specify a small exception word list.
 52.pg
 53Only words that consist of a central alphabetic string
 54surrounded by (usually null) non-alphabetic strings
 55are considered candidates for automatic hyphenation.
 56Words that were input containing hyphens
 57(minus),
 58em-dashes (\fB\e(em\fR),
 59or hyphenation indicator characters\
 60\(emsuch as mother-in-law\(em\
 61are \fIalways\fR subject to splitting after those characters,
 62whether or not automatic hyphenation is on or off.
 63.h1
 64.bt
 65\fB&nh\fR	hyphenate	-	E	\
 66Automatic hyphenation is turned off.
 67.bt
 68\fB&hy\fIN\fR	on,\fIN=\fR1	on,\fIN=\fR1	E	\
 69Automatic hyphenation is turned on
 70for \fIN\fR\|\(>=1, or off for \fIN=\fR\|0.
 71If \fIN=\fR\|2, \fIlast\fR lines (ones that will cause a trap)
 72are not hyphenated.
 73For \fIN=\fR\|4 and 8, the last and first two characters
 74respectively of a word are not split off.
 75These values are additive;
 76i.|e. \fIN=\fR\|14 will invoke all three restrictions.
 77.bt
 78\fB&hc\fI|c\fR	\fB\e%	\e%\fR	E	Hyphenation indicator character is set
 79to \fIc\fR or to the default \fB\e%\fR.
 80The indicator does not appear in the output.
 81.bt
 82\fB&hw\fI|word1|...\fR		ignored	-	Specify hyphenation points in words
 83with imbedded minus signs.
 84Versions of a word with terminal \fIs\fR are implied;
 85i.|e. \fIdig\-it\fR implies \fIdig\-its\fR.
 86This list is examined initially \fIand\fR after
 87each suffix stripping.
 88The space available is small\(emabout 128 characters.
 89.mh
 90Three Part Titles.
 91.pg
 92The titling function \fBtl\fR provides for automatic placement
 93of three fields at the left, center, and right of a line
 94with a title-length
 95specifiable with \fBlt\fR.
 96\fBtl\fR may be used anywhere, and is independent of the
 97normal text collecting process.
 98A common use is in header and footer macros.
 99.h1
100.bt
101\fB&tl\fI|\'left\|\'center\|\'right\|\'\fR	-	-	\
102The strings \fIleft\fR, \fIcenter\fR, and \fIright\fR are
103respectively left-adjusted, centered, and right-adjusted
104in the current title-length.
105Any of the strings may be empty,
106and overlapping is permitted.
107If the page-number character (initially \fB%\fR) is found within any of the fields it is replaced
108by the current page number having the format assigned to register \fB%\fR.
109Any character may be used as the string delimiter.
110.bt
111\fB&pc\fI|c\fR	\fB%\fR	off	-	The page number character is set to \fIc\fR,
112or removed.
113The page-number register remains \fB%\fR.
114.bt
115\fB&lt\fI|\(+-N\fR	6.5\|in	previous	E,\fBm\fR	Length of title set to \fI\(+-N\fR.
116The line-length and the title-length are \fIindependent\fR.
117Indents do not apply to titles; page-offsets do.
118.mh
119Output Line Numbering.
120.pg
121.ll -\w'0000'u
122.nm 1 3
123Automatic sequence numbering of output lines may be
124requested with \fBnm\fR.
125When in effect,
126a three-digit, arabic number plus a digit-space
127is prepended to output text lines.
128The text lines are thus offset by four digit-spaces,
129and otherwise retain their line length;
130a reduction in line length may be desired to keep the right margin
131aligned with an earlier margin.
132Blank lines, other vertical spaces, and lines generated by \fBtl\fR
133are \fInot\fR numbered.
134Numbering can be temporarily suspended with \fBnn\fR,
135or with an \fB.nm\fR followed by a later \fB.nm|+0\fR.
136In addition,
137a line number indent \fII\fR, and the number-text separation \fIS\fR
138may be specified in digit-spaces.
139Further, it can be specified that only those line numbers that are
140multiples of some number \fIM\fR are to be printed (the others will appear
141as blank number fields).
142.br
143.nm
144.ll
145.h1
146.bt
147\fB&nm\fI|\(+-N|M|S|I\fR		off	E	\
148Line number mode.
149If \fI\(+-N\fR is given,
150line numbering is turned on,
151and the next output line numbered is numbered \fI\(+-N\fR.
152Default values are \fIM=\fR\|1, \fIS=\fR\|1, and \fII=\fR\|0.
153Parameters corresponding to missing arguments are unaffected;
154a non-numeric argument is considered missing.
155In the absence of all arguments, numbering is turned off;
156the next line number is preserved for possible further use
157in number register \fBln\fR.
158.bt
159\fB&nn\fI|N\fR	-	\fIN=\fR1	E	The next \fIN\fR text output lines are not
160numbered.
161.pg
162.ll -\w'0000'u
163.nm +0
164As an example, the paragraph portions of this section
165are numbered with \fIM=\fR\|3:
166\&\fB.nm|1|3\fR was placed at the beginning;
167\&\fB.nm\fR was placed at the end of the first paragraph;
168and \fB.nm|+0\fR was placed in front of this paragraph;
169and \fB.nm\fR finally placed at the end.
170Line lengths were also changed (by \fB\ew\'0000\'u\fR) to keep the right side aligned.
171Another example is
172\&\fB.nm|+5|5|x|3\fR which turns on numbering with the line number of the next
173line to be five greater than the last numbered line,
174with \fIM=\fR\|5, with spacing \fIS\fR untouched, and with the indent \fII\fR set to 3.
175.br
176.ll
177.nm
178.mh
179Conditional Acceptance of Input
180.pg
181In the following,
182\fIc\fR is a one-character, built-in \fIcondition\fR name,
183\fB!\fR signifies \fInot\fR,
184\fIN\fR is a numerical expression,
185\fIstring1\fR and \fIstring2\fR are strings delimited by any non-blank, non-numeric character \fInot\fR in the strings,
186and
187\fIanything\fR represents what is conditionally accepted.
188.h1
189.bt
190\fB&if\fI|c|anything\fR		-	-	If condition \fIc\fR true, accept \fIanything\fR as input;
191in multi-line case use \fI\e{anything\|\e}\fR.
192.bt
193\fB&if|!\fIc|anything\fR		-	-	If condition \fIc\fR false, accept \fIanything\fR.
194.bt
195\fB&if\fI|N|anything\fR		-	\fBu\fR	If expression \fIN\fR > 0, accept \fIanything\fR.
196.bt
197\fB&if|!\fIN|anything\fR	-	\fBu\fR	If expression \fIN\fR \(<= 0, accept \fIanything\fR.
198.bt
199\fB&if\fI|\|\'string1\|\'string2\|\'|anything\fR	-	If \fIstring1\fR identical to \fIstring2\fR,
200accept \fIanything\fR.
201.bt
202\fB&if|!\fI\|\'string1\|\'string2\|\'|anything\fR	-	If \fIstring1\fR not identical to \fIstring2\fR,
203accept \fIanything\fR.
204.bt
205\fB&ie\fI|c|anything\fR		-	\fBu\fR	If portion of if-else; all above forms (like \fBif\fR).
206.bt
207\fB&el\fI|anything\fR		-	-	Else portion of if-else.
208.pg
209The built-in condition names are:
210.TS
211center box;
212c2|c
213c2|c
214c2|l.
215Condition
216Name	True If
217_
218\fBo\fR	Current page number is odd
219\fBe\fR	Current page number is even
220\fBt\fR	Formatter is \*(TR
221\fBn\fR	Formatter is \*(NR
222.TE
223If the condition \fIc\fR is \fItrue\fR, or if the number \fIN\fR is greater than zero,
224or if the strings compare identically (including motions and character size and font),
225\fIanything\fR is accepted as input.
226If a \fB!\fR precedes the condition, number, or string comparison,
227the sense of the acceptance is reversed.
228.pg
229Any spaces between the condition and the beginning of \fIanything\fR are skipped over.
230The \fIanything\fR can be either a single input line (text, macro, or whatever)
231or a number of input lines.
232In the multi-line case,
233the first line must begin with a left delimiter \fB\e{\fR and
234the last line must end with a right delimiter \fB\e}\fR.
235.pg
236The request \fBie\fR (if-else) is identical to \fBif\fR
237except that the acceptance state is remembered.
238A subsequent and matching \fBel\fR (else) request then uses the reverse sense of that state.
239\fBie\fR|-|\fBel\fR pairs may be nested.
240.pg
241Some examples are:
242.x1
243.ft B
244.ne 1
245&if e .tl \'\|Even Page %\'\'\'
246.ft R
247.x2
248which outputs a title if the page number is even; and
249.x1
250.ft B
251.ne 3.1
252&ie \en%>1 \e{\e
253\&\'sp 0.5i
254&tl \'\|Page %\'\'\'
255\&\'sp ~\|1.2i|\e}
256&el .sp ~\|2.5i
257.ft R
258.x2
259which treats page 1 differently from other pages.
260.mh
261Environment Switching.
262.pg
263A number of the parameters that
264control the text processing are gathered together into an
265\fIenvironment\fR, which can be switched by the user.
266The environment parameters are those associated
267with requests noting E in their \fINotes\fR column;
268in addition, partially collected lines and words are in the environment.
269Everything else is global; examples are page-oriented parameters,
270diversion-oriented parameters, number registers, and macro and string definitions.
271All environments are initialized with default parameter values.
272.h1
273.bt
274\fB&ev\fI|N\fR	\fIN\(eq\fR0	previous	-	Environment switched to
275environment 0\(<=\fIN\fR\(<=2.
276Switching is done in push-down fashion so that
277restoring a previous environment \fImust\fR be done with \fB.ev\fR
278rather than specific reference.
279.mh
280Insertions from the Standard Input
281.pg
282The input can be temporarily switched to the system \fIstandard input\fR
283with \fBrd\fR,
284which will switch back when \fItwo\fR newlines
285in a row are found (the \fIextra\fR blank line is not used).
286This mechanism is intended for insertions in form-letter-like documentation.
287On \s-1UNIX\s+1, the \fIstandard input\fR can be the user's keyboard,
288a \fIpipe\fR, or a \fIfile\fR.
289.h1
290.bt
291\fB&rd\fI|prompt\fR	-	\fIprompt=\fR\s-1BEL\s+1		\
292Read insertion from the standard input until two newlines in a row are found.
293If the standard input is the user's keyboard, \fIprompt\fR (or a \s-1BEL\s+1)
294is written onto the user's terminal.
295\fBrd\fR behaves like a macro,
296and arguments may be placed after \fIprompt\fR.
297.bt
298\fB&ex\fR	-	-	-	Exit from \*(NR\(sl\*(TR.
299Text processing is terminated exactly as if all input had ended.
300.pg
301If insertions are to be
302taken from the terminal keyboard \fIwhile\fR output is being printed
303on the terminal, the command line option \fB\-q\fR will turn off the echoing
304of keyboard input and prompt only with \s-1BEL\s+1.
305The regular input and insertion input \fIcannot\fR
306simultaneously come from the standard input.
307.pg
308As an example,
309multiple copies of a form letter may be prepared by entering the insertions
310for all the copies in one file to be used as the standard input,
311and causing the file containing the letter to reinvoke itself using \fBnx\fR (\(sc19);
312the process would ultimately be ended by an \fBex\fR in the insertion file.
313.mh
314Input\(slOutput File Switching
315.pg
316The (read-only) number register \fB.c\fR contains the input line number in
317the current input file.  The number register \fBc.\fR is a general register
318serving the same purpose.
319.h1
320.bt
321\fB&so\fI|filename\fR		-	-	Switch source file.
322The top input (file reading) level is switched to \fIfilename\fR.
323The effect of an \fBso\fR encountered in a macro
324occurs immediately.
325When the new file ends,
326input is again taken from the original file.
327\fBso\fR's may be nested.
328.bt
329\fB&nx\fI|filename\fR		end-of-file	-	Next file is \fIfilename\fR.
330The current file is considered ended, and the input is immediately switched
331to \fIfilename\fR.
332.bt
333\fB&pi\fI|program\fR		-	-	Pipe output to \fIprogram\fR (\*(NR only).
334This request must occur \fIbefore\fR any printing occurs.
335No arguments are transmitted to \fIprogram\fR.
336.mh
337Miscellaneous
338.pg
339.h1
340.bt
341.mc \s12\(br\s0
342\fB&mc\fI|c|N\fR	-	off	E,\fBm\fR	\
343Specifies that a \fImargin\fR character \fIc\fR appear a distance
344\fIN\fR to the right of the right margin
345after each non-empty text line (except those produced by \fBtl\fR).
346If the output line is too-long (as can happen in nofill mode)
347the character will be appended to the line.
348If \fIN\fR is not given, the previous \fIN\fR is used; the initial \fIN\fR is
3490.2|inches in \*(NR and 1\|em in \*(TR.
350The margin character used with this paragraph was a 12-point box-rule.
351.br
352.mc
353.bt
354\fB&tm\fI|string\fR	-	newline	-	\
355After skipping initial blanks, \fIstring\fR (rest of the line) is read in \fIcopy mode\fR
356and written on the user's terminal. (see \(sc21).
357.bt
358\fB&ig\fI|yy\fR	-	\fI.yy=\fB..\fR	-	Ignore \
359input lines.
360\fBig\fR behaves exactly like \fBde\fR (\(sc7) except that the
361input is discarded.
362The input is read in \fIcopy mode\fR, and any auto-incremented
363registers will be affected.
364.bt
365\fB&pm\fI|t\fR	-	all	-	\
366Print macros.
367The names and sizes of all of the defined macros and strings are printed
368on the user's terminal;
369if \fIt\fR is given, only the total of the sizes is printed.
370The sizes is given in \fIblocks\fR
371of 128 characters.
372.bt
373\fB&ab\fI|string\fR	-	-	-	\
374Print \fIstring\fR on standard error and terminate immediately.  The
375default \fIstring\fR is "User Abort". Does not cause a break.  Only output
376preceding the last break is written.
377.bt
378.lg 0
379\fB&fl\fR	-	-	B	\c
380.lg
381Flush output buffer.
382Used in interactive debugging to force output.
383.mh
384Output and Error Messages.
385.pg
386The output from \fBtm\fR, \fBpm\fR, \fBab\fR and the prompt from \fBrd\fR,
387as well as various \fIerror\fR messages are written onto
388\s-1UNIX\s+1's \fIstandard error\fR output.
389The latter is different from the \fIstandard output\fR,
390where \*(NR formatted output goes.
391By default, both are written onto the user's terminal,
392but they can be independently redirected.
393.pg
394Various \fIerror\fR conditions may occur during
395the operation of \*(NR and \*(TR.
396Certain less serious errors having only local impact do not
397cause processing to terminate.
398Two examples are \fIword overflow\fR, caused by a word that is too large
399to fit into the word buffer (in fill mode), and
400\fIline overflow\fR, caused by an output line that grew too large
401to fit in the line buffer;
402in both cases, a message is printed, the offending excess
403is discarded,
404and the affected word or line is marked at the point of truncation
405with a \(** in \*(NR and a \(lh in \*(TR.
406The philosophy is to continue processing, if possible,
407on the grounds that output useful for debugging may be produced.
408If a serious error occurs, processing terminates,
409and an appropriate message is printed.
410Examples are the inability to create, read, or write files,
411and the exceeding of certain internal limits that
412make future output unlikely to be useful.
413.ps 10
414.vs 12
415.ft R
416.bp