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