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