![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to cstr.54 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / vol2 / troff|
Return to cstr.54 CVS log | Up to [Research Unix] / researchv10dc / vol2 / troff |
1.1 root 1: .TR 54
2: .ND "Revised November, 1992
3: .ds NR "\f2nroff\fP
4: .ds TR "\f2troff\fP
5: .ds Tr \f2Troff\fP
6: .ds Nr \f2Nroff\fP
7: .
8: .de BI
9: .nr PQ \\n(.f
10: .if \\n(.$=0 .ft 4
11: .if \\n(.$>0 \%\&\\$3\f4\\$1\\f\\n(PQ\\$2
12: ..
13: .am NH
14: .nr p \\np+1
15: .nr s 0 1
16: ..
17: .de sc
18: .LP
19: \f4\\np.\\n+s.\ \ \\$1\f1\0
20: ..
21: .de bt
22: .SP .25
23: .LP
24: .NE 2.1
25: .ta 1i 2i 3i 4i
26: \\$1 \\$2 \\$3 \\$4
27: .IP "" 0.8i
28: ....br
29: \\$5
30: ..
31: .
32: .
33: .
34: .
35: .EQ
36: delim @@
37: define cw % "\&" font CW %
38: .EN
39: .
40: .
41: .TL
42: Troff User's Manual\(dg
43: .AU
44: Joseph F. Ossanna
45: .br
46: Brian W. Kernighan
47: .AI
48: .MH
49: .SH
50: Introduction
51: .PP
52: \*(Tr and \*(NR are text processors
53: that format text for typesetter- and
54: typewriter-like terminals, respectively.
55: They accept lines of text interspersed with lines of
56: format control information and
57: format the text into a printable, paginated document
58: having a user-designed style.
59: \*(Tr and \*(NR offer
60: unusual freedom in document styling:
61: arbitrary style headers and footers;
62: arbitrary style footnotes;
63: multiple automatic sequence numbering for paragraphs, sections, etc;
64: multiple column output;
65: dynamic font and point-size control;
66: arbitrary horizontal and vertical local motions at any point;
67: and
68: a family of automatic overstriking, bracket construction, and
69: line-drawing functions.
70: .
71: .de TL
72: .LP
73: .ce
74: .ps +2
75: .ft B
76: ..
77: .
78: .FS
79: \(dgThis is a version of the original \*(TR reference manual,
80: revised several times by B. W. Kernighan.
81: .FE
82: .PP
83: .I Troff
84: produces its output in a device-independent form,
85: although parameterized for a specific device;
86: \*(TR output must be processed by a driver for that
87: device to produce printed output.
88: .PP
89: \*(Tr and \*(NR are highly compatible with each other and it is almost always
90: possible to prepare input acceptable to both.
91: Conditional input is provided that enables
92: the user to embed input expressly destined for either program.
93: \*(Nr can prepare output directly for a variety of terminal types and
94: is capable of utilizing the full resolution of each terminal.
95: A warning, however:
96: \*(NR
97: necessarily cannot support all features of
98: \*(TR.
99: Within that limitation, it is the same as \*(TR,
100: and in fact there is only a single program,
101: invoked by two different names.
102: .SH
103: Background to the Second Edition
104: .PP
105: \*(Tr
106: was originally written by the late Joe Ossanna
107: in about 1973, in assembly language for the
108: \s-1PDP\s0-11,
109: to drive the Graphic Systems CAT typesetter.
110: It was rewritten in C around 1975,
111: and underwent slow but steady evolution until
112: Ossanna's death late in 1977.
113: .PP
114: In 1979, Brian Kernighan
115: modified
116: \*(TR
117: so that it would produce output for a variety of typesetters,
118: while retaining its input specifications.
119: Over the decade from 1979 to 1989,
120: the internals
121: have been modestly revised,
122: though much of the code remains as it was when Ossanna wrote it.
123: .PP
124: \*(Tr
125: reads parameter files
126: each time it is invoked, to
127: set values for machine resolution,
128: legal type sizes and fonts, and character names,
129: character widths
130: and the like.
131: \*(Tr
132: output is
133: \s-1ASCII\s0
134: characters
135: in a simple language
136: that describes where each character is to be placed
137: and in what size and font.
138: A post-processor must be written for each device
139: to convert this typesetter-independent language
140: into specific instructions for that device.
141: .PP
142: The output language contains information that was not readily
143: identifiable in the older output.
144: Most notably, the beginning of each page and line
145: is marked,
146: so post-processors can do device-specific optimizations
147: such as sorting the data vertically or printing it boustrophedonically,
148: independent of
149: \*(TR.
150: .PP
151: Capabilities for graphics have been added.
152: \*(TR
153: now recognizes commands for drawing diagonal lines,
154: circles, ellipses, circular arcs,
155: and quadratic B-splines;
156: there are also ways to pass arbitrary information to the output
157: unprocessed by
158: \*(TR.
159: .PP
160: A number of limitations have been eased or eliminated.
161: A document may have an arbitrary number of fonts on any page
162: (if the output device permits it, of course).
163: Fonts may be accessed merely by naming them;
164: ``mounting'' is no longer necessary.
165: There are no limits on the number of characters.
166: \H'8'Character height\H'10' and \S'-1'sl\S'0'a\S'1'nt\S'0' may be set
167: independently of width.
168: .PP
169: The remainder of this document contains a description of
170: usage and command-line options;
171: a summary of requests, escape sequences, and pre-defined number registers;
172: a reference manual;
173: tutorial examples;
174: and a list of commonly-available characters.
175: .SH
176: Acknowledgements
177: .PP
178: Joe Ossanna's
179: \*(TR
180: remains a remarkable accomplishment.
181: For fifteen years, it has proven a robust tool,
182: taking unbelievable abuse from a variety of preprocessors
183: and being forced into uses that were never conceived of
184: in the original design,
185: all with considerable grace under fire.
186: .PP
187: The current version of \*(TR has profited from
188: significant code improvements by
189: Jaap Akkerhuis, Dennis Ritchie, Ken Thompson, and Molly Wagner.
190: Andrew Hume, Doug McIlroy, and Ravi Sethi made valuable suggestions on the manual.
191: I fear that the remaining bugs are my fault.
192: .sp 100
193: .BP
194: .TL
195: Usage
196: .SP
197: .PP
198: \*(Tr or \*(NR is invoked as
199: .P1
200: troff \fIoptions files\fP
201: nroff \fIoptions files\fP
202: .P2
203: where @options@ represents any of a number of option arguments
204: and @files@ represents the list of files containing the document
205: to be formatted.
206: An argument consisting of a single minus
207: .CW - ' `
208: is taken to be
209: a filename corresponding to the standard input.
210: If no filenames are given input is taken from the standard input.
211: The options, which may appear in any order so long as they appear
212: before the files, are:
213: .TS
214: center;
215: lfCW lw(4.5i).
216: -N T{
217: Run as \*(NR; default is \*(TR.
218: T}
219: -m@name@ T{
220: Read the macro file
221: @cw /usr/lib/tmac. name@
222: before the input @files@.
223: T}
224: -T@name@ T{
225: Specifies
226: the type of the output device.
227: Specific devices are site-dependent.
228: For
229: \*(TR,
230: useful names include
231: .CW post
232: (Postscript, the default),
233: .CW 202
234: (Linotron 202), and
235: .CW aps
236: (Autologic APS-5).
237: For
238: \*(NR ,
239: useful names include
240: @cw "37"@ for the (default) Model 37 Teletype\(rg,
241: @cw "450"@ for the \s-1DASI\s+1-450 (Diablo Hyterm),
242: @cw lp@ for ``dumb'' line printer terminals (no half-line motions,
243: no reverse motions,
244: and @cw think@ for the HP ThinkJet printer.
245: T}
246: -i T{
247: Read standard input after the input files are exhausted.
248: T}
249: -o@list@ T{
250: Print only pages whose page numbers appear in @list@,
251: which consists of comma-separated numbers and number ranges.
252: A number range has the form @N-M@
253: and means pages @N@ through @M@;
254: a initial @-N@ means
255: from the beginning to page @N@; and a final @N-@ means
256: from @N@ to the end.
257: T}
258: -n@N@ T{
259: Number first generated page @N@.
260: T}
261: -r@aN@ T{
262: Set number register @a@ (one-character) to @N@.
263: T}
264: -s@N@ T{
265: Stop every @N@ pages.
266: \*(Nr will halt prior to every @N@ pages (default @N=1@)
267: to allow paper loading or
268: changing, and will resume upon receipt of a newline.
269: \*(Tr will include a ``pause'' code every @N@ pages;
270: its meaning, if any, depends on the output device.
271: T}
272: -u@N@ T{
273: Set amount of emboldening for the
274: .CW bd
275: request to @N@.
276: T}
277: -F@path@ T{
278: Look in directory @path@ for font information;
279: default is
280: .CW /usr/lib/font
281: for \*(TR
282: and
283: .CW /usr/lib/term
284: for \*(NR.
285: T}
286: .sp .5
287: T{
288: \*(TR Only
289: T}
290: -a T{
291: Send a printable \s-1(ASCII)\s+1 approximation
292: of the results to the standard output.
293: T}
294: .sp .5
295: T{
296: \*(NR Only
297: T}
298: -e T{
299: Produce equally-spaced words in adjusted
300: lines, using full terminal resolution.
301: T}
302: -h T{
303: Use tabs instead of spaces
304: to speed up printing.
305: T}
306: -q T{
307: Invoke the simultaneous input-output mode of the @cw rd@ request.
308: T}
309: .TE
310: .PP
311: Each option is a separate argument;
312: for example,
313: .P1
314: troff -Tpost -ms -o4,6,8-10 @file1 ~ file2@
315: .P2
316: requests formatting of pages 4, 6, and 8 through 10 of a document contained in the files
317: named @file1@ and @file2@,
318: specifies the output device as a Postscript printer,
319: and invokes the macro package
320: .CW -ms .
321: .PP
322: Various pre- and post-processors are available for use with \*(NR and \*(TR.
323: These include the equation preprocessor
324: .I eqn
325: (for \*(TR only),
326: the table-construction preprocessor
327: .I tbl ,
328: and
329: .I pic ,
330: .I ideal ,
331: and
332: .I grap
333: for various forms of graphics.
334: A reverse-line postprocessor
335: .I col
336: is available for multiple-column \*(NR output on terminals without reverse-line ability;
337: .I col
338: expects the Model 37 Teletype
339: escape sequences that \*(NR produces by default.
340: .sp 100
341: .BP
342: .TL
343: Request Summary
344: .PP
345: In the following table,
346: the notation @+- N@ in the
347: .BI "Request Form
348: column means that the forms @N@, @+N@, or @-N@ are permitted,
349: to set the parameter to @N@, increment it by @N@, or decrement it by @N@,
350: respectively.
351: Plain @N@ means that the value is used to set the parameter.
352: .BI "Initial Values
353: separated by
354: .CW ;
355: are for
356: \*(TR
357: and
358: \*(NR
359: respectively.
360: In the
361: .BI Notes
362: column,
363: .TS
364: center;
365: c lw(4.5i).
366: B T{
367: Request normally causes a break.
368: The use of
369: .CW ' \&
370: as control character (instead of
371: .CW . )\&
372: suppresses the break function.
373: T}
374: D T{
375: Mode or relevant parameters associated with current diversion level.
376: T}
377: E T{
378: Relevant parameters are a part of the current environment.
379: T}
380: O T{
381: Must stay in effect until logical output.
382: T}
383: P T{
384: Mode must be still or again in effect at the time of physical output.
385: T}
386: T T{
387: \*(TR only; no effect in \*(NR.
388: T}
389: @bold v@, @bold p@, @bold m@, @bold u@ T{
390: Default scale indicator; if not specified, scale indicators are ignored.
391: T}
392: .TE
393: .sp
394: .tr &.
395: .ps 9
396: .vs 11
397: .nr z 0 1
398: .TS
399: lf4 lf4 lf4 lf4 lf4
400: lf4 lf4 lf4 lf4 lf4
401: lfCW l l l l.
402: Request Initial If No
403: Form Value Argument Notes Explanation
404: .sp .5
405: .T&
406: lf3 s s s s.
407: \\n+z. General Information
408: .sp .5
409: .T&
410: lf3 s s s s
411: lfCW l l l l.
412: \\n+z. Font and Character Size Control
413: .sp .5
414: &ps @+- N@ 10 point previous E,T Point size; also @cw "\es" +- N@.
415: &ss @N@ 12/36\fBm\fP ignored E,T Space-character size set to @N/36@ em.
416: &cs @ F~N~ M@ off - P,T Constant character space (width) mode (font @F@).
417: &bd @F~N@ off - P,T Embolden font @F@ by @N-1@ units.
418: &bd S@~F~N@ off - P,T Embolden Special Font when current font is @F@.
419: &ft@~F@ Roman previous E Change to font @F@; also @cw "\ef" x@, @cw "\ef(" xx@, @cw "\ef" N@.
420: &fp@~N~F~L@ R,I,B,...,S ignored - Mount font named @F@ on physical position @N>=1@;
421: long name is @L@ if given.
422: .sp .5
423: .T&
424: lf3 s s s s
425: lfCW l l l l.
426: \\n+z. Page Control
427: &pl @+- N@ 11i 11i @bold v@ Page length.
428: &bp @+- N@ @N=1@ - B,@bold v@ Eject current page; next page number @N@.
429: &pn @+- N@ @N=1@ ignored - Next page number @N@.
430: &po @+- N@ 1i; 0 previous @bold v@ Page offset.
431: &ne @N@ - @N=1 roman v@ D,@bold v@ Need @N@ vertical space.
432: &mk @R@ none internal D Mark current vertical place in register @R@.
433: &rt @+- N@ none internal D,@bold v@ Return (upward only) to marked vertical place.
434: .sp .5
435: .T&
436: lf3 s s s s
437: lfCW l l l l.
438: \\n+z. Text Filling, Adjusting, and Centering
439: &br - - B Break.
440: &fi fill - B,E Fill output lines.
441: &nf fill - B,E No filling or adjusting of output lines.
442: &ad @c@ adj, both adjust E Adjust output lines with mode @c@; @c = cw l , cw r , cw c , cw b , none@
443: &na adjust - E No output line adjusting.
444: &ce @N@ off @N=1@ B,E Center next @N@ input text lines.
445: .sp .5
446: .T&
447: lf3 s s s s
448: lfCW l l l l.
449: \\n+z. Vertical Spacing
450: &vs @N@ 12p; 1/6i previous E,@bold p@ Vertical baseline spacing (@V@).
451: &ls @N@ @N=1@ previous E Output @N-1@ @bold v@'s after each text output line.
452: &sp @N@ - @N=1@v B,@bold v@ Space vertical distance @N@ in either direction.
453: &sv @N@ - @N=1@v @bold v@ Save vertical distance @N@.
454: &os - - - Output saved vertical distance.
455: &ns space - D Turn no-space mode on.
456: &rs - - D Restore spacing; turn no-space mode off.
457: .sp .5
458: .T&
459: lf3 s s s s
460: lfCW l l l l.
461: \\n+z. Line Length and Indenting
462: &ll @+- N@ 6.5i previous E,@bold m@ Line length.
463: &in @+- N@ @N=0@ previous B,E,@bold m@ Indent.
464: &ti @+- N@ - ignored B,E,@bold m@ Temporary indent.
465: .sp .5
466: .ne 2.1
467: .T&
468: lf3 s s s s
469: lfCW l l l l.
470: \\n+z. Macros, Strings, Diversion, and Position Traps
471: &de @xx~yy@ - @.yy= cw ".."@ - Define or redefine macro @xx@; end at call of @yy@.
472: &am @xx~yy@ - @.yy= cw ".."@ - Append to a macro.
473: &ds @xx~string@ - ignored - Define a string @xx@ containing @string@.
474: &as @xx~string@ - ignored - Append @string@ to string @xx@.
475: &rm @xx@ - ignored - Remove request, macro, or string.
476: &rn @xx~yy@ - ignored - Rename request, macro, or string @xx@ to @yy@.
477: &di @xx@ - end D Divert output to macro @xx@.
478: &da @xx@ - end D Divert and append to @xx@.
479: &wh @N~xx@ - - @bold v@ Set location trap; negative is w.r.t. page bottom.
480: &ch @xx~N@ - - @bold v@ Change trap location.
481: &dt @N~xx@ - off D,@bold v@ Set a diversion trap.
482: &it @N~xx@ - off E Set an input-line count trap.
483: &em @xx@ none none - End macro is @xx@.
484: .sp .5
485: .T&
486: lf3 s s s s
487: lfCW l l l l.
488: \\n+z. Number Registers
489: &nr @R~+- N~M@ - @bold u@ Define and set number register @R@; auto-increment by @M@.
490: &af @R~c@ arabic - - Assign format to register @R@ (@c= cw "1" , cw i , cw I , cw a , cw A@).
491: &rr @R@ - - - Remove register @R@.
492: .sp .5
493: .T&
494: lf3 s s s s
495: lfCW l l l l.
496: \\n+z. Tabs, Leaders, and Fields
497: &ta@~Nt~. . .@ 0.5i; 0.8n none E,@bold m@ Tab settings; left-adjusting, unless @t= cw R@ (right), @cw C@ (centered).
498: &tc@~c@ none none E Tab repetition character.
499: &lc@~c@ @cw "."@ none E Leader repetition character.
500: &fc@~a~b@ off off - Set field delimiter @a@ and pad character @b@.
501: .sp .5
502: .T&
503: lf3 s s s s
504: lfCW l l l l.
505: \\n+z. Input and Output Conventions and Character Translations
506: &ec@~c@ \e \e - Set escape character.
507: &eo on - - Turn off escape character mechanism.
508: &lg@~N@ on; - on T Ligature mode on if @N>0@.
509: &ul@~N@ off @N=1@ E Underline (italicize in \*(TR) @N@ input lines.
510: &cu@~N@ off @N=1@ E Continuous underline in \*(NR; in \*(TR, like @cw ul@.
511: &uf@~F@ Italic Italic - Underline font set to @F@ (to be switched to by @cw ul@).
512: &cc@~c@ @cw .@ @cw .@ E Set control character to @c@.
513: &c2@~c@ @cw "'"@ @cw "'"@ E Set no-break control character to @c@.
514: &tr@~abcd....@ none - O Translate @a@ to @b@, etc., on output.
515: .sp .5
516: .T&
517: lf3 s s s s.
518: \\n+z. Local Horizontal and Vertical Motions, and the Width Function
519: .sp .5
520: .T&
521: lf3 s s s s.
522: \\n+z. Overstrike, Bracket, Line-drawing, Graphics, and Zero-width Functions
523: .sp .5
524: .T&
525: lf3 s s s s
526: lfCW l l l l.
527: \\n+z. Hyphenation.
528: &nh hyphenate - E No hyphenation.
529: &hy@~N@ hyphenate hyphenate E Hyphenate; @N =@ mode.
530: &hc@~c@ @cw "\e%"@ @cw "\e%"@ E Hyphenation indicator character @c@.
531: &hw@~word~. . .@ ignored - Add words to hyphenation dictionary.
532: .sp .5
533: .T&
534: lf3 s s s s
535: lfCW l l l l.
536: \\n+z. Three-Part Titles.
537: &tl@~'l'c'r'@ - - Three-part title; delimiter may be any character.
538: &pc@~c@ @cw %@ off - Page number character.
539: <@~+- N@ 6.5i previous E,@bold m@ Length of title.
540: .sp .5
541: .T&
542: lf3 s s s s
543: lfCW l l l l.
544: \\n+z. Output Line Numbering.
545: &nm@~+- N^M^S^I@ off E Number mode on or off, set parameters.
546: &nn@~N@ - @N=1@ E Do not number next @N@ lines.
547: .sp .5
548: .T&
549: lf3 s s s s
550: lfCW l l l l.
551: \\n+z. Conditional Acceptance of Input
552: &if@~c~any@ - - If condition @c@ true, accept @any@ as input;
553: for multi-line, use @cw "\e{" any cw "\e}"@.
554: &if !@c~any@ - - If condition @c@ false, accept @any@.
555: &if@~N~any@ - @bold u@ If expression @N > 0@, accept @any@.
556: &if !@N~any@ - @bold u@ If expression @N <= 0@ [sic], accept @any@.
557: &if@~ 's1 's2 '~any@ - - If string @s1@ identical to @s2@, accept @any@.
558: &if !@ 's1 's2 '~any@ - - If string @s1@ not identical to @s2@, accept @any@.
559: &ie@~c~any@ - @bold u@ If portion of if-else; all above forms (like @cw "if"@).
560: &el@~any@ - - Else portion of if-else.
561: .sp .5
562: .T&
563: lf3 s s s s
564: lfCW l l l l.
565: \\n+z. Environment Switching
566: &ev@~N@ @N=0@ previous - Environment switch (push down).
567: .sp .5
568: .T&
569: lf3 s s s s
570: lfCW l l l l.
571: \\n+z. Insertions from the Standard Input
572: &rd@~prompt@ - @prompt@=\s-1BEL\s+1 - Read insertion.
573: &ex - - - Exit.
574: .sp .5
575: .T&
576: lf3 s s s s
577: lfCW l l l l.
578: \\n+z. Input/Output File Switching
579: &so@~filename@ - - Switch source file (push down).
580: &nx@~filename@ end-of-file - Next file.
581: &sy@~string@ - - Execute program @string@. Output is not interpolated.
582: &pi@~string@ - - Pipe output to program @string@.
583: &cf@~filename@ - - Copy file contents to \*(TR output.
584: .sp .5
585: .T&
586: lf3 s s s s
587: lfCW l l l l.
588: \\n+z. Miscellaneous
589: &mc@~c~N@ - off E,@bold m@ Set margin character @c@ and separation @N@.
590: &tm@~string@ - newline - Print @string@ on terminal (standard error).
591: &ab@~string@ - newline - Print @string@ on standard error, exit program.
592: &ig@~yy@ - @.yy= cw ".."@ - Ignore input until call of @yy@.
593: &lf@~N ~f@ - - Set input line number to @N@ and filename to @f@.
594: &pm@~t@ - all - Print macro names, sizes; if @t@ present, print only total of sizes.
595: &fl - - B Flush output buffer.
596: .sp .5
597: .T&
598: lf3 s s s s.
599: \\n+z. Output and Error Messages
600: .sp .5
601: \\n+z. Output Language
602: .sp .5
603: \\n+z. Device and Font Description Files
604: .TE
605: .br
606: .nr zz 9
607: .de cl
608: .ie \\n+(cl<\n(zz \{\
609: . po +\\n(.lu/\n(zzu
610: . rt\}
611: .el \{.po 1i\}
612: ..
613: .nr cl 0 1
614: .di zz
615: .ta .35iR
616: .nf
617: .ps 9
618: .vs 10.5
619: \f(CWab\fP 20
620: \f(CWad\fP 4
621: \f(CWaf\fP 8
622: \f(CWam\fP 7
623: \f(CWas\fP 7
624: \f(CWbd\fP 2
625: \f(CWbp\fP 3
626: \f(CWbr\fP 4
627: \f(CWc2\fP 10
628: \f(CWcc\fP 10
629: \f(CWce\fP 4
630: \f(CWcf\fP 19
631: \f(CWch\fP 7
632: \f(CWcs\fP 2
633: \f(CWcu\fP 10
634: \f(CWda\fP 7
635: \f(CWde\fP 7
636: \f(CWdi\fP 7
637: \f(CWds\fP 7
638: \f(CWdt\fP 7
639: \f(CWec\fP 10
640: \f(CWel\fP 16
641: \f(CWem\fP 7
642: \f(CWeo\fP 10
643: \f(CWev\fP 17
644: \f(CWex\fP 18
645: \f(CWfc\fP 9
646: \f(CWfi\fP 4
647: \f(CWfl\fP 20
648: \f(CWfp\fP 2
649: \f(CWft\fP 2
650: \f(CWhc\fP 13
651: \f(CWhw\fP 13
652: \f(CWhy\fP 13
653: \f(CWie\fP 16
654: \f(CWif\fP 16
655: \f(CWig\fP 20
656: \f(CWin\fP 6
657: \f(CWit\fP 7
658: \f(CWlc\fP 9
659: \f(CWlg\fP 10
660: \f(CWlf\fP 20
661: \f(CWll\fP 6
662: \f(CWls\fP 5
663: \f(CWlt\fP 14
664: \f(CWmc\fP 20
665: \f(CWmk\fP 3
666: \f(CWna\fP 4
667: \f(CWne\fP 3
668: \f(CWnf\fP 4
669: \f(CWnh\fP 13
670: \f(CWnm\fP 15
671: \f(CWnn\fP 15
672: \f(CWnr\fP 8
673: \f(CWns\fP 5
674: \f(CWnx\fP 19
675: \f(CWos\fP 5
676: \f(CWpc\fP 14
677: \f(CWpi\fP 19
678: \f(CWpl\fP 3
679: \f(CWpm\fP 20
680: \f(CWpn\fP 3
681: \f(CWpo\fP 3
682: \f(CWps\fP 2
683: \f(CWrd\fP 18
684: \f(CWrm\fP 7
685: \f(CWrn\fP 7
686: \f(CWrr\fP 8
687: \f(CWrs\fP 5
688: \f(CWrt\fP 3
689: \f(CWso\fP 19
690: \f(CWsp\fP 5
691: \f(CWss\fP 2
692: \f(CWsv\fP 5
693: \f(CWsy\fP 19
694: \f(CWta\fP 9
695: \f(CWtc\fP 9
696: \f(CWti\fP 6
697: \f(CWtl\fP 14
698: \f(CWtm\fP 20
699: \f(CWtr\fP 10
700: \f(CWuf\fP 10
701: \f(CWul\fP 10
702: \f(CWvs\fP 5
703: \f(CWwh\fP 7
704: .di
705: .nr aa \n(dn/\n(zz
706: .ne \\n(aau+10p
707: .sp
708: .SP 2
709: .TL
710: Alphabetical Request and Section Number Cross Reference
711: .SP .5
712: .LP
713: .sp .5
714: .nf
715: .wh \n(nlu+\n(aau cl
716: .nr qq \n(nlu+\n(aau
717: .ps
718: .vs
719: .mk
720: .zz
721: .rt
722: .sp \n(.tu
723: .ch cl 12i
724: .sp 100
725: .BP
726: .TL
727: Escape Sequences for Characters, Indicators, and Functions
728: .SP .5
729: .LP
730: .ps -1
731: .vs -1
732: .TS
733: center;
734: c2 l
735: c2 l2 l
736: n2 l2fCW l.
737: .ft 4
738: Section Escape
739: Reference Sequence Meaning
740: .ft
741: .sp .5
742: 10.1 \e\e \e prevents or delays the interpretation of \&\f(CW\e\fP
743: 10.1 \ee Printable version of the current escape character.
744: 2.1 \e' \' (acute accent); equivalent to \&\f(CW\e(aa\fP
745: 2.1 \e` \` (grave accent); equivalent to \&\f(CW\e(ga\fP
746: 2.1 \e\- \- Minus sign in the current font
747: 7. \e\^. Period (dot) (see \&\f(CWde\fP)
748: 11.1 \e\f2space\fP Unpaddable space-size space character
749: 11.1 \e0 Digit width space
750: 11.1 \e| 1/6 em narrow space character (zero width in \*(NR)
751: 11.1 \e^ 1/12 em half-narrow space character (zero width in \*(NR)
752: .tr &&
753: 4.1 \e& Non-printing, zero width character
754: .tr &.
755: 10.6 \e! Transparent line indicator
756: 10.8 \e" Beginning of comment; continues to end of line
757: 13. \e% Default optional hyphenation character
758: 2.1 \e(@xx@ Character named @xx@
759: 7.1 \e*@x,~@\e*(@xx@ Interpolate string @x@ or @xx@
760: 7.3 \e$@N@ Interpolate argument @1 <= N <= 9@
761: 9.1 \ea Non-interpreted leader character
762: 12.3 \eb'@abc...@' Bracket building function
763: 4.2 \ec Connect to next input text
764: 2.1 \eC'@xyz@' Character named @xyz@
765: 11.1 \ed Downward 1/2 em vertical motion (1/2 line in \*(NR)
766: 12.5 \eD'@c...@' Draw graphics function @c@ with parameters @. . .@; @c= cw l , cw c , cw e , cw a , cw "~"@
767: 2.2 \ef@x,~@\ef(@xx,~@\ef@N@ Change to font named @x@ or @xx@, or position @N@
768: 8. \eg@x,~@\eg(@xx@ Format of number register @x@ or @xx@
769: 11.1 \eh'@N@' Local horizontal motion; move right @N@ (negative left)
770: 2.3 \eH'@N@' Height of current font is @N@
771: 11.3 \ek@x@ Mark horizontal input place in register @x@
772: 12.4 \el'@Nc@' Horizontal line drawing function (optionally with @c@ )
773: 12.4 \eL'@Nc@' Vertical line drawing function (optionally with @c@ )
774: 8. \en@x,~@\en(@xx@ Contents of number register @x@ or @xx@
775: 2.1 \eN'@N@' Character number @N@ on current font
776: 12.1 \eo'@abc...@' Overstrike characters @a,~ b,~ c@, ...
777: 4.1 \ep Break and spread output line
778: 11.1 \er Reverse 1 em vertical motion (reverse line in \*(NR)
779: 2.3 \es@N,~@\es@+- N@ Point-size change function; also @cw "\es(" nn@, @cw "\es" +- cw "(" nn@
780: 2.2 \eS'@N@' Slant output @N@ degrees
781: 9.1 \et Non-interpreted horizontal tab
782: 11.1 \eu Reverse (up) 1/2 em vertical motion (1/2 line in \*(NR)
783: 11.1 \ev'@N@' Local vertical motion; move down N (negative up)
784: 11.2 \ew'@string@' Width of @string@
785: 5.2 \ex'@N@' Extra line-space function (negative before, positive after)
786: 10.7 \eX'@string@' Ouput @string@ as device control function
787: 12.2 \ez@c@ Print @c@ with zero width (without spacing)
788: 16. \e{ Begin conditional input
789: 16. \e} End conditional input
790: 10.8 \e@newline@ Concealed (ignored) newline
791: - \e@Z@ @Z@, any character not listed above
792: .TE
793: .ps +1
794: .vs +1
795: .LP
796: The escape sequences
797: .CW \e\e ,
798: .CW \e\^. ,
799: .CW \e" ,
800: .CW \e$ ,
801: .CW \e* ,
802: .CW \ea ,
803: .CW \en ,
804: .CW \et ,
805: .CW \eg ,
806: and
807: .CW \e@newline@
808: are interpreted in copy mode (\(sc7.2).
809: .SP .5i
810: \0
811: .sp 100
812: .BP
813: .TL
814: Predefined Number Registers
815: .LP
816: .ps -1
817: .vs -1
818: .TS
819: c2l
820: c2 l2 l
821: n2 l2fCW l.
822: .ft 4
823: Section Register
824: Reference Name Description
825: .ft
826: .sp .5
827: 3. % Current page number.
828: 11.2 ct Character type (set by \&\fC\ew\fP function).
829: 7.4 dl Width (maximum) of last completed diversion.
830: 7.4 dn Height (vertical size) of last completed diversion.
831: - dw Current day of the week (1-7).
832: - dy Current day of the month (1-31).
833: 15. ln Output line number.
834: - mo Current month (1-12).
835: 4.1 nl Vertical position of last printed text baseline.
836: 11.2 sb Depth of string below baseline (generated by \&\fC\ew\fP function).
837: 11.2 st Height of string above baseline (generated by \&\fC\ew\fP function).
838: - yr Last two digits of current year.
839: .TE
840: .ps +1
841: .vs +1
842:
843:
844: .TL
845: Predefined Read-Only Number Registers
846: .LP
847: .ps -1
848: .vs -1
849: .TS
850: c2 l
851: c2 l2 l
852: n2 l2fCW l.
853: .ft 4
854: Section Register
855: Reference Name Description
856: .ft
857: .sp .5
858: 19. $$ Process id of \*(TR or \*(NR.
859: 7.3 &$ Number of arguments available at the current macro level.
860: 5.2 &a Post-line extra line-space most recently used in @cw "\ex'" N cw "'" @.
861: - &A Set to 1 in \*(TR, if @cw -a@ option used; always 1 in \*(NR.
862: 2.3 &b Emboldening level.
863: 20. &c Number of lines read from current input file.
864: 7.4 &d Current vertical place in current diversion; equal to @cw nl@, if no diversion.
865: 2.2 &f Current font number.
866: 20. &F Current input file name [sic].
867: 4. &h Text baseline high-water mark on current page or diversion.
868: 11.1 &H Available horizontal resolution in basic units.
869: 6. &i Current indent.
870: 4.2 &j Current @cw ad@ mode.
871: 4.1 &k Current output horizontal position.
872: 6. &l Current line length.
873: 5.1 &L Current @cw ls@ value.
874: 4. &n Length of text portion on previous output line.
875: 3. &o Current page offset.
876: 3. &p Current page length.
877: 7.5 .R Number of unused number registers.
878: - &T Set to 1 in \*(NR, if \&\fC\-T\fP option used; always 0 in \*(TR.
879: 2.3 &s Current point size.
880: 7.5 &t Distance to the next trap.
881: 4.1 &u Equal to 1 in fill mode and 0 in nofill mode.
882: 5.1 &v Current vertical line spacing.
883: 11.1 &V Available vertical resolution in basic units.
884: 11.2 &w Width of previous character.
885: - &x Reserved version-dependent register.
886: - &y Reserved version-dependent register.
887: 7.4 &z Name [sic] of current diversion.
888: .TE
889: .ps +1
890: .vs +1
891: .sp 100
892: .BP
893: .TL
894: Reference Manual
895: .NH
896: General Explanation
897: .sc "Form of input.
898: Input consists of \fItext lines\fR, which are destined to be printed,
899: interspersed with \fIcontrol lines\fR,
900: which set parameters or otherwise control subsequent processing.
901: Control lines begin with a \fIcontrol character\fR\(em\
902: normally \&\fC.\fR (period) or \&\fC'\fR (single quote)\(em\
903: followed by a one or two character name that specifies
904: a basic \fIrequest\fR or the substitution of
905: a user-defined \fImacro\fR in place of the control line.
906: The control character \&\fC'\fR suppresses the \fIbreak\fR function\(em\
907: the forced output of a partially filled line\(em\
908: caused by certain requests.
909: The control character may be separated from the request/macro name by
910: white space (spaces and/or tabs) for aesthetic reasons.
911: Names should be followed by either
912: space or newline.
913: Control lines with unrecognized names are ignored.
914: .PP
915: Various special functions may be introduced anywhere in the input by
916: means of an \fIescape\fR character, normally \&\fC\e\fR.
917: For example, the function
918: .CW \en@R@
919: causes the interpolation of the contents of the
920: \fInumber register R\fR
921: in place of the function;
922: here @R@ is either a single character name
923: as in \&\fC\en\fIx\fR,
924: or a two-character name introduced by
925: a left-parenthesis, as in \&\fC\en(\fIxx\fR.
926: .sc "Formatter and device resolution.
927: \*(Tr internally stores and processes dimensions in units that correspond to
928: the particular device for which output is being prepared;
929: values from 300 to 1200/inch are typical.
930: See \(sc23.
931: \*(Nr internally uses 240 units/inch,
932: corresponding to the least common multiple of the
933: horizontal and vertical resolutions of various
934: typewriter-like output devices.
935: \*(Tr rounds horizontal/vertical numerical parameter input to the actual
936: horizontal/vertical resolution of the output device indicated by the \&\fC-T\fR option
937: (default
938: .CW post ).
939: \*(Nr similarly rounds numerical input to the actual resolution
940: of its output device
941: (default Model 37 Teletype).
942: .sc "Numerical parameter input.
943: Both \*(NR and \*(TR
944: accept numerical input with the appended scale
945: indicators
946: shown in the following table,
947: where
948: \fIS\fR is the current type size in points and
949: \fIV\fR is the current vertical line spacing in
950: basic units.
951: .TS
952: center box;
953: c|c
954: c|c
955: c|l.
956: Scale
957: Indicator Meaning
958: _
959: \&\fCi\fR Inch
960: \&\fCc\fR Centimeter
961: \&\fCP\fR Pica = 1/6 inch
962: \&\fCm\fR Em = \fIS\fR points
963: \&\fCn\fR En = Em/2
964: \&\fCp\fR Point = 1/72 inch
965: \&\fCu\fR Basic unit
966: \&\fCv\fR Vertical line space \fIV\fR
967: none Default, see below
968: .TE
969: In \*(NR, both the em and the en are taken to be equal to the
970: nominal character width,
971: which is output-device dependent;
972: common values are 1/10 and 1/12 inch.
973: Actual character widths in \*(NR need not be all the same and constructed characters
974: such as \-> (\(->) are often extra wide.
975: The default scaling is
976: .CW m
977: for the horizontally-oriented requests
978: and functions
979: .CW ll ,
980: .CW in ,
981: .CW ti ,
982: .CW ta ,
983: .CW lt ,
984: .CW po ,
985: .CW mc ,
986: .CW \eh ,
987: .CW \el ,
988: and horizontal coordinates of
989: .CW \eD ;
990: .CW v
991: for the vertically-oriented requests and functions
992: .CW pl ,
993: .CW wh ,
994: .CW ch ,
995: .CW dt ,
996: .CW sp ,
997: .CW sv ,
998: .CW ne ,
999: .CW rt ,
1000: .CW \ev ,
1001: .CW \ex ,
1002: .CW \eL ,
1003: and vertical coordinates of
1004: .CW \eD ;
1005: .CW p
1006: for the
1007: .CW vs
1008: request;
1009: and
1010: .CW u
1011: for the requests
1012: .CW nr ,
1013: .CW if ,
1014: and
1015: .CW ie .
1016: \fIAll\fR other requests ignore any scale indicators.
1017: When a number register containing an already appropriately scaled number
1018: is interpolated to provide numerical input,
1019: the unit scale indicator
1020: \&\fCu\fR may need to be appended to prevent
1021: an additional inappropriate default scaling.
1022: The number, @N@, may be specified in decimal-fraction form
1023: but the parameter finally stored is rounded to an integer number of basic units.
1024: Internal computations are performed in integer arithmetic.
1025: .PP
1026: The \fIabsolute position\fR indicator \&\fC|\fR may be prepended
1027: to a number @N@
1028: to generate the distance to the vertical or horizontal place @N@.
1029: For vertically-oriented requests and functions, \&\fC|\fP@N@
1030: becomes the distance in basic units from the current vertical place on the page or in a \fIdiversion\fR (\(sc7.4)
1031: to the vertical place @N@.
1032: For \fIall\fR other requests and functions,
1033: \&\fC|\fP@N@
1034: becomes the distance from
1035: the current horizontal place on the \fIinput\fR line to the horizontal place @N@.
1036: For example,
1037: .P1
1038: \&.sp |3.2c
1039: .P2
1040: will space in the required direction to 3.2 centimeters from the top of the page.
1041: .sc "Numerical expressions.
1042: .tr &&
1043: Wherever numerical input is expected an expression involving parentheses,
1044: the arithmetic operators \&\fC+\fR, \&\fC-\fR, \&\fC/\fR, \&\fC\(**\fR, \&\fC%\fR (mod),
1045: and the logical operators
1046: \&\fC<\fR,
1047: \&\fC>\fR,
1048: \&\fC<=\fR,
1049: \&\fC>=\fR,
1050: \&\fC=\fR (or \&\fC==\fR),
1051: \&\fC&\fR\ (and),
1052: \&\fC:\fR\ (or)
1053: may be used.
1054: Except where controlled by parentheses, evaluation of expressions is left-to-right;
1055: there is no operator precedence.
1056: In the case of certain requests, an initial \&\fC+\fR or \&\fC-\fR is stripped
1057: and interpreted as an increment or decrement indicator respectively.
1058: In the presence of default scaling, the desired scale indicator must be
1059: attached to \fIevery\fR number in an expression
1060: for which the desired and default scaling differ.
1061: For example,
1062: if the number register \&\fCx\fR contains 2
1063: and the current point size is 10,
1064: then
1065: .P1
1066: \&.ll (4.25i+\enxP+3)/2u
1067: .P2
1068: will set the line length to 1/2 the sum of 4.25 inches + 2 picas + 3 ems.
1069: .sc "Notation.
1070: Numerical parameters are indicated in this manual in two ways.
1071: @+- N@ means that the argument may take the forms @N@, @+N@, or @-N@ and
1072: that the corresponding effect is to set the parameter
1073: to @N@, to increment it by @N@, or to decrement it by @N@ respectively.
1074: Plain @N@ means that an initial algebraic sign is \fInot\fR
1075: an increment indicator,
1076: but merely the sign of @N@.
1077: Generally, unreasonable numerical input is either ignored
1078: or truncated to a reasonable value.
1079: For example,
1080: most requests expect to set parameters to non-negative
1081: values;
1082: exceptions are
1083: .CW sp ,
1084: .CW wh ,
1085: .CW ch ,
1086: .CW nr ,
1087: and
1088: .CW if .
1089: The requests
1090: .CW ps ,
1091: .CW ft ,
1092: .CW po ,
1093: .CW vs ,
1094: .CW ls ,
1095: .CW ll ,
1096: .CW in ,
1097: and
1098: .CW lt
1099: restore the previous parameter value in the absence
1100: of an argument.
1101: .PP
1102: Single character arguments are indicated by single lower case letters
1103: and
1104: one/two character arguments are indicated by a pair of lower case letters.
1105: Character string arguments are indicated by multi-character mnemonics.
1106: .NH
1107: Font and Character Size Control
1108: .sc "Character set.
1109: The \*(TR character set is defined by a description file specific to each output device (\(sc23).
1110: There are normally several regular fonts and one or more special fonts.
1111: Characters are input as themselves (\s-2ASCII\s0),
1112: as @cw "\e(" xx@, as @cw "\eC'" name cw "'"@,
1113: or as
1114: .CW \eN'@n@' .
1115: The form
1116: .CW \eC'@name@'
1117: permits a name of any length;
1118: the form
1119: .CW \eN'@n@'
1120: refers to the @n@-th character on the current font,
1121: whether named or not.
1122: .PP
1123: Normally the input characters
1124: .CW ' ,
1125: .CW ` ,
1126: and
1127: .CW -
1128: are printed as `, ', and - respectively;
1129: .CW \e' ,
1130: .CW \e` ,
1131: and
1132: .CW \e-
1133: produce \', \`, and \-.
1134: Non-existent characters are printed as a 1-em space.
1135: .PP
1136: \*(Nr has an analogous, but different, mechanism for defining legal characters
1137: and how to print them.
1138: By default all \s-1ASCII\s0 characters are valid.
1139: There are such
1140: additional characters as may be available on
1141: the output device,
1142: such characters as may be able to be constructed
1143: by overstriking or other combination,
1144: and those that can reasonably be mapped
1145: into other printable characters.
1146: The exact behavior is determined by a driving
1147: table prepared for each device.
1148: .sc "Fonts.
1149: \*(Tr
1150: begins execution by reading information for a set of defaults fonts,
1151: said to be
1152: .I mounted ;
1153: conventionally, the first four are
1154: Times Roman (\&\fCR\fR),
1155: .I "Times Italic
1156: (\&\fCI\fR),
1157: .B "Times Bold
1158: (\&\fCB\fR),
1159: and
1160: .BI "Times Bold Italic
1161: (\&\fCBI\fR) ,
1162: and the last is a Special font
1163: .CW S ) (
1164: containing miscellaneous characters.
1165: These fonts are used in this document.
1166: The set of fonts and positions is determined by the device description file,
1167: described in \(sc23.
1168: .PP
1169: The current font, initially Roman, may be changed
1170: by use of the \&\fCft\fR request,
1171: or by embedding at any desired point
1172: either \&\fC\ef\fIx\fR, \&\fC\ef(\fIxx\fR, or \&\fC\ef\fP@N@,
1173: where
1174: \fIx\fR and \fIxx\fR are the name of a font
1175: and @N@ is a numerical font position.
1176: .PP
1177: It is not necessary to change to the Special font;
1178: characters on that font are automatically handled
1179: as if they were physically part of the current font.
1180: The Special font may actually be several fonts;
1181: the name
1182: .CW S
1183: is reserved and is generally used for one of these.
1184: All special fonts must be mounted after regular fonts.
1185: .PP
1186: \*(Tr can be informed that any particular font is mounted
1187: by use of the \&\fCfp\fR request.
1188: The list of known fonts is installation dependent.
1189: In the subsequent discussion of font-related requests,
1190: @F@ represents either a one/two-character
1191: font name or the numerical font position.
1192: The current font is available (as a numerical position) in the read-only number register \&\fC.f\fR.
1193: .PP
1194: A request for a named but not-mounted font is honored
1195: if the font description information exists.
1196: In this way, there is no limit on the number of fonts that may be printed
1197: in any part of a document.
1198: Mounted fonts may be handled more efficiently,
1199: and they may be referred to by their mount positions,
1200: but there is no other difference.
1201: .PP
1202: The function
1203: .CW \eS'@+- N@'
1204: causes the current font to be slanted by
1205: @+- N@
1206: degrees.
1207: Not all devices support slanting.
1208: .PP
1209: \*(Nr understands font control
1210: and normally underlines italic characters (see \(sc10.5).
1211: .sc "Character size.
1212: Character point sizes available depend on the specific output device;
1213: a typical (historical) set of values is
1214: 6, 7, 8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 28, and 36.
1215: This is a range of 1/12 inch to 1/2 inch.
1216: The \&\fCps\fR request is used to change or restore the point size.
1217: Alternatively the point size may be changed between any two characters
1218: by embedding a
1219: .CW \es@N@
1220: at the desired point
1221: to set the size to @N@,
1222: or a
1223: .CW "\&\fC\es@+- N@
1224: (@1<=N<=9@)
1225: to increment/decrement the size by @N@;
1226: .CW \es0
1227: restores the previous size.
1228: Requested point size values that are between two valid
1229: sizes yield the larger of the two.
1230: .PP
1231: Note that through an accident of history, a construction like
1232: .CW \es39
1233: is parsed as size 39, and thus converted to size 36 (given the sizes above),
1234: while
1235: .CW \es40
1236: is parsed as size 4 followed by
1237: .CW 0 .
1238: The syntax
1239: @cw "\es(" nn@ and @cw "\es" +- cw "(" nn@
1240: permits specification of sizes that would otherwise be ambiguous.
1241: .PP
1242: The current size is available in the \&\fC.s\fR register.
1243: \*(Nr ignores type size requests.
1244: .PP
1245: The function
1246: .CW "\eH'@+- N@'
1247: sets \H'+2'the height of the current font\H'0' to
1248: @N@, or increments it by @+N@, or decrements it by @-N@;
1249: if @N=0@, the height is restored to the current point size.
1250: In each case, the width is unchanged.
1251: Not all devices support independent height and width for characters.
1252: .FS
1253: *The fields have the same meaning as described earlier in the Request Summary.
1254: .FE
1255: .SP .5
1256: .LP
1257: .ne 2.1
1258: .ta 1i 2i 3i 4i
1259: \f4Request\fR \f4Initial\fR \f4If\ No\fR
1260: .br
1261: \f4Form\fR \f4Value\fR \f4Argument\fR \f4Notes\fR
1262: .bt "\&\fC.ps\fI \(+-N\fR*" "10\|point" "previous" "E" "Point size
1263: set to \(+-@N@.
1264: Alternatively embed
1265: .CW \es@N@
1266: or
1267: .CW "\&\fC\es@+- N@" .
1268: Any positive size value may be requested;
1269: if invalid, the next larger valid size will result, with a
1270: maximum of 36.
1271: A paired sequence
1272: @+N@, @-N@
1273: will work because the previous requested value is also remembered.
1274: Ignored in \*(NR.
1275: .bt "\&\fC.ss\fI N\fR" "12/36\|em" "ignored" "E" "Space-character size
1276: (i.e., inter-word gap)
1277: is set to @N@/36 ems.
1278: This size is the minimum word spacing in adjusted text.
1279: Ignored in \*(NR.
1280: .bt "\&\fC.cs\fI\|F\|N\|M\fR" "off" "-" "P" "Constant character space
1281: (width) mode is
1282: set on for font @F@ (if mounted); the width of every character will be
1283: taken to be @N@/36 ems.
1284: If @M@ is absent,
1285: the em is that of the character's point size;
1286: if @M@ is given,
1287: the em is @M@ points.
1288: All affected characters
1289: are centered in this space, including those with an actual width
1290: larger than this space.
1291: Special Font characters occurring while the current font
1292: is @F@ are also so treated.
1293: If @N@ is absent, the mode is turned off.
1294: The mode must be in effect when the characters are physically printed.
1295: Ignored in \*(NR.
1296: .bt "\&\fC.bd\fI F N\fR" "off" "-" "P" "The characters in font @F@ will be artificially
1297: emboldened by printing each one twice, separated by @N-1@ basic units.
1298: A reasonable value for @N@ is 3 when the character size is near 10 points.
1299: If @N@ is missing the embolden mode is turned off.
1300: The emboldening value @N@ is in the \&\fC.b\fP register.
1301: .IP
1302: .bd R 3
1303: This paragraph is printed with \&\fC.bd R 3\fR.
1304: The mode must be in effect when the characters are physically printed.
1305: Ignored in \*(NR.
1306: .br
1307: .bd R
1308: .bt "\&\fC.bd S \fIF N\fR" "off" "-" "P" "The characters in the Special font
1309: will be emboldened whenever the current font is @F@.
1310: The mode must be in effect when the characters are physically printed.
1311: Ignored in \*(NR.
1312: .bt "\&\fC.ft\fP @F@" "Roman" "previous" "E" "Font changed to
1313: @F@.
1314: Alternatively, embed
1315: .CW \ef@F@ .
1316: The font name \&\fCP\fR is reserved to mean the previous font,
1317: and the name
1318: .CW S
1319: for the special font.
1320: .bt "\&\fC.fp \fIN F L\fR" "R,I,B,...,S" "ignored" "-" "Font position.
1321: This is a statement
1322: that a font named @F@ is associated with position @N@.
1323: It is a fatal error if @F@ is not known.
1324: For fonts with names longer than two characters,
1325: .I L
1326: refers to the long name,
1327: and
1328: .I F
1329: becomes a synonym.
1330: There is generally a limit of about 10 mounted fonts.
1331: .NH
1332: Page control
1333: .PP
1334: Top and bottom margins are not automatically provided;
1335: it is conventional to define two \fImacros\fR and to set \fItraps\fR
1336: for them at vertical positions 0 (top) and @-N@ (distance @N@ up from the bottom).
1337: See \(sc7 and Tutorial Examples \(scT2.
1338: A pseudo-page transition onto the first page occurs
1339: either when the first \fIbreak\fR occurs or
1340: when the first \fInon-diverted\fR text processing occurs.
1341: Arrangements
1342: for a trap to occur at the top of the first page
1343: must be completed before this transition.
1344: In the following, references to the \fIcurrent diversion\fR (\(sc7.4)
1345: mean that the mechanism being described works during both
1346: ordinary and diverted output (the former considered as the top diversion level).
1347: .PP
1348: The limitations on \*(TR and \*(NR output dimensions
1349: are device dependent.
1350: .bt "\&\fC.pl\fI \(+-N\fR" "11\|in" "11\|in" "\fBv\fR" "Page length set to @+- N@.
1351: The current page length is available in the \&\fC.p\fR register.
1352: .bt "\&\fC.bp\fI \(+-N\fR" "\fIN\(eq\fR1" "-" "B,\fBv\fR" "Begin page.
1353: The current page is ejected and a new page is begun.
1354: If @+- N@ is given, the new page number will be @+- N@.
1355: Also see request \&\fCns\fR.
1356: .bt "\&\fC.pn\fI \(+-N\fR" "@N@\(eq1" "ignored" "-" "Page number.
1357: The next page (when it occurs) will have the page number @+- N@.
1358: A \&\fCpn\fR must occur before the initial pseudo-page transition
1359: to affect the page number of the first page.
1360: The current page number is in the \&\fC%\fR register.
1361: .bt "\&\fC.po\fI \(+-N\fR" "1\|in; 0" "previous" "\fBv\fR" "Page offset.
1362: The current \fIleft margin\fR is set to @+- N@.
1363: The \*(TR initial value provides 1 inch of paper margin
1364: on a typical device.
1365: The current page offset is available in the \&\fC.o\fR register.
1366: .bt "\&\fC.ne\fI N\fR" "-" "\fIN\(eq\fR1\|\fIV\fR" "D,\fBv\fR" "Need @N@ vertical space.
1367: If the distance \fID\fR to the next trap position (see \(sc7.5) is less than @N@,
1368: a forward vertical space of size \fID\fR occurs,
1369: which will spring the trap.
1370: If there are no remaining
1371: traps on the page,
1372: \fID\fR is the distance to the bottom of the page.
1373: If @D<V@, another line could still be output
1374: and spring the trap.
1375: In a diversion, \fID\fR is the distance to the \fIdiversion trap\fR, if any,
1376: or is very large.
1377: .bt "\&\fC.mk\fI R\fR" "none" "internal" "D" "Mark the current vertical place
1378: in an internal register (both associated with the current diversion level),
1379: or in register @R@, if given.
1380: See \&\fCrt\fR request.
1381: .bt "\&\fC.rt\fI \(+-N\fR" "none" "internal" "D,\fBv\fR" "Return \fIupward only\fR to a marked vertical place
1382: in the current diversion.
1383: If @+- N@ (with respect to current place) is given,
1384: the place is @+- N@ from the top of the page or diversion
1385: or, if @N@ is absent, to a
1386: place marked by a previous \&\fCmk\fR.
1387: The \&\fCsp\fR request (\(sc5.3) may be used
1388: in all cases instead of \&\fCrt\fR
1389: by spacing to the absolute place stored in a explicit register,
1390: e.g., using the sequence
1391: .CW ".mk
1392: @R@ ...\&
1393: .CW ".sp
1394: .CW |\en@R@u ;
1395: this also works when the motion is downwards.
1396: .NH
1397: Text Filling, Adjusting, and Centering
1398: .sc "Filling and adjusting.
1399: Normally,
1400: words are collected from input text lines
1401: and assembled into a output text line
1402: until some word does not fit.
1403: An attempt is then made
1404: to hyphenate the word to put part
1405: of it into the output line.
1406: The spaces between the words on the output line
1407: are then increased to spread out the line
1408: to the current \fIline length\fR
1409: minus any current \fIindent\fR.
1410: A \fIword\fR is any string of characters delimited by
1411: the \fIspace\fR character or the beginning/end of the input line.
1412: Any adjacent pair of words that must be kept together
1413: (neither split across output lines nor spread apart
1414: in the adjustment process)
1415: can be tied together by separating them with the
1416: \fIunpaddable space\fR character
1417: ``\&\fC\e\ \fR'' (backslash-space).
1418: The adjusted word spacings are uniform in \*(TR
1419: and the minimum interword spacing can be controlled
1420: with the \&\fCss\fR request (\(sc2).
1421: In \*(NR, they are normally nonuniform because of
1422: quantization to character-size spaces;
1423: however,
1424: the command line option \&\fC-e\fR causes uniform
1425: spacing with full output device resolution.
1426: Filling, adjustment, and hyphenation (\(sc13) can all be
1427: prevented or controlled.
1428: The text length on the last line output is available in the \&\fC.n\fR register,
1429: and text baseline position on the page for this line is in the \&\fCnl\fR register.
1430: The text baseline high-water mark (lowest place) on the current page is in
1431: the \&\fC.h\fR register.
1432: The current horizontal output position is in the \&\fC.k\fP register.
1433: .PP
1434: An input text line ending with \&\fC.\fR\^, \&\fC?\fR, or \&\fC!\fR,
1435: optionally followed by any number of
1436: .CW \&" ,
1437: .CW ' ,
1438: .CW ) ,
1439: .CW ] ,
1440: .CW * ,
1441: or
1442: \(dg,
1443: is taken
1444: to be the end of a sentence, and an additional space character is
1445: automatically provided during filling.
1446: To prevent this, add
1447: .CW \e&
1448: to the end of the input line.
1449: Multiple inter-word space characters found in the input are retained,
1450: except for trailing spaces;
1451: initial spaces also cause a break.
1452: .PP
1453: When filling is in effect, a \&\fC\ep\fR may be embedded or attached to a word to
1454: cause a break at the end of the word and have the resulting output
1455: line spread out to fill the current line length.
1456: .PP
1457: .tr &&
1458: A text input line that happens to begin
1459: with a control character can
1460: be made not to look like a control line
1461: by prefixing it with
1462: the non-printing, zero-width filler character \&\fC\e&\fR.
1463: Still another way is to specify output translation of some
1464: convenient character into the control character
1465: using \&\fCtr\fR (\(sc10.5).
1466: .tr &.
1467: .sc "Interrupted text.
1468: The copying of a input line in \fInofill\f (non-fill) mode can be interrupted
1469: by terminating
1470: the partial line with a \&\fC\ec\fR.
1471: The next encountered input text line will be considered to be a continuation
1472: of the same line of input text.
1473: Similarly,
1474: a word within \fIfilled\fR text may be interrupted by terminating the
1475: word (and line) with \&\fC\ec\fR;
1476: the next encountered text will be taken as a continuation of the
1477: interrupted word.
1478: If the intervening control lines cause a break,
1479: any partial line will be forced out along with any partial word.
1480: .bt "\&\fC.br\fR" "-" "-" "B" "Break.
1481: The filling of the line currently
1482: being collected is stopped and
1483: the line is output without adjustment.
1484: Text lines beginning with space characters
1485: (but not tabs)
1486: and empty text lines (blank lines) also cause a break.
1487: .bt "\&\fC.fi\fR" "fill on" - B,E "Fill subsequent output lines.
1488: The register \&\fC.u\fR is 1 in fill mode and 0 in nofill mode.
1489: .bt "\&\fC.nf\fR" "fill on" "-" "B,E" "Nofill.
1490: Subsequent output lines are neither filled nor adjusted.
1491: Input text lines are copied directly to output lines
1492: without regard for the current line length.
1493: .bt "\&\fC.ad\fI c\fR" "adj, both" "adjust" "E" "Line adjustment is begun.
1494: If fill mode is not on, adjustment will be deferred until
1495: fill mode is back on.
1496: If the type indicator @c@ is present,
1497: the adjustment type is changed as shown in the following table.
1498: .TS
1499: center box;
1500: c|c
1501: c|l.
1502: Indicator Adjust Type
1503: _
1504: \&\fCl\fR adjust left margin only
1505: \&\fCr\fR adjust right margin only
1506: \&\fCc\fR center
1507: \&\fCb\fR or \&\fCn\fR adjust both margins
1508: absent unchanged
1509: .TE
1510: The number register
1511: .CW .j
1512: contains the current value of the
1513: .CW ad
1514: setting;
1515: its value can be recorded and used subsequently to set adjustment.
1516: .bt "\&\fC.na\fR" "adjust" "-" "E" "Noadjust.
1517: Adjustment is turned off;
1518: the right margin will be ragged.
1519: The adjustment type for \&\fCad\fR is not changed.
1520: Output line filling still occurs if fill mode is on.
1521: .bt "\&\fC.ce\fI N\fR" "off" "@N=1@" "B,E" "Center the next @N@ input text lines
1522: within the current available horizontal space (line-length minus indent).
1523: If @N=0@, any residual count is cleared.
1524: A break occurs after each of the @N@ input lines.
1525: If the input line is too long,
1526: it will be left adjusted.
1527: .NH
1528: Vertical Spacing
1529: .sc "Baseline spacing.
1530: The vertical spacing @(V)@ between the baselines of successive
1531: output lines can be set
1532: using the \&\fCvs\fR request.
1533: \fIV\fR should be large enough to accommodate the character sizes
1534: on the affected output lines.
1535: For the common type sizes (9-12 points),
1536: usual typesetting practice is to set \fIV\fR to 2 points greater than the
1537: point size;
1538: \*(TR default is 10-point type on a 12-point spacing
1539: (as in this document).
1540: The current \fIV\fR is available in the \&\fC.v\fR register.
1541: Multiple-\fIV\|\fR line separation (e.g., double spacing) may be requested
1542: with \&\fCls\fR,
1543: but it is better to use a large
1544: .CW vs
1545: instead;
1546: certain preprocessors assume single spacing.
1547: The current line spacing is available in the \&\fC.L\fP register.
1548: .sc "Extra line-space.
1549: If a word contains a vertically tall construct requiring
1550: the output line containing it to have extra vertical space
1551: before and/or after it,
1552: the \fIextra-line-space\fR function \&\fC\ex'\fIN\fP'\fR
1553: can be embedded in or attached to that word.
1554: If @N@ is negative,
1555: the output line containing the word will
1556: be preceded by @N@ extra vertical space;
1557: if @N@ is positive,
1558: the output line containing the word
1559: will be followed by @N@ extra vertical space.
1560: If successive requests for extra space apply to the same line,
1561: the maximum values are used.
1562: The most recently utilized post-line extra line-space is available in the \&\fC.a\fR register.
1563: .PP
1564: In
1565: .CW \ex'\f2...\fP'
1566: and other functions having a pair of delimiters around
1567: their parameter,
1568: the delimiter choice (here
1569: .CW ' )
1570: is arbitrary,
1571: except that it can not look like the continuation of a number expression for @N@.
1572: .sc "Blocks of vertical space.
1573: A block of vertical space is ordinarily requested using \&\fCsp\fR,
1574: which honors the \fIno-space\fR mode and which does
1575: not space past a trap.
1576: A contiguous block of vertical space may be reserved using \&\fCsv\fR.
1577: .bt "\&\fC.vs \fIN\fR" "12pts; 1/6in" "previous" "E,\fBp\fR" "Set vertical baseline spacing size \fIV\fR.
1578: Transient extra vertical space is available with \&\fC\ex\fI'N\|\|'\fR (see above).
1579: .bt "\&\fC.ls \fIN\fR" "@N=1@" "previous" "E" "\fILine\fR spacing
1580: set to @+- N@.
1581: @N-1@ \fIV\fR\^s (blank lines) are
1582: appended to each output text line.
1583: Appended blank lines are omitted, if the text or previous appended blank line reached a trap position.
1584: .bt "\&\fC.sp \fIN\fR" "-" "@N=1~V@" "B,\fBv\fR" "Space vertically in either direction.
1585: If @N@ is negative, the motion is backward (upward)
1586: and is limited to the distance to the top of the page.
1587: Forward (downward) motion is truncated to the distance to the
1588: nearest trap.
1589: If the no-space mode is on,
1590: no spacing occurs (see \&\fCns\fR, and \&\fCrs\fR below).
1591: .bt "\&\fC.sv\fI N\fR" "-" "@N=1~V@" "\fBv\fR" "Save a contiguous vertical block of size @N@.
1592: If the distance to the next trap is greater
1593: than @N@, @N@ vertical space is output.
1594: No-space mode has no effect.
1595: If this distance is less than @N@,
1596: no vertical space is immediately output,
1597: but @N@ is remembered for later output (see \&\fCos\fR).
1598: Subsequent \&\fCsv\fR requests will overwrite any still remembered @N@.
1599: .bt "\&\fC.os\fR" "-" "-" "-" "Output saved vertical space.
1600: No-space mode has no effect.
1601: Used to finally output a block of vertical space requested
1602: by an earlier \&\fCsv\fR request.
1603: .bt "\&\fC.ns\fR" "space" "-" "D" "No-space mode turned on.
1604: When on, no-space mode inhibits \&\fCsp\fR requests and
1605: \&\fCbp\fR requests \fIwithout\fR a next page number.
1606: No-space mode is turned off when a line of
1607: output occurs, or with \&\fCrs\fR.
1608: .bt "\&\fC.rs\fR" "space" "-" "D" "Restore spacing.
1609: The no-space mode is turned off.
1610: .bt "\&Blank text line." "" "-" "B" "Causes a break and
1611: output of a blank line exactly like \&\fCsp 1\fR.
1612: .NH
1613: Line Length and Indenting
1614: .PP
1615: The maximum line length for fill mode may be set with \&\fCll\fR.
1616: The indent may be set with \&\fCin\fR;
1617: an indent applicable to only the next output line may be set with \&\fCti\fR.
1618: The line length includes indent space but not
1619: page offset space.
1620: The line length minus the indent is the basis for centering with \&\fCce\fR.
1621: The effect of \&\fCll\fR, \&\fCin\fR, or \&\fCti\fR
1622: is delayed, if a partially collected line exists,
1623: until after that line is output.
1624: In fill mode the length of text on an output line is less than or equal to
1625: the line length minus the indent.
1626: The current line length and indent are available in registers \&\fC.l\fR and \&\fC.i\fR respectively.
1627: The length of \fIthree-part titles\fR produced by \&\fCtl\fR
1628: (see \(sc14) is independently set by \&\fClt\fR.
1629: .bt "\&\fC.ll\fI \(+-N\fR" "6.5\|in" "previous" "E,\fBm\fR" "Line length is set to \(+-@N@.
1630: .bt "\&\fC.in\fI \(+-N\fR" "\fIN\(eq\^\fR0" "previous" "B,E,\fBm\fR" "Indent is set to @+- N@.
1631: The indent is prepended to each output line.
1632: .bt "\&\fC.ti\fI \(+-N\fR" "-" "ignored" "B,E,\fBm\fR" "Temporary indent.
1633: The next output text line will be indented a distance @+- N@
1634: with respect to the current indent.
1635: The resulting total indent may not be negative.
1636: The current indent is not changed.
1637: .NH
1638: Macros, Strings, Diversion, and Position Traps
1639: .sc "Macros and strings.
1640: A \fImacro\fR is a named set of arbitrary \fIlines\fR that may be invoked by name or
1641: with a \fItrap\fR.
1642: A \fIstring\fR is a named string of \fIcharacters\fR,
1643: not including a newline character,
1644: that may be interpolated by name at any point.
1645: Request, macro, and string names share the same name list.
1646: Macro and string names
1647: may be one or two characters long and may usurp previously defined
1648: request, macro, or string names;
1649: this implies that built-in operations may be (irrevocably) redefined.
1650: Any of these entities may be renamed with \&\fCrn\fR
1651: or removed with \&\fCrm\fR.
1652: .PP
1653: Macros are created by \&\fCde\fR and \&\fCdi\fR, and appended to by \&\fCam\fR and \&\fCda\fR;
1654: \&\fCdi\fR and \&\fCda\fR cause normal output to be stored in a macro.
1655: A macro is invoked in the same way as a request;
1656: a control line beginning \&\fC.\fIxx\fR will interpolate the contents of macro \fIxx\fR.
1657: The remainder of the line may contain up to nine \fIarguments\fR.
1658: .PP
1659: Strings are created by \&\fCds\fR and appended to by \&\fCas\fR.
1660: The strings \fIx\fR and \fIxx\fR are interpolated at any desired point with
1661: \&\fC\e\(**\fIx\fR and \&\fC\e\(**(\fIxx\fR respectively.
1662: String references and macro invocations may be nested.
1663: .sc "Copy mode input interpretation.
1664: During the definition and extension
1665: of strings and macros (not by diversion)
1666: the input is read in \fIcopy mode\fR.
1667: In copy mode, input is copied without interpretation
1668: except that:
1669: .IP
1670: .ds + \v'-.1m'\s-4\(bu\s+4\v'+.1m'
1671: .nf
1672: \*+ The contents of number registers indicated by \&\fC\en\fR are interpolated.
1673: \*+ Strings indicated by \&\fC\e\(**\fR are interpolated.
1674: \*+ Arguments indicated by \&\fC\e$\fR are interpolated.
1675: \*+ Concealed newlines indicated by \&\fC\e\fP\f2newline\fP are eliminated.
1676: \*+ Comments indicated by \&\fC\e"\fR are eliminated.
1677: \*+ \&\fC\et\fR and \&\fC\ea\fR are interpreted as \s-1ASCII\s+1 horizontal tab and \s-1SOH\s+1 respectively (\(sc9).
1678: \*+ \&\fC\e\e\fR is interpreted as \&\fC\e\fR.
1679: \*+ \&\fC\e.\fR is interpreted as ``\&\fC.\fR''.
1680: .LP
1681: These interpretations can be suppressed by
1682: prepending
1683: a \&\fC\e\fR.
1684: For example, since \&\fC\e\e\fR maps into a \&\fC\e\fR, \&\fC\e\en\fR will copy as \&\fC\en\fR, which
1685: will be interpreted as a number register indicator when the
1686: macro or string is reread.
1687: .sc "Arguments.
1688: When a macro is invoked by name, the remainder of the line is
1689: taken to contain up to nine arguments.
1690: The argument separator is the space character (not tab), and arguments
1691: may be surrounded by double quotes to permit embedded space characters.
1692: Pairs of double quotes may be embedded in double-quoted arguments to
1693: represent a single double-quote character.
1694: The argument
1695: .CW \&""
1696: is explicitly null.
1697: If the desired arguments won't fit on a line,
1698: a concealed newline may be used to continue on the next line.
1699: A trailing double quote may be omitted.
1700: .PP
1701: When a macro is invoked the \fIinput level\fR is \fIpushed down\fR and
1702: any arguments available at the previous level become unavailable
1703: until the macro is completely read and the previous level is restored.
1704: A macro's own arguments can be interpolated at any point
1705: within the macro with
1706: .CW \e$@N@ ,
1707: which interpolates the @N@\^th
1708: argument
1709: (1\(<=@N@\^\(<=9).
1710: If an invoked argument does not exist,
1711: a null string results.
1712: For example, the macro \fIxx\fR may be defined by
1713: .P1
1714: .ta .75i
1715: &de xx \e" begin definition
1716: Today is \e\e$1 the \e\e$2.
1717: &. \e" end definition
1718: .P2
1719: and called by
1720: .P1
1721: &xx Monday 14th
1722: .P2
1723: to produce the text
1724: .P1
1725: Today is Monday the 14th.
1726: .P2
1727: Note that each \&\fC\e$\fR
1728: was concealed in the definition with a prepended \&\fC\e\fR.
1729: The number of
1730: arguments is in the \&\fC.$\fR register.
1731: .PP
1732: No arguments are available at the top (non-macro) level,
1733: within a string, or within a trap-invoked macro.
1734: .PP
1735: Arguments are copied in copy mode onto a stack
1736: where they are available for reference.
1737: It is advisable to
1738: conceal string references (with an extra \&\fC\e\fR\|)
1739: to delay interpolation until argument reference time.
1740: .sc "Diversions.
1741: Processed output may be diverted into a macro for purposes
1742: such as footnote processing (see Tutorial \(scT5)
1743: or determining the horizontal and vertical size of some text for
1744: conditional changing of pages or columns.
1745: A single diversion trap may be set at a specified vertical position.
1746: The number registers \&\fCdn\fR and \&\fCdl\fR respectively contain the
1747: vertical and horizontal size of the most
1748: recently ended diversion.
1749: Processed text that is diverted into a macro
1750: retains the vertical size of each of its lines when reread
1751: in \fInofill\fR mode
1752: regardless of the current \fIV\fR.
1753: Constant-spaced (\&\fCcs\fR) or emboldened (\&\fCbd\fR) text that is diverted
1754: can be reread correctly only if these modes are again or still in effect
1755: at reread time.
1756: One way to do this is to embed in the diversion the appropriate
1757: \&\fCcs\fR or \&\fCbd\fR requests with the \fItransparent\fR
1758: mechanism described in \(sc10.6.
1759: .PP
1760: Diversions may be nested
1761: and certain parameters and registers
1762: are associated
1763: with the current diversion level
1764: (the top non-diversion level may be thought of as the
1765: 0th diversion level).
1766: These are the diversion trap and associated macro,
1767: no-space mode,
1768: the internally-saved marked place (see \&\fCmk\fR and \&\fCrt\fR),
1769: the current vertical place (\&\fC.d\fR register),
1770: the current high-water text baseline (\&\fC.h\fR register),
1771: and the current diversion name (\&\fC.z\fR register).
1772: .sc "Traps.
1773: Three types of trap mechanisms are available\(empage traps, a diversion trap, and
1774: an input-line-count trap.
1775: Macro-invocation traps may be planted using \&\fCwh\fR at any page position including the top.
1776: This trap position may be changed using \&\fCch\fR.
1777: Trap positions at or below the bottom of the page
1778: have no effect unless or until
1779: moved to within the page or rendered effective by an increase in page length.
1780: Two traps may be planted at the same position only by first planting them at different
1781: positions and then moving one of the traps;
1782: the first planted trap will conceal the second unless and until the first one is moved
1783: (see Tutorial Examples).
1784: If the first one is moved back, it again conceals the second trap.
1785: The macro associated with a page trap is automatically
1786: invoked when a line of text is output whose vertical size reaches
1787: or sweeps past the trap position.
1788: Reaching the bottom of a page springs the top-of-page trap, if any,
1789: provided there is a next page.
1790: The distance to the next trap position is available in the \&\fC.t\fR register;
1791: if there are no traps between the current position and the bottom of the page,
1792: the distance returned is the distance to the page bottom.
1793: .PP
1794: A macro-invocation trap effective in the current diversion may be planted using \&\fCdt\fR.
1795: The \&\fC.t\fR register works in a diversion; if there is no subsequent trap a large
1796: distance is returned.
1797: For a description of input-line-count traps, see \&\fCit\fR below.
1798: .bt "\&\fC&de\fI xx yy\fR" "-" "\fI.yy=\&\fC..\fR" "-" "Define or redefine the macro \fIxx\fR.
1799: The contents of the macro begin on the next input line.
1800: Input lines are copied in \fIcopy mode\fR until the definition is terminated by a
1801: line beginning with \&\fC.\fIyy\fR,
1802: whereupon the macro \fIyy\fR is called.
1803: In the absence of \fIyy\fR, the definition
1804: is terminated by a
1805: line beginning with ``\&\fC..\fR''.
1806: A macro may contain \&\fCde\fR requests
1807: provided the terminating macros differ
1808: or the contained definition terminator is concealed.
1809: \&``\&\fC..\fR'' can be concealed as
1810: \&\fC\e\e..\fR which will copy as \&\fC\e..\fR and be reread as ``\&\fC..\fR''.
1811: .bt "\&\fC&am\fI xx yy\fR" "-" "\fI.yy=\&\fC..\fR" "-" "Append to macro
1812: .I xx
1813: (append version of \&\fCde\fR).
1814: .bt "\&\fC&ds\fI xx string\fR" "-" "ignored" "-" "Define a string
1815: \fIxx\fR containing \fIstring\fR.
1816: Any initial double quote in \fIstring\fR is stripped off to permit
1817: initial blanks.
1818: .bt "\&\fC&as\fI xx string\fR" "-" "ignored" "-" "Append
1819: \fIstring\fR to string \fIxx\fR
1820: (append version of \&\fCds\fR).
1821: .bt "\&\fC&rm\fI xx\fR" "-" "ignored" "-" "Remove
1822: request, macro, or string.
1823: The name \fIxx\fR is removed from the name list and
1824: any related storage space is freed.
1825: Subsequent references will have no effect.
1826: If many macros and strings are being created dynamically, it
1827: may become necessary to remove unused ones
1828: to recapture internal storage space for newer registers.
1829: .bt "\&\fC&rn\fI xx yy\fR" "-" "ignored" "-" "Rename request, macro, or string
1830: \fIxx\fR to \fIyy\fR.
1831: If \fIyy\fR exists, it is first removed.
1832: .bt "\&\fC&di\fI xx\fR" "-" "end" "D" "Divert output to macro \fIxx\fR.
1833: Normal text processing occurs during diversion
1834: except that page offsetting is not done.
1835: The diversion ends when the request \&\fCdi\fR or \&\fCda\fR is encountered without an argument;
1836: extraneous
1837: requests of this type should not appear when nested diversions are being used.
1838: .bt "\&\fC&da \fIxx\fR" "-" "end" "D" "Divert, appending to macro \fIxx\fR
1839: (append version of \&\fCdi\fR).
1840: .bt "\&\fC&wh\fI N xx\fR" "-" "-" "\fBv\fR" "Install
1841: a trap to invoke \fIxx\fR at page position \fIN\fR;
1842: a negative N will be interpreted as a distance from the
1843: page bottom.
1844: Any macro previously planted at @N@ is replaced by \fIxx\fR.
1845: A zero @N@ refers to the top of a page.
1846: In the absence of \fIxx\fR, the first trap found at @N@, if any, is removed.
1847: .bt "\&\fC&ch\fI xx N\fR" "-" "-" "\fBv\fR" "Change
1848: the trap position for macro \fIxx\fR to be @N@.
1849: In the absence of @N@, the trap, if any, is removed.
1850: .bt "\&\fC&dt\fI N xx\fR" "-" "off" "D,\fBv\fR" "Install a diversion trap
1851: at position @N@ in the \fIcurrent\fR diversion to invoke
1852: macro \fIxx\fR.
1853: Another \&\fCdt\fR will redefine the diversion trap.
1854: If no arguments are given, the diversion trap is removed.
1855: .bt "\&\fC&it\fI N xx\fR" "-" "off" "E" "Set an input-line-count trap
1856: to invoke the macro \fIxx\fR after @N@ lines of \fItext\fR input
1857: have been read
1858: (control or request lines do not count).
1859: The text may be inline text or
1860: text interpolated by inline or trap-invoked macros.
1861: .bt "\&\fC&em\fI xx\fR" "none" "none" "-" "The
1862: macro \fIxx\fR will be invoked
1863: when all input has ended.
1864: The effect is almost as if the contents of \fIxx\fR had been at the end
1865: of the last file processed,
1866: but all processing ceases at the next page eject.
1867: .NH
1868: Number Registers
1869: .PP
1870: A variety of parameters are available to the user as
1871: predefined \fInumber registers\fR (see Summary, page \n(*%).
1872: In addition, users may define their own registers.
1873: Register names are one or two characters long and do not conflict
1874: with request, macro, or string names.
1875: Except for certain predefined read-only registers,
1876: a number register can be read, written, automatically
1877: incremented or decremented, and interpolated
1878: into the input in a variety of formats.
1879: One common use of user-defined registers is to
1880: automatically number sections, paragraphs, lines, etc.
1881: A number register may be used any time numerical input is expected or desired
1882: and may be used in numerical \fIexpressions\fR (\(sc1.4).
1883: .PP
1884: Number registers are created and modified using \&\fCnr\fR, which
1885: specifies the name, numerical value, and the auto-increment size.
1886: Registers are also modified, if accessed
1887: with an auto-incrementing sequence.
1888: If the registers \fIx\fR and \fIxx\fR both contain
1889: @N@ and have the auto-increment size @M@,
1890: the following access sequences have the effect shown:
1891: .TS
1892: center box;
1893: c2|c2|c
1894: c2|c2|c2
1895: l2|c2|c2
1896: l2|c2|c2
1897: l2|l2|c2.
1898: Effect on Value
1899: Sequence Register Interpolated
1900: _
1901: \&\fC\en\fIx\fR none @N@
1902: \&\fC\en(\fIxx\fR none @N@
1903: \&\fC\en+\fIx\fR \fIx\fR incremented by @M@ \fIN+M\fR
1904: \&\fC\en\-\fIx\fR \fIx\fR decremented by @M@ \fIN\-M\fR
1905: \&\fC\en+(\fIxx\fR \fIxx\fR incremented by @M@ \fIN+M\fR
1906: \&\fC\en\-(\fIxx\fR \fIxx\fR decremented by @M@ \fIN\-M\fR
1907: .TE
1908: When interpolated, a number register is converted to
1909: decimal (default),
1910: decimal with leading zeros,
1911: lower-case Roman,
1912: upper-case Roman,
1913: lower-case sequential alphabetic,
1914: or
1915: upper-case sequential alphabetic
1916: according to the format specified by \&\fCaf\fR.
1917: .bt "\&\fC&nr\fI R \(+-N M\fR" "" "-" "\fBu\fR" "The number register
1918: @R@ is assigned the value @+- N@
1919: with respect to the previous value, if any.
1920: The increment for auto-incrementing is set to @M@.
1921: .bt "\&\fC&af\fI R c\fR" "arabic" "-" "-" "Assign
1922: format @c@ to register @R@.
1923: The available formats are:
1924: .Tm number register format s
1925: .TS
1926: center box;
1927: c2|c
1928: c2|c
1929: c2|l.
1930: Numbering
1931: Format Sequence
1932: _
1933: \&\fC1\fR 0, 1, 2, 3, 4, 5, ...
1934: \&\fC001\fR 000, 001, 002, 003, 004, 005, ...
1935: \&\fCi\fR 0, i, ii, iii, iv, v, ...
1936: \&\fCI\fR 0, I, II, III, IV, V, ...
1937: \&\fCa\fR 0, a, b, c, ..., z, aa, ab, ..., zz, aaa, ...
1938: \&\fCA\fR 0, A, B, C, ..., Z, AA, AB, ..., ZZ, AAA, ...
1939: .TE
1940: An arabic format having @N@ digits
1941: specifies a field width of @N@ digits (example 2 above).
1942: The read-only registers and the width function
1943: .CW \ew
1944: (\(sc11.2)
1945: are always arabic.
1946: Warning: the value of a number register in a non-arabic format
1947: is not numeric, and will not produce the expected results in expressions.
1948: .IP
1949: The function
1950: .CW \eg@x@
1951: or
1952: .CW \eg(@xx@
1953: returns the format of a number register in a form suitable for
1954: .CW af ;
1955: it returns nothing if the register has not been used.
1956: .bt "\&\fC&rr\fI R\fR" "-" "ignored" "-" "Remove number register @R@.
1957: If many registers are being created dynamically, it
1958: may become necessary to remove unused registers
1959: to recapture internal storage space for newer registers.
1960: The register
1961: .CW .R
1962: contains the number of number registers still available.
1963: .NH
1964: Tabs, Leaders, and Fields
1965: .sc "Tabs and leaders.
1966: The \s-1ASCII\s+1 horizontal tab character and the \s-1ASCII\s+1
1967: \s-1SOH\s+1 (control-A, hereafter called the \fIleader\fR character)
1968: can both be used to generate either horizontal motion or
1969: a string of repeated characters.
1970: The length of the generated entity is governed
1971: by internal \fItab stops\fR specifiable
1972: with \&\fCta\fR.
1973: The default difference is that tabs generate motion and leaders generate
1974: a string of periods;
1975: \&\fCtc\fR and \&\fClc\fR
1976: offer the choice of repeated character or motion.
1977: There are three types of internal tab stops\(em\
1978: \fIleft\fR adjusting, \fIright\fR adjusting,
1979: and \fIcentering\fR.
1980: In the following table,
1981: \fID\fR is the distance from the current position on the \fIinput\fR line
1982: (where a tab or leader was found)
1983: to the next tab stop,
1984: \fInext-string\fR consists
1985: of the input characters following the tab (or leader) up to the next tab (or leader) or end of line,
1986: and
1987: \fIW\fR is the width of \fInext-string\fR.
1988: .TS
1989: center box;
1990: c2|c2|c
1991: c2|c2|c
1992: c2|c2|l.
1993: Tab Length of motion or Location of
1994: type repeated characters \fInext-string\fR
1995: _
1996: Left \fID\fR Following \fID\fR
1997: Right \fID\-W\fR Right adjusted within \fID\fR
1998: Centered \fID\-W/\fR2 Centered on right end of \fID\fR
1999: .TE
2000: The length of generated motion is allowed to be negative, but
2001: that of a repeated character string cannot be.
2002: Repeated character strings contain an integer number of characters, and
2003: any residual distance is prepended as motion.
2004: Tabs or leaders found after the last tab stop are ignored, but may be used
2005: as \fInext-string\fR terminators.
2006: .PP
2007: Tabs and leaders are not interpreted in copy mode.
2008: \&\fC\et\fR and \&\fC\ea\fR always generate a non-interpreted
2009: tab and leader respectively, and
2010: are equivalent to actual tabs and leaders in copy mode.
2011: .sc "Fields.
2012: A \fIfield\fR is contained between
2013: a pair of \fIfield delimiter\fR characters,
2014: and consists of sub-strings
2015: separated by \fIpadding\fR indicator characters.
2016: The field length is the distance on the
2017: \fIinput\fR line from the position where the field begins to the next tab stop.
2018: The difference between the total length of all the sub-strings
2019: and the field length is incorporated as horizontal
2020: padding space that is divided among the indicated
2021: padding places.
2022: The incorporated padding is allowed to be negative.
2023: For example,
2024: if the field delimiter is \&\fC#\fR and the padding indicator is \&\fC^\fR,
2025: \&\fC#^\fIxxx\&\fC^\fIright\|\&\fC#\fR
2026: specifies a right-adjusted string with the string \fIxxx\fR centered
2027: in the remaining space.
2028: .h1
2029: .bt "\&\fC&ta\fI Nt ...\fR" "0.8; 0.5in" "none" "E,\fBm\fR" "Set tab stops and types.
2030: \fIt=\&\fCR\fR, right adjusting;
2031: \fIt=\&\fCC\fR, centering;
2032: \fIt\fR absent, left adjusting.
2033: \*(Tr tab stops are preset every 0.5in.,
2034: \*(NR every 0.8in.
2035: The stop values are separated by spaces, and
2036: a value preceded by \&\fC+\fR
2037: is treated as an increment to the previous stop value.
2038: .bt "\&\fC&tc\fI c\fR" "none" "none" "E" "The tab repetition character
2039: becomes @c@,
2040: or is removed, thus specifying motion.
2041: .bt "\&\fC&lc\fI c\fR" "\&\fC.\fR" "none" "E" "The leader repetition character
2042: becomes @c@,
2043: or is removed, thus specifying motion.
2044: .bt "\&\fC&fc\fI a b\fR" "off" "off" "-" "The field delimiter
2045: is set to \fIa\fR;
2046: the padding indicator is set to the space character or to
2047: \fIb\fR, if given.
2048: In the absence of arguments the field mechanism is turned off.
2049: .NH
2050: Input and Output Conventions and Character Translations
2051: .sc "Input character translations.
2052: Ways of inputting the valid character set were
2053: discussed in \(sc2.1.
2054: The \s-1ASCII\s+1 control characters horizontal tab (\(sc9.1),
2055: \s-1SOH\s+1 (\(sc9.1), and backspace (\(sc10.3) are discussed elsewhere.
2056: The newline delimits input lines.
2057: In addition,
2058: \s-1STX\s+1, \s-1ETX\s+1, \s-1ENQ\s+1, \s-1ACK\s+1, and \s-1BEL\s+1
2059: are accepted,
2060: and may be used as delimiters or translated into a graphic with \&\fCtr\fR (\(sc10.5).
2061: All others are ignored.
2062: .PP
2063: The \fIescape\fR character \&\fC\e\fR
2064: introduces \fIescape sequences\fR,
2065: which cause the following character to mean
2066: another character, or to indicate
2067: some function.
2068: .nr %% \n(*%-1
2069: A complete list of such sequences is given in the Summary on page \n(%%.
2070: The escape character \&\fC\e\fR
2071: should not be confused with the \s-1ASCII\s+1 control character \s-1ESC\s+1.
2072: The escape character \&\fC\e\fR can be input with the sequence \&\fC\e\e\fR.
2073: The escape character can be changed with \&\fCec\fR,
2074: and all that has been said about the default \&\fC\e\fR becomes true
2075: for the new escape character.
2076: \&\fC\ee\fR can be used to print whatever the current escape character is.
2077: The escape mechanism may be turned off with \&\fCeo\fR,
2078: and restored with \&\fCec\fR.
2079: .h1
2080: .bt "\&\fC&ec\fI c\fR" "\&\fC\e\fR" "\&\fC\e\fR" "-" "Set escape character
2081: to \&\fC\e\fR, or to @c@, if given.
2082: .bt "\&\fC&eo\fR" "on" "-" "-" "Turn escape mechanism off.
2083: .sc "Ligatures.
2084: .lg0
2085: The set of available ligatures is device and font dependent,
2086: but is often a subset of
2087: \&\fC\(fi\fR, \&\fC\(fl\fR, \&\fC\(ff\fR, \&\fC\(Fi\fR, and \&\fC\(Fl\fR.
2088: They may be input by
2089: \&\fC\e(fi\fR, \&\fC\e(fl\fR, \&\fC\e(ff\fR, \&\fC\e(Fi\fR, and \&\fC\e(Fl\fR respectively.
2090: .lg
2091: The ligature mode is normally on in \*(TR, and automatically invokes
2092: ligatures during input.
2093: .h1
2094: .bt "\&\fC&lg\fI N\fR" "on; off" "on" "-" "Ligature mode
2095: is turned on if @N@ is absent or non-zero,
2096: and turned off if @N=0@.
2097: If @N=2@, only the two-character ligatures are automatically invoked.
2098: Ligature mode is inhibited for
2099: request, macro, string, register, or file names,
2100: and in copy mode.
2101: No effect in \*(NR.
2102: .sc "Backspacing, underlining, overstriking, etc.
2103: Unless in copy mode, the \s-1ASCII\s+1 backspace character is replaced
2104: by a backward horizontal motion having the width of the
2105: space character.
2106: Underlining as a form of line-drawing is discussed in \(sc12.4.
2107: A generalized overstriking function is described in \(sc12.1.
2108: .PP
2109: \*(Nr automatically underlines
2110: characters in the \fIunderline\fR font,
2111: specifiable with \&\fCuf\fR,
2112: normally that on font position 2.
2113: In addition to \&\fCft\fR and
2114: .CW \ef@F@ ,
2115: the underline font may be selected by \&\fCul\fR and \&\fCcu\fR.
2116: Underlining is restricted to an output-device-dependent
2117: subset of reasonable characters.
2118: .bt "\&\fC&ul\fI N\fR" "off" "@N=1@" "E" "Italicize in \*(TR
2119: (underline in \*(NR) the next @N@
2120: input text lines.
2121: Actually, switch to underline font, saving the
2122: current font for later restoration;
2123: other font changes within the span of a \&\fCul\fR
2124: will take effect,
2125: but the restoration will undo the last change.
2126: Output generated by \&\fCtl\fR (\(sc14) is affected by the
2127: font change, but does not decrement @N@.
2128: If @N>1@, there is the risk that
2129: a trap interpolated macro may provide text
2130: lines within the span;
2131: environment switching can prevent this.
2132: .bt "\&\fC&cu\fI N\fR" "off" "@N=1@" "E" "Continuous underline.
2133: A variant
2134: of \&\fCul\fR that causes \fIevery\fR character to be underlined in \*(NR.
2135: Identical to \&\fCul\fR in \*(TR.
2136: .bt "\&\fC&uf\fI F\fR" "Italic" "Italic" "-" "Underline font set to @F@.
2137: In \*(NR,
2138: @F@ may not be on position 1.
2139: .sc "Control characters.
2140: Both the control character \&\fC.\fR and the \fIno-break\fR
2141: control character \&\fC'\fR may be changed.
2142: Such a change must be compatible with the design
2143: of any macros used in the span of the change,
2144: and
2145: particularly of any trap-invoked macros.
2146: .bt "\&\fC&cc\fI c\fR" "\&\fC.\fR" "\&\fC.\fR" "E" "The basic control character
2147: is set to @c@,
2148: or reset to ``\&\fC.\fR''.
2149: .bt "\&\fC&c2\fI c\fR" "\&\fC'" "'\fR" "E" "The \fIno-break\fR control character is set
2150: to @c@, or reset to ``\&\fC'\fR''.
2151: .sc "Output translation.
2152: One character can be made a stand-in for another character using \&\fCtr\fR.
2153: All text processing (e.g., character comparisons) takes place
2154: with the input (stand-in) character which appears to have the width of the final
2155: character.
2156: The graphic translation occurs at the moment of output
2157: (including diversion).
2158: .bt "\&\fC&tr\fI abcd....\fR" "none" "-" "O" "Translate
2159: \fIa\fR into \fIb\fR, @c@ into \fId\fR, etc.
2160: If an odd number of characters is given,
2161: the last one will be mapped into the space character.
2162: To be consistent, a particular translation
2163: must stay in effect from \fIinput\fR to \fIoutput\fR time.
2164: .sc "Transparent throughput.
2165: An input line beginning with a \&\fC\e!\fR is read in copy mode and \fItrans\%parently\fR output
2166: (without the initial \&\fC\e!\fR);
2167: the text processor is otherwise unaware of the line's presence.
2168: This mechanism may be used to pass control information to a post-processor
2169: or to embed control lines in a macro created by a diversion.
2170: .sc "Transparent output
2171: The sequence
2172: .CW \eX'@anything@'
2173: copies
2174: .I anything
2175: to the output, as a device control function of the form
2176: .CW x
2177: .CW X
2178: .I anything
2179: (\(sc22).
2180: Escape sequences in
2181: .I anything
2182: are processed.
2183: .sc "Comments and concealed newlines.
2184: An uncomfortably long input line that must stay
2185: one line (e.g., a string definition, or nofilled text)
2186: can be split into several physical lines by ending all but
2187: the last one with the escape \&\fC\e\fR.
2188: The sequence \&\fC\e\fR@newline@ is always ignored,
2189: except in a comment.
2190: Comments may be embedded at the end of any line by
2191: prefacing them with \&\fC\e"\fR.
2192: The newline at the end of a comment cannot be concealed.
2193: A line beginning with \&\fC\e"\fR will appear as a blank line and
2194: behave like
2195: .CW ".sp\ 1" ;
2196: a comment can be on a line by itself by beginning the line with \&\fC.\e"\fR.
2197: .NH
2198: Local Horizontal and Vertical Motions, and the Width Function
2199: .sc "Local Motions.
2200: The functions \&\fC\ev'\fIN\&\fC'\fR and
2201: \&\fC\eh'\fIN\&\fC'\fR
2202: can be used for \fIlocal\fR vertical and horizontal motion respectively.
2203: The distance @N@ may be negative; the positive directions
2204: are rightward and downward.
2205: A local motion is one contained within a line.
2206: To avoid unexpected vertical dislocations, it is necessary that
2207: the net vertical local motion within a word in filled text
2208: and otherwise within a line balance to zero.
2209: The above and certain other escape sequences providing local motion are
2210: summarized in the following table.
2211: .ds Y \0\0\0
2212: .TS
2213: center box;
2214: c2|cs2||c2|cs2
2215: c1|c2c2||c2|c2c2.
2216: Vertical Effect in Horizontal Effect in
2217: Local Motion \*(TR \*(NR Local Motion \*(TR \*(NR
2218: _
2219: .sp.4
2220: .TC
2221: l2|ls2||l2|ls2.
2222: \&\fC\*Y\ev'\fIN\|\fC'\fR Move distance @N@ \
2223: \&\fC\*Y\eh'\fIN\|\fC'\fR Move distance @N@
2224: .TC
2225: _2|_2_2||l2|ls2.
2226: x x x \&\fC\*Y\e\fP\f2space\fP Unpaddable space-size space
2227: .TC
2228: l2|l2|l2||l2|ls2.
2229: \&\fC\*Y\eu\fR \(12 em up \(12 line up \&\fC\*Y\e0\fR Digit-size space
2230: .TC
2231: l2|l2|l2||_2|_2_2.
2232: \&\fC\*Y\ed\fR \(12 em down \(12 line down x x x
2233: .TC
2234: l2|l2|l2||l2|l2|l2.
2235: \&\fC\*Y\er\fR 1 em up 1 line up \&\fC\*Y\e|\fR 1/6 em space ignored
2236: \&\fC\*Y\e^\fR 1/12 em space ignored
2237: .sp.4
2238: .TE
2239: As an example,
2240: \&\fCE\s-2\v'-.4m'2\v'.4m'\s+2\fR
2241: could be generated by the sequence
2242: \&\fCE\es\-2\ev'\-0.4m'2\ev'0.4m'\es+2\fR;
2243: note that
2244: the 0.4 em vertical motions are at the smaller size.
2245: .sc "Width Function.
2246: The \fIwidth\fR function \&\fC\ew'\fIstring\&\fC'\fR
2247: generates the numerical width of \fIstring\fR (in basic units).
2248: Size and font changes may be embedded in \fIstring\fR,
2249: and will not affect the current environment.
2250: For example,
2251: \&\&\fC.ti\ \-\ew'\efB1.\ 'u\fR could be used to
2252: temporarily indent leftward a distance equal to the
2253: size of the string ``\&\fC1.\ \fR'' in font
2254: .CW B .
2255: .PP
2256: The width function also sets three number registers.
2257: The registers \&\fCst\fR and \&\fCsb\fR are set respectively to the highest and
2258: lowest extent of \fIstring\fR relative to the baseline;
2259: then, for example,
2260: the total height of the string is \&\fC\en(stu\-\en(sbu\fR.
2261: In \*(TR the number register \&\fCct\fR is set to a value
2262: between 0 and 3.
2263: The value
2264: 0 means that all of the characters in \fIstring\fR were short lower
2265: case characters without descenders (like \&\fCe\fR);
2266: 1 means that at least one character has a descender (like \&\fCy\fR);
2267: 2 means that at least one character is tall (like \&\fCH\fR);
2268: and 3 means that both tall characters and characters with
2269: descenders are present.
2270: .sc "Mark horizontal place.
2271: The function \&\fC\ek\fIx\fR causes the current horizontal
2272: position in the \fIinput line\fR to be stored in register \fIx\fR.
2273: For example,
2274: the construction \&\fC\ekx\fIword\fC\eh'|\enxu+3u'\fIword\&\fC\fR
2275: will embolden \fIword\fR by backing up to almost its beginning and overprinting it,
2276: resulting in \kz\fIword\fR\h'|\nzu+3u'\fIword\fR.
2277: .NH
2278: Overstrike, Bracket, Line-drawing, Graphics, and Zero-width Functions
2279: .sc "Overstriking.
2280: Automatically centered overstriking of up to nine characters
2281: is provided by the \fIoverstrike\fR function
2282: \&\fC\eo'\fIstring\&\fC\|'\fR.
2283: The characters in \fIstring\fR are overprinted with centers aligned; the total width
2284: is that of the widest character.
2285: \fIstring\fR may not contain local vertical motion.
2286: As examples,
2287: \&\fC\eo'e\e''\fR produces \o'e\'', and
2288: \&\fC\eo'\e(mo\e(sl'\fR produces \o'\(mo\(sl'.
2289: .sc "Zero-width characters.
2290: The function
2291: .CW \ez@c@
2292: will output @c@ without spacing over
2293: it, and can be used to produce left-aligned overstruck
2294: combinations.
2295: As examples,
2296: \&\fC\ez\e(ci\e(pl\fR will produce \&\fC\z\(ci\(pl\fR, and
2297: \&\fC\e(br\ez\e(rn\e(ul\e(br\fR will produce a small
2298: constructed box \&\fC\(br\z\(rn\(ul\(br\fR\|.
2299: .sc "Large Brackets.
2300: The Special Font usually contains a number of bracket construction pieces
2301: \|\|\(lt\|\|\(lb\|\|\(rt\|\|\(rb\|\|\(lk\|\|\(rk\|\|\(bv\|\|\(lf\|\|\(rf\|\|\(lc\|\|\(rc\|\|
2302: that can be combined into various bracket styles.
2303: The function \&\fC\eb'\fIstring\&\fC\|'\fR may be used to pile
2304: up vertically the characters in \fIstring\fR
2305: (the first character on top and the last at the bottom);
2306: the characters are vertically separated by 1 em and the total
2307: pile is centered 1/2 em above the current baseline
2308: (\(12 line in \*(NR).
2309: For example,
2310: .P1
2311: \eb'\e(lc\e(lf'E\eb'\e(rc\e(rf'\ex'\-0.5m'\ex'0.5m'
2312: .P2
2313: produces
2314: \x'-.5m'\x'.5m'\b'\(lc\(lf'E\b'\(rc\(rf'.
2315: .sc "Line drawing.
2316: .tr &&
2317: The function \&\fC\el'\fINc\fC'\fR (backslash-ell) draws a string of repeated @c@'s towards the right for a distance @N@.
2318: If @c@ looks like a continuation of
2319: an expression for @N@, it may be insulated from @N@ with a \&\fC\e&\fR.
2320: If @c@ is not specified, the \&\fC\(ru\fR (baseline rule) is used
2321: (underline character in \*(NR).
2322: If @N@ is negative, a backward horizontal motion
2323: of size @N@ is made before drawing the string.
2324: Any space resulting from @N@/(size of @c@) having a remainder is put at the beginning (left end)
2325: of the string.
2326: If @N@ is less than the width of @c@,
2327: a single @c@ is centered on a distance @N@.
2328: In the case of characters
2329: that are designed to be connected, such as
2330: baseline-rule\ \&\fC\(ru\fR\|,
2331: under-rule\ \&\fC\(ul\fR\|,
2332: and
2333: root-en\ \&\fC\(rn\fR\|,
2334: the remainder space is covered by overlapping.
2335: As an example, a macro to underscore a string can be written
2336: .tr &.
2337: .P1
2338: .ne 2.1
2339: &de us
2340: \e\e$1\e\|l\|'|0\e(ul'
2341: &&
2342: .P2
2343: .ne2.1
2344: .de xu
2345: \\$1\l'|0\(ul'
2346: ..
2347: or one to draw a box around a string
2348: .P1
2349: &de bx
2350: \e(br\e|\e\e$1\e|\e(br\e\|l\|'|0\e(rn'\e\|l\|'|0\e(ul'
2351: &&
2352: .P2
2353: .de bx
2354: \(br\|\\$1\|\(br\l'|0\(rn'\l'|0\(ul'
2355: ..
2356: such that
2357: .P1
2358: &ul "underlined words"
2359: .P2
2360: and
2361: .P1
2362: &bx "words in a box"
2363: .P2
2364: yield
2365: .xu "underlined words"
2366: and
2367: .bx "words in a box"
2368: \h'-\w'.'u'.
2369: .PP
2370: The function \&\fC\eL'\fINc\&\fC'\fR draws a vertical line consisting
2371: of the (optional) character @c@ stacked vertically apart 1\|em
2372: (1 line in \*(NR),
2373: with the first two characters overlapped,
2374: if necessary, to form a continuous line.
2375: The default character is the \fIbox rule\fR \|\(br\| (\&\fC\|\e(br\fR);
2376: the other suitable character is the \fIbold vertical\fR \|\(bv\| (\&\fC\|\e(bv\fR).
2377: The line is begun without any initial motion relative to the
2378: current baseline.
2379: A positive @N@ specifies a line drawn downward and
2380: a negative @N@ specifies a line drawn upward.
2381: After the line is drawn no compensating
2382: motions are made;
2383: the instantaneous baseline is at the end of the line.
2384: .PP
2385: .de eb
2386: .sp -1
2387: .nf
2388: \h'-.5n'\L'|\\nzu-1'\l'\\n(.lu+1n\(ul'\L'-|\\nzu+1'\l'|0u-.5n\(ul'
2389: .fi
2390: ..
2391: .ne 2i
2392: .mk z
2393: .nr z \nz+1
2394: The horizontal and vertical line drawing functions may be used
2395: in combination to produce large boxes.
2396: The zero-width \fIbox-rule\fR and the \(12-em wide \fIunder-rule\fR
2397: were designed to form corners when using 1-em vertical
2398: spacings.
2399: For example the macro
2400: .nr x \n(DV
2401: .nr DV 0
2402: .P1 .15i
2403: \&.de eb
2404: \&.sp \-1 \e"compensate for next automatic baseline spacing
2405: \&.nf \e"avoid possibly overflowing word buffer
2406: \&\eh'-.5n'\eL'|\e\enau\-1'\el'\e\en(.lu+1n\e(ul'\eL'-|\e\enau+1'\el'|0u-.5n\e(ul' \e"draw box
2407: \&.fi
2408: \&..
2409: .P2
2410: .nr DV \nx
2411: will draw a box around some text whose beginning vertical place was
2412: saved in number register \fIa\fR
2413: (e.g., using \&\fC.mk\ a\fR)
2414: as was done for this paragraph.
2415: .eb
2416: .sc "Graphics.
2417: The function
2418: .CW \eD'@c...@'
2419: draws a graphic object of type @c@
2420: according to a sequence of parameters,
2421: which are generally pairs of numbers.
2422: .IP
2423: .nf
2424: .ta 1.7i
2425: \fC\eD'l @dh~ dv@' \f1draw line from current position by @dh,~dv@\fC
2426: \fC\eD'c @d@' \f1draw circle of diameter @d@ with left side at current position\fC
2427: \fC\eD'e @d sub 1 d sub 2@' \f1draw ellipse of diameters @d sub 1@ and @d sub 2@\fC
2428: \fC\eD'a @dh sub 1~ dv sub 1~ dh sub 2~ dv sub 2@'\fC \f1draw arc from current position to @dh sub 1 +dh sub 2@, @dv sub 1 +dv sub 2@,\fC
2429: \f1with center at @dh sub 1 ,~ dv sub 1@ from current position\fC
2430: \fC\eD'~ @dh sub 1 dv sub 1 dh sub 2 dv sub 2 "..."@'\fC \f1draw B-spline from current position by @dh sub 1, dv sub 1@,\fC
2431: \f1then by @dh sub 2 , dv sub 2@, then by @dh sub 2 , dv sub 2@, then ...\fC
2432: .LP
2433: For example,
2434: .CW "\eD'e0.2i 0.1i'"
2435: draws the ellipse
2436: \D'e.2i .1i'\|,
2437: and
2438: .CW "\eD'l.2i -.1i'\eD'l.1i .1i'"
2439: the line
2440: \D'l.2i -.1i'\D'l.1i .1i'\|.
2441: A
2442: .CW \\eD
2443: with an unknown @c@ is processed and copied through to the output
2444: for unspecified interpretation.
2445: .PP
2446: Numbers taken as horizontal (first, third, etc.) have default scaling of ems;
2447: vertical numbers (second, fourth, etc.) have default scaling of @V^@s (\(sc1.3).
2448: The position after a graphical object has been drawn is
2449: at its end; for circles and ellipses, the ``end''
2450: is at the right side.
2451: .NH
2452: Hyphenation.
2453: .PP
2454: Automatic hyphenation may be switched off and on.
2455: When switched on with \&\fChy\fR,
2456: several variants may be set.
2457: A \fIhyphenation indicator\fR character may be embedded in a word to
2458: specify desired hyphenation points,
2459: or may be prepended to suppress hyphenation.
2460: In addition,
2461: the user may specify a small list of exception words.
2462: .PP
2463: Only words that consist of a central alphabetic string
2464: surrounded by (usually null) non-alphabetic strings
2465: are candidates for automatic hyphenation.
2466: Words that contain hyphens
2467: (minus),
2468: em-dashes (\&\fC\e(em\fR),
2469: or hyphenation indicator characters
2470: are always subject to splitting after those characters,
2471: whether automatic hyphenation is on or off.
2472: .bt "\&\fC&nh\fR" "hyphenate" "-" "E" "Automatic hyphenation is turned off.
2473: .bt "\&\fC&hy\fP@~N@" "on, @N=1@" "on, @N=1@" "E" "Automatic hyphenation is turned on
2474: for @N>=1@, or off for @N=0@.
2475: If @N=2@, last lines (ones that will cause a trap)
2476: are not hyphenated.
2477: For @N=4@ and 8, the last and first two characters
2478: respectively of a word are not split off.
2479: These values are additive;
2480: i.e., @N=14@ will invoke all three restrictions.
2481: .bt "\&\fC&hc\fI c\fR" "\&\fC\e%" "\e%\fR" "E" "Hyphenation indicator character is set
2482: to @c@ or to the default \&\fC\e%\fR.
2483: The indicator does not appear in the output.
2484: .bt "\&\fC&hw\fI word ...\fR" "" "ignored" "-" "Specify
2485: hyphenation points in words
2486: with embedded minus signs.
2487: Versions of a word with terminal \fIs\fR are implied;
2488: i.e.,
2489: .CW dig-it
2490: implies
2491: .CW dig-its .
2492: This list is examined initially and after
2493: each suffix stripping.
2494: The space available is small\(emabout 128 characters.
2495: .NH
2496: Three-Part Titles.
2497: .PP
2498: The titling function \&\fCtl\fR provides for automatic placement
2499: of three fields at the left, center, and right of a line
2500: with a title length
2501: specifiable with \&\fClt\fR.
2502: \&\fCtl\fR may be used anywhere, and is independent of the
2503: normal text collecting process.
2504: A common use is in header and footer macros.
2505: .h1
2506: .bt "\&\fC&tl '\fIleft\fP'\fIcenter\fP'\fIright\fP'\fR" "" "-" "-" "The strings
2507: \fIleft\fR, \fIcenter\fR, and \fIright\fR are
2508: respectively left-adjusted, centered, and right-adjusted
2509: in the current title length.
2510: Any of the strings may be empty,
2511: and overlapping is permitted.
2512: If the page-number character (initially \&\fC%\fR) is found within any of the fields it is replaced
2513: by the current page number in the format assigned to register \&\fC%\fR.
2514: Any character may be used in place of
2515: .CW '
2516: as the string delimiter.
2517: .bt "\&\fC&pc\fI c\fR" "\&\fC%\fR" "off" "-" "The page number character is set to @c@,
2518: or removed.
2519: The page number register remains \&\fC%\fR.
2520: .bt "\&\fC<\fI \(+-N\fR" "6.5\|in" "previous" "E,\fBm\fR" "Length of title
2521: is set to @+- N@.
2522: The line length and the title length are independent.
2523: Indents do not apply to titles; page offsets do.
2524: .NH
2525: Output Line Numbering.
2526: .PP
2527: .ll -\w'0000'u
2528: .nm 1 3
2529: Automatic sequence numbering of output lines may be
2530: requested with \&\fCnm\fR.
2531: When in effect,
2532: a three-digit, arabic number plus a digit-space
2533: is prepended to output text lines.
2534: The text lines are thus offset by four digit-spaces,
2535: and otherwise retain their line length;
2536: a reduction in line length may be desired to keep the right margin
2537: aligned with an earlier margin.
2538: Blank lines, other vertical spaces, and lines generated by \&\fCtl\fR
2539: are not numbered.
2540: Numbering can be temporarily suspended with \&\fCnn\fR,
2541: or with an \&\fC.nm\fR followed by a later \&\fC.nm +0\fR.
2542: In addition,
2543: a line number indent \fII\fR, and the number-text separation \fIS\fR
2544: may be specified in digit-spaces.
2545: Further, it can be specified that only those line numbers that are
2546: multiples of some number @M@ are to be printed (the others will appear
2547: as blank number fields).
2548: .br
2549: .nm
2550: .ll
2551: .bt "\&\fC&nm\fI \(+-N M S I\fR" "" "off" "E" "Line number mode.
2552: If @+- N@ is given,
2553: line numbering is turned on,
2554: and the next output line numbered is numbered @+- N@.
2555: Default values are @M=1@, @S=1@, and @I=0@.
2556: Parameters corresponding to missing arguments are unaffected;
2557: a non-numeric argument is considered missing.
2558: In the absence of all arguments, numbering is turned off;
2559: the next line number is preserved for possible further use
2560: in number register \&\fCln\fR.
2561: .bt "\&\fC&nn\fI N\fR" "-" "@N=1@" "E" "The next @N@ text output lines are not
2562: numbered.
2563: .PP
2564: .ll -\w'0000'u
2565: .nm +0
2566: As an example, the paragraph portions of this section
2567: are numbered with \fIM=\fR\|3:
2568: \&\&\fC.nm\ 1\ 3\fR was placed at the beginning;
2569: \&\&\fC.nm\fR was placed at the end of the first paragraph;
2570: and \&\fC.nm\ +0\fR was placed in front of this paragraph;
2571: and \&\fC.nm\fR finally placed at the end.
2572: Line lengths were also changed (by \&\fC\ew'0000'u\fR) to keep the right side aligned.
2573: Another example is
2574: .CW .nm
2575: .CW +5
2576: .CW 5
2577: .CW x
2578: .CW 3 ,
2579: which turns on numbering with the line number of the next
2580: line to be 5 greater than the last numbered line,
2581: with @M=5@, with spacing \fIS\fR untouched, and with the indent \fII\fR set to 3.
2582: .br
2583: .ll
2584: .nm
2585: .NH
2586: Conditional Acceptance of Input
2587: .PP
2588: In the following,
2589: @c@ is a one-character built-in \fIcondition\fR name,
2590: \&\fC!\fR signifies \fInot\fR,
2591: @N@ is a numerical expression,
2592: \fIstring1\fR and \fIstring2\fR are strings delimited by any non-blank, non-numeric character not in the strings,
2593: and
2594: \fIanything\fR represents what is conditionally accepted.
2595: .bt "\&\fC&if\fI c anything\fR" "" "-" "-" "If condition
2596: @c@ true, accept \fIanything\fR as input;
2597: in multi-line case use \fI\e{anything\|\e}\fR.
2598: .bt "\&\fC&if !\fIc anything\fR" "-" "-" "" "If condition @c@ false, accept \fIanything\fR.
2599: .bt "\&\fC&if\fI N anything\fR" "" "-" "\fBu\fR" "If expression @N@ > 0, accept \fIanything\fR.
2600: .bt "\&\fC&if !\fIN anything\fR" "-" "\fBu\fR" "" "If expression @N@ \(<= 0, accept \fIanything\fR.
2601: .bt "\&\fC&if '\fIstring1\fC'\fIstring2\fC'\fI anything\fR" "" "-" "" "If \fIstring1\fR identical to \fIstring2\fR,
2602: accept \fIanything\fR.
2603: .bt "\&\fC&if !'\fIstring1\fC'\fIstring2\fC'\fI anything\fR" "" "-" "" "If \fIstring1\fR not identical to \fIstring2\fR,
2604: accept \fIanything\fR.
2605: .bt "\&\fC&ie\fI c anything\fR" "" "-" "\fBu\fR" "If portion of if-else;
2606: all of the forms for \&\fCif\fR above are valid.
2607: .bt "\&\fC&el\fI anything\fR" "" "-" "-" "Else portion of if-else.
2608: .PP
2609: The built-in condition names are:
2610: .TS
2611: center box;
2612: c2|c2
2613: c2|c2
2614: c2|l2.
2615: Condition
2616: Name True If
2617: _
2618: \&\fCo\fR Current page number is odd
2619: \&\fCe\fR Current page number is even
2620: \&\fCt\fR Formatter is \*(TR
2621: \&\fCn\fR Formatter is \*(NR
2622: .TE
2623: If the condition @c@ is true, or if the number @N@ is greater than zero,
2624: or if the strings compare identically (including motions and character size and font),
2625: \fIanything\fR is accepted as input.
2626: If a \&\fC!\fR precedes the condition, number, or string comparison,
2627: the sense of the acceptance is reversed.
2628: .PP
2629: Any spaces between the condition and the beginning of \fIanything\fR are skipped over.
2630: The \fIanything\fR can be either a single input line (text, macro, or whatever)
2631: or a number of input lines.
2632: In the multi-line case,
2633: the first line must begin with a left delimiter \&\fC\e{\fR and
2634: the last line must end with a right delimiter \&\fC\e}\fR.
2635: .PP
2636: The request \&\fCie\fR (if-else) is identical to \&\fCif\fR
2637: except that the acceptance state is remembered.
2638: A subsequent and matching \&\fCel\fR (else) request then uses the reverse sense of that state.
2639: \&\fCie\fR-\&\fCel\fR pairs may be nested.
2640: .PP
2641: Some examples are:
2642: .P1
2643: &if e .tl '\|Even Page %'''
2644: .P2
2645: which outputs a title if the page number is even; and
2646: .P1
2647: &ie \en%>1 \e{\e
2648: \&' sp 0.5i
2649: & tl 'Page %'''
2650: \&' sp |1.2i \e}
2651: &el .sp |2.5i
2652: .P2
2653: which treats page 1 differently from other pages.
2654: .NH
2655: Environment Switching.
2656: .PP
2657: A number of the parameters that
2658: control the text processing are gathered together into an
2659: \fIenvironment\fR, which can be switched by the user.
2660: The environment parameters are those associated
2661: with requests noting E in their \fINotes\fR column;
2662: in addition, partially collected lines and words are in the environment.
2663: Everything else is global; examples are page-oriented parameters,
2664: diversion-oriented parameters, number registers, and macro and string definitions.
2665: All environments are initialized with default parameter values.
2666: .bt "\&\fC&ev\fI N\fR" "@N=0@" "previous" "-" "Environment switched to
2667: environment @0<=N<=2@.
2668: Switching is done in push-down fashion so that
2669: restoring a previous environment \fImust\fR be done with \&\fC.ev\fR
2670: rather than specific reference.
2671: Note that what is pushed down and restored is the environment
2672: .I number,
2673: not its contents.
2674: .NH
2675: Insertions from the Standard Input
2676: .PP
2677: The input can be temporarily switched to the system standard input
2678: with \&\fCrd\fR,
2679: which will switch back when two consecutive newlines
2680: are found (the extra blank line is not used).
2681: This mechanism is intended for insertions in form-letter-like documentation.
2682: On \s-1UNIX\s+1, the standard input can be the user's keyboard,
2683: a pipe, or a file.
2684: .bt "\&\fC&rd\fI prompt\fR" "-" "\fIprompt=\fR\s-1BEL\s+1" "-" "Read insertion
2685: from the standard input until two newlines in a row are found.
2686: If the standard input is the user's keyboard, \fIprompt\fR (or a \s-1BEL\s+1)
2687: is written onto the standard output.
2688: \&\fCrd\fR behaves like a macro,
2689: and arguments may be placed after \fIprompt\fR.
2690: .bt "\&\fC&ex\fR" "-" "-" "-" "Exit from \*(NR/\*(TR.
2691: Text processing is terminated exactly as if all input had ended.
2692: .PP
2693: If insertions are to be
2694: taken from the terminal keyboard while output is being printed
2695: on the terminal, the command line option \&\fC\-q\fR will turn off the echoing
2696: of keyboard input and prompt only with \s-1BEL\s+1.
2697: The regular input and insertion input cannot
2698: simultaneously come from the standard input.
2699: .PP
2700: As an example,
2701: multiple copies of a form letter may be prepared by entering the insertions
2702: for all the copies in one file to be used as the standard input,
2703: and causing the file containing the letter to reinvoke itself with \&\fCnx\fR (\(sc19);
2704: the process would ultimately be ended by an \&\fCex\fR in the insertion file.
2705: .NH
2706: Input/Output File Switching
2707: .bt "\&\fC&so\fI filename\fR" "" "-" "-" "Switch source file.
2708: The top input (file reading) level is switched to \fIfilename\fR.
2709: When the new file ends,
2710: input is again taken from the original file.
2711: \&\fCso\fR's may be nested.
2712: .bt "\&\fC&nx\fI filename\fR" "" "end-of-file" "-" "Next file is \fIfilename\fR.
2713: The current file is considered ended, and the input is immediately switched
2714: to \fIfilename\fR.
2715: .bt "\&\fC&sy\fI string\fR" "" "-" "-" "Execute program from \fIstring\fR,
2716: which is the rest of the input line.
2717: The output is not collected automatically.
2718: The number register
2719: .CW $$ ,
2720: which contains the process id of the \*(TR process,
2721: may be useful in generating unique filenames for output.
2722: .bt "\&\fC&pi\fI string\fR" "" "-" "-" "Pipe output to \fIstring\fR,
2723: which is the rest of the input line.
2724: This request must occur before any printing occurs.
2725: .bt "\&\fC&cf\fI filename\fR" "" "-" "-" "Copy
2726: contents of file
2727: .I filename
2728: to output, completely unprocessed.
2729: The file is assumed to contain something meaningful
2730: to subsequent processes.
2731: .NH
2732: Miscellaneous
2733: .br
2734: .mc \s12\(br\s0
2735: .bt "\&\fC.mc\fI c N\fR" - off E,\fBm\fR "Specifies
2736: that a \fImargin\fR character @c@ appear a distance
2737: @N@ to the right of the right margin
2738: after each non-empty text line (except those produced by \&\fCtl\fR).
2739: If the output line is too long (as can happen in nofill mode)
2740: the character will be appended to the line.
2741: If @N@ is not given, the previous @N@ is used; the initial @N@ is
2742: 0.2 inches in \*(NR and 1 em in \*(TR.
2743: The margin character used with this paragraph was a 12-point box-rule.
2744: .br
2745: .mc
2746: .bt "\&\fC.tm\fI string\fR" "-" "newline" "-" "After skipping initial blanks,
2747: \fIstring\fR (rest of the line) is read in copy mode
2748: and written on the standard error.
2749: .bt "\&\fC&ab\fI string\fR" "-" "newline" "-" "After skipping initial blanks,
2750: \fIstring\fR (rest of the line) is read in copy mode
2751: and written on the standard error.
2752: \*(Tr or \*(NR then exit.
2753: .bt "\&\fC.ig\fI yy\fR" "-" "\fI.yy=\&\fC..\fR" "-" "Ignore
2754: input lines.
2755: \&\fCig\fR behaves exactly like \&\fCde\fR (\(sc7) except that the
2756: input is discarded.
2757: The input is read in copy mode, and any auto-incremented
2758: registers will be affected.
2759: .bt "\&\fC.lf\fI N filename\fR" "" "-" "-" "Set
2760: line number to @N@ and filename to @filename@
2761: for purposes of subsequent error messages, etc.
2762: The number register [sic]
2763: .CW .F
2764: contains the name of the current input file,
2765: as set by command line argument,
2766: .CW so ,
2767: .CW nx ,
2768: or
2769: .CW lf .
2770: The number register
2771: .CW .c
2772: contains the number of input lines read from the current file,
2773: again perhaps as modified by
2774: .CW lf .
2775: .CW
2776: .bt "\&\fC.pm\fI t\fR" "-" "all" "-" "Print macros.
2777: The names and sizes of all of the defined macros and strings are printed
2778: on the standard error;
2779: if \fIt\fR is given, only the total of the sizes is printed.
2780: The sizes is given in blocks
2781: of 128 characters.
2782: .bt "\&\fC.fl\fR" - - B "Flush output buffer.
2783: Force output, including any pending position information.
2784: ......
2785: .NH
2786: Output and Error Messages.
2787: .PP
2788: The output from \&\fCtm\fR, \&\fCpm\fR, and the prompt from \&\fCrd\fR,
2789: as well as various error messages are written onto
2790: the standard error.
2791: The latter is different from the standard output,
2792: where formatted text goes.
2793: By default, both are written onto the user's terminal,
2794: but they can be independently redirected.
2795: .PP
2796: Various error conditions may occur during
2797: the operation of \*(NR and \*(TR.
2798: Certain less serious errors having only local impact do not
2799: cause processing to terminate.
2800: Two examples are \fIword overflow\fR, caused by a word that is too large
2801: to fit into the word buffer (in fill mode), and
2802: \fIline overflow\fR, caused by an output line that grew too large
2803: to fit in the line buffer.
2804: In both cases, a message is printed, the offending excess
2805: is discarded,
2806: and the affected word or line is marked at the point of truncation
2807: with a \(** in \*(NR and a \(lh in \*(TR.
2808: Processing continues if possible,
2809: on the grounds that output useful for debugging may be produced.
2810: If a serious error occurs, processing terminates,
2811: and a message is printed, along with a list of the macro names currently active.
2812: Examples of serious errors include the inability to create, read, or write files,
2813: and the exceeding of certain internal limits that
2814: make future output unlikely to be useful.
2815: .NH
2816: Output Language
2817: .PP
2818: \*(Tr
2819: produces its output in a language that is independent of any
2820: specific output device,
2821: except that the numbers in it have been computed on the basis
2822: of the resolution of the device,
2823: and the sizes, fonts, and characters that that device can print.
2824: Nevertheless it is quite possible to interpret that output
2825: on a different device, within the latter's capabilities.
2826: .IP
2827: .nf
2828: .ta .7i
2829: @cw s n@ set point size to @n@
2830: @cw f n@ set font to @n@
2831: @cw c c@ print \s-1ASCII\s0 character @c@
2832: @cw C xx@ print character @xx@; terminate @xx@ by white space
2833: @cw N n@ print character @n@ on current font
2834: @cw H n@ go to absolute horizontal position \f2n\fP (@n>=0@)
2835: @cw V n@ go to absolute vertical position \f2n\fP (@n>=0@, down is positive)
2836: @cw h n@ go \f2n\fP units horizontally; @n < 0@ is to the left
2837: @cw v n@ go \f2n\fP units vertically; @n < 0@ is up
2838: @nnc@ move right \f2nn\fP, then print \s-1ASCII\s0 character \f2c\fP; \f2nn\fP must be exactly 2 digits
2839: @cw p n@ new page \f2n\fP begins\(emset vertical position to 0
2840: @cw n b~a@ end of line (information only\(emno action); \f2b\fP = space before line, \f2a\fP = after
2841: @cw w@ paddable word space (information only\(emno action)
2842: @cw D c@ ...\en graphics function @c@; see below
2843: @cw x@ ...\en device control functions; see below
2844: @cw "#"@ ...\en comment
2845: .LP
2846: All position values are in units.
2847: Sequences that end in digits must be followed by a non-digit.
2848: Blanks, tabs and newlines may occur as separators
2849: in the input, and are mandatory to separate constructions
2850: that would otherwise be confused.
2851: Graphics functions, device control functions, and comments extend to the
2852: end of the line they occur on.
2853: .PP
2854: The device control and graphics commands are intended as open-ended
2855: families, to be expanded as needed.
2856: The graphics functions coincide directly with the
2857: .CW \eD
2858: sequences:
2859: .IP
2860: .nf
2861: .ta 1.7i
2862: @cw Dl@ \f2dh dv\fP draw line from current position by @dh,~ dv@
2863: @cw Dc@ \f2d\fP draw circle of diameter \f2d\fP with left side here
2864: @cw De@ @dh sub 1~dv sub 2@ draw ellipse of diameters @dh sub 1@ and @ dv sub 2@\fP
2865: @cw Da ~dh sub 1~ dv sub 1 ~ dh sub 2 ~dv sub 2@ draw arc from current position to @dh sub 1 +dh sub 2 ,~ dv sub 1 +dv sub 2@,
2866: center at @dh sub 1 ,~ dv sub 1@ from current position
2867: @cw "D~" ~dh sub 1 ~dv sub 1 ~dh sub 2 ~dv sub 2@ ... draw B-spline from current position to @dh sub 1 ,~ dv sub 1@,
2868: then to @dh sub 2 , ~dv sub 2@, then to ...
2869: @cw "D"z ~dh sub 1 ~dv sub 1 ~dh sub 2 ~dv sub 2@ ... for any other @z@ is uninterpreted
2870: .LP
2871: In all of these, @dh, ~dv@ is an increment on the current horizontal and
2872: vertical position,
2873: with down and right positive.
2874: All distances and dimensions are in units.
2875: .PP
2876: The device control functions begin with
2877: .CW x ,
2878: then a command, then other parameters.
2879: .IP
2880: .ta .8i
2881: .nf
2882: .ft CW
2883: x T \f2s\fP \f1name of typesetter is @s@\fC
2884: x r \f2n h v\fP \f1resolution is @n@ units/inch;\fC \f1@h@ = minimum horizontal motion, @v@ = minimum vertical\fC
2885: x i \f1initialize\fP
2886: x f \f2n s\fP \f1mount font @s@ on font position @n@\fC
2887: x p \f1pause\(emcan restart\fC
2888: x s \f1stop\(emdone forever\fC
2889: x t \f1generate trailer information, if any\fC
2890: x H \f2n\fP \f1set character height to @n@\fC
2891: x S \f2n\fP \f1set slant to @n@\fC
2892: x X \f2any\fP \f1generated by the \&\fC\eX\fP function\fC
2893: x \f2any\fP \f1to be ignored if not recognized\fC
2894: .LP
2895: Subcommands like
2896: .CW i '' ``
2897: may be spelled out like
2898: .CW init ''. ``
2899: .PP
2900: The commands
2901: .CW "x T" ,
2902: .CW "x r " ...,
2903: and
2904: .CW "x i"
2905: must occur first;
2906: fonts must be mounted before they can be used;
2907: .CW "x s
2908: comes last.
2909: There are no other order requirements.
2910: .PP
2911: The following is the output from
2912: .CW hello, "" ``
2913: .CW world ''
2914: for a typical Postscript printer,
2915: as described in \(sc23:
2916: .P1
2917: x T post
2918: x res 720 1 1
2919: x init
2920: V0
2921: p1
2922: .P2
2923: .P1
2924: x font 1 R
2925: x font 2 I
2926: x font 3 B
2927: x font 4 BI
2928: x font 5 CW
2929: x font 6 H
2930: x font 7 HB
2931: x font 8 HX
2932: x font 9 S1
2933: x font 10 S
2934: .P2
2935: .P1
2936: s10
2937: f1
2938: H0
2939: s10
2940: f1
2941: V0
2942: H720
2943: V120
2944: ch
2945: 50e44l28l28o50,w58w72o50r33l28dn120 0
2946: x trailer
2947: V7920
2948: x stop
2949: .P2
2950: .PP
2951: \*(Tr output is normally not redundant;
2952: size and font changes and position information are not included
2953: unless needed.
2954: Nevertheless, each page is self-contained, for the benefit of postprocessors
2955: that re-order pages or process only a subset.
2956: .NH
2957: Device and Font Description Files
2958: .PP
2959: The parameters that describe a output device
2960: .I name
2961: are read
2962: from the directory
2963: .CW /usr/lib/font/dev@name@ ,
2964: each time
2965: \*(TR
2966: is invoked.
2967: The device name is provided by default,
2968: by the environment variable
2969: .CW TYPESETTER ,
2970: or by a command-line argument
2971: .CW -T@name@ .
2972: The default device name is
2973: .CW post ,
2974: for Postscript.
2975: The pre-defined string
2976: .CW .T
2977: contains the name of the device.
2978: The
2979: .CW -F
2980: command-line option may be used to change the default directory.
2981: .......
2982: .sc "Device description file.
2983: The file
2984: .CW DESC
2985: in
2986: .CW /usr/lib/font/dev@name@
2987: contains general parameters of the device, one per line,
2988: as a sequence of names and values.
2989: \*(Tr recognizes these parameters, and ignores any
2990: others that may be present for specific drivers:
2991: .IP
2992: .nf
2993: .ta 1i
2994: @cw fonts ~ n ~ F sub 1 ~F sub 2 ~. . .~ F sub n@
2995: @cw sizes ~ s sub 1 ~ s sub 2 ~ . . . cw 0@
2996: @cw res ~n@
2997: @cw hor ~n@
2998: @cw vert ~n@
2999: @cw unitwidth ~n@
3000: @cw charset@
3001: \f2list of multi-character character names (optional)\fP
3002: .LP
3003: The @F sub i@ are font names
3004: to be initially mounted.
3005: The list of sizes is a set of integers representing
3006: some or all of the legal sizes the device can produce,
3007: terminated by a zero.
3008: The
3009: .CW res
3010: parameter gives the resolution of the machine in units per inch;
3011: .CW hor
3012: and
3013: .CW ver
3014: give the minimum number of units that can be moved
3015: horizontally and vertically.
3016: .PP
3017: Character widths for each font are assumed to be given in machine units
3018: at point size
3019: .CW unitwidth .
3020: (In other words, a character with a width of
3021: @n@ is @n@ units wide at size
3022: .CW unitwidth .)
3023: .PP
3024: A list of valid character names may be introduced by
3025: .CW charset ;
3026: the list of names is optional.
3027: .PP
3028: A line whose first non-blank character is
3029: .CW #
3030: is a comment.
3031: Except that
3032: .CW charset
3033: must occur last, parameters may appear in any order.
3034: .PP
3035: Here is a subset of the
3036: .CW DESC
3037: file for a typical Postscript printer:
3038: .P1
3039: # Description file for Postscript printers.
3040:
3041: fonts 10 R I B BI CW H HB HX S1 S
3042: sizes 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
3043: 24 25 26 27 28 29 30 31 32 33 34 35 36 38 40 44 48 54 60 72 0
3044: res 720
3045: hor 1
3046: vert 1
3047: unitwidth 10
3048: charset
3049: hy ct fi fl ff Fi Fl dg em 14 34 12 en aa
3050: ga ru sc dd -> br Sl ps cs cy as os =. ld
3051: rd le ge pp -+ ob vr
3052: sq bx ci fa te ** pl mi eq ~= *A *B *X *D
3053: *E *F *G *Y *I *K *L *M *N *O *P *R *H *S *T *U *W
3054: *C *Q *Z ul rn *a *b *x *d *e *f *g *y *i *k
3055: *l *m *n *o *p *h *r *s *t *u *w *c *q *z
3056: .P2
3057: .sc "Font description files.
3058: Each font is described by an analogous description file,
3059: which begins with parameters of the font, one per line, followed by a
3060: list of characters and widths.
3061: The file for font
3062: .I f
3063: is
3064: .CW /usr/lib/font/dev@name@/@f@ .
3065: .IP
3066: .ta 1.7i
3067: .nf
3068: @cw name ~str@ name of font is @str@
3069: @cw ligatures ~ ". . ." ~ cw "0"@ list of ligatures
3070: @cw spacewidth ~n@ width of a space on this font
3071: @cw special@ this is a special font
3072: @cw charset@
3073: \f2list of character name, width, ascender/descender, code\fP
3074: .LP
3075: The
3076: .CW name
3077: and
3078: .CW charset
3079: fields are mandatory;
3080: .CW charset
3081: must be last.
3082: Comments are permitted,
3083: as are other unrecognized parameters.
3084: .PP
3085: Each line following
3086: .CW charset
3087: describes one character: its name, its width in units as described above,
3088: ascender/descender information, and a decimal, octal or hexadecimal value
3089: by which the output device knows it
3090: (the
3091: .CW \eN
3092: ``number'' of the character).
3093: The character name is arbitrary, except that
3094: .CW ---
3095: signifies an unnamed character.
3096: If the width field contains
3097: .CW \&" ,
3098: the name is a synonym for the previous character.
3099: The ascender/descender field is 1 if
3100: the character has a descender (hangs below the baseline, like
3101: .CW y ),
3102: is 2 if it has an ascender (is tall, like
3103: .CW Y ),
3104: is 3 if both,
3105: and is 0 if neither.
3106: The value is returned
3107: in the
3108: .CW ct
3109: register, as computed by the
3110: .CW \ew
3111: function (\(sc11.2).
3112: .PP
3113: Here are excerpts from a typical font description file
3114: for the same Postscript printer.
3115: .P1
3116: hy 33 0 45 hyphen \e(hy
3117: - " - is a synonym for \e(hy
3118: .sp .3
3119: Q 72 3 81
3120: .sp .3
3121: a 44 0 97
3122: b 50 2 98
3123: c 44 0 99
3124: d 50 2 100
3125: y 50 1 121
3126: .sp .3
3127: em 100 0 208
3128: --- 44 2 220 English pound currency symbol \eN'220'
3129: --- 36 0 221 centered dot \eN'221'
3130: .P2
3131: This says, for example, that the width of the letter
3132: .CW a
3133: is 44 units at point size 10,
3134: the value of
3135: .CW unitwidth .
3136: Point sizes are scaled linearly and rounded, so the width of
3137: .CW a
3138: will be 44 at size 10, 40 at size 9, 35 at size 8,
3139: and so on.
3140: .sp 100
3141: .BP
3142: .fp 8 C CW
3143: .tr &.
3144: .tr |
3145: .tr ~|
3146: .TL
3147: Tutorial Examples
3148: .SP
3149: .2C
3150: .sp .25i
3151: .SH
3152: Introduction
3153: .PP
3154: It is almost always necessary to
3155: prepare at least a small set of macro definitions
3156: to describe a document.
3157: Such common formatting needs
3158: as page margins and footnotes
3159: are deliberately not built into \*(NR and \*(TR.
3160: Instead,
3161: the macro and string definition, number register, diversion,
3162: environment switching, page-position trap, and conditional input mechanisms
3163: provide the basis for user-defined implementations.
3164: .PP
3165: For most uses, a standard package like
3166: .CW -ms
3167: or
3168: .CW -mm
3169: is the right choice.
3170: The next stage is to augment that,
3171: or to selectively replace macros from the standard package.
3172: The last stage, much harder,
3173: is to write one's own from scratch.
3174: .PP
3175: The examples discussed here are intended to be useful and somewhat realistic,
3176: but will not necessarily cover all relevant contingencies.
3177: Explicit numerical parameters are used
3178: in the examples
3179: to make them easier to read and to
3180: illustrate typical values.
3181: In many cases, number registers would really be used
3182: to reduce the number of places where numerical
3183: information is kept,
3184: and to concentrate conditional parameter initialization
3185: like that which depends on whether \*(TR or \*(NR is being used.
3186: .SH
3187: Page Margins
3188: .PP
3189: As discussed in \(sc3,
3190: header and footer macros are usually defined
3191: to describe the top and bottom page margin areas respectively.
3192: A trap is planted at page position 0 for the header, and at
3193: \fI\-N\fR (\fIN\fR from the page bottom) for the footer.
3194: The simplest such definitions might be
3195: .P1 .1i
3196: &de hd \e"define header
3197: \&'sp 1i
3198: && \e"end definition
3199: &de fo \e"define footer
3200: \&'bp
3201: && \e"end definition
3202: &wh 0 hd
3203: &wh -1i fo
3204: .P2
3205: which provide blank 1 inch top and bottom margins.
3206: The header will occur on the \fIfirst\fR page,
3207: only if the definition and trap exist prior to
3208: the initial pseudo-page transition (\(sc3).
3209: In fill mode, the output line that springs the footer trap
3210: was typically forced out because some part or whole word didn't fit on it.
3211: If anything in the footer and header that follows causes a break,
3212: that word or part word will be forced out.
3213: In this and other examples,
3214: requests like \&\fCbp\fR and \&\fCsp\fR that normally cause breaks are invoked using
3215: the no-break control character \&\fC'\fR
3216: to avoid this.
3217: When the header/footer design contains material
3218: requiring independent text processing, the
3219: environment may be switched, avoiding
3220: most interaction with the running text.
3221: .PP
3222: A more realistic example would be
3223: .P1 .1i
3224: &de hd \e"header
3225: &if \e\en%>1 \e{\e
3226: \&'sp ~0.5i-1 \e"tl base at 0.5i
3227: &tl ''- % -'' \e"centered page number
3228: &ps \e"restore size
3229: &ft \e"restore font
3230: &vs \e} \e"restore vs
3231: \&'sp ~1.0i \e"space to 1.0i
3232: &ns \e"turn on no-space mode
3233: &&
3234: &de fo \e"footer
3235: &ps 10 \e"set footer/header size
3236: &ft R \e"set font
3237: &vs 12p \e"set baseline spacing
3238: &if \e\en%=1 \e{\e
3239: \&'sp ~\e\en(.pu-0.5i-1 \e"tl base 0.5i up
3240: &tl ''- % -'' \e} \e"first page number
3241: \&'bp
3242: &&
3243: &wh 0 hd
3244: &wh -1i fo
3245: .P2
3246: which sets the size, font, and baseline spacing for the
3247: header/footer material, and ultimately restores them.
3248: The material in this case is a page number at the bottom of the
3249: first page and at the top of the remaining pages.
3250: The \&\fCsp\fR's refer to absolute positions to avoid
3251: dependence on the baseline spacing.
3252: Another reason for doing this in the footer
3253: is that the footer is invoked by printing a line whose
3254: vertical spacing swept past the trap position by possibly
3255: as much as the baseline spacing.
3256: No-space mode is turned on at the end of \&\fChd\fR
3257: to render ineffective
3258: accidental occurrences of \&\fCsp\fR at the top of the running text.
3259: .PP
3260: The above method of restoring size, font, etc., presupposes
3261: that such requests (that set \fIprevious\fR value) are \fInot\fR
3262: used in the running text.
3263: A better scheme is save and restore both the current \fIand\fR
3264: previous values as shown for size in the following:
3265: .P1 .1i
3266: &de fo
3267: &nr s1 \e\en(.s \e"current size
3268: &ps
3269: &nr s2 \e\en(.s \e"previous size
3270: & --- \e"rest of footer
3271: &&
3272: &de hd
3273: & --- \e"header stuff
3274: &ps \e\en(s2 \e"restore previous size
3275: &ps \e\en(s1 \e"restore current size
3276: &&
3277: .P2
3278: Page numbers may be printed in the bottom margin
3279: by a separate macro triggered during the footer's
3280: page ejection:
3281: .P1 .1i
3282: &de bn \e"bottom number
3283: &tl ''- % -'' \e"centered page number
3284: &&
3285: &wh -0.5i-1v bn \e"tl base 0.5i up
3286: .P2
3287: .SH
3288: Paragraphs and Headings
3289: .PP
3290: The housekeeping
3291: associated with starting a new paragraph should be collected
3292: in a paragraph macro
3293: that, for example,
3294: does the desired preparagraph spacing,
3295: forces the correct font, size, baseline spacing, and indent,
3296: checks that enough space remains for \fImore than one\fR line,
3297: and
3298: requests a temporary indent.
3299: .P1 .1i
3300: &de pg \e"paragraph
3301: &br \e"break
3302: &ft R \e"force font,
3303: &ps 10 \e"size,
3304: &vs 12p \e"spacing,
3305: &in 0 \e"and indent
3306: &sp 0.4 \e"prespace
3307: &ne 1+\e\en(.Vu \e"want more than 1 line
3308: &ti 0.2i \e"temp indent
3309: &&
3310: .P2
3311: The first break in \&\fCpg\fR
3312: will force out any previous partial lines,
3313: and must occur before the \&\fCvs\fR.
3314: The forcing of font, etc. is
3315: partly a defense against prior error and
3316: partly to permit
3317: things like section heading macros to
3318: set parameters only once.
3319: The prespacing parameter is suitable for \*(TR;
3320: a larger space, at least as big as the output device vertical resolution, would be
3321: more suitable in \*(NR.
3322: The choice of remaining space to test for in the \&\fCne\fR
3323: is the smallest amount greater than one line
3324: (the \&\fC.V\fR is the available vertical resolution).
3325: .PP
3326: A macro to automatically number section headings
3327: might look like:
3328: .P1 .1i
3329: &de sc \e"section
3330: & --- \e"force font, etc.
3331: &sp 0.4 \e"prespace
3332: &ne 2.4+\e\en(.Vu \e"want 2.4+ lines
3333: .lg 0
3334: &fi
3335: .lg
3336: \e\en+S.
3337: &&
3338: &nr S 0 1 \e"init S
3339: .P2
3340: The usage is \&\fC.sc\fR,
3341: followed by the section heading text,
3342: followed by \&\fC.pg\fR.
3343: The \&\fCne\fR test value includes one line of heading,
3344: 0.4 line in the following \&\fCpg\fR, and
3345: one line of the paragraph text.
3346: A word consisting of the next section number and a period is
3347: produced to begin the heading line.
3348: The format of the number may be set by \&\fCaf\fR (\(sc8).
3349: .PP
3350: Another common form is the labeled, indented paragraph,
3351: where the label protrudes left into the indent space.
3352: .P1 .1i
3353: &de lp \e"labeled paragraph
3354: &pg
3355: &in 0.5i \e"paragraph indent
3356: &ta 0.2i 0.5i \e"label, paragraph
3357: &ti 0
3358: \et\e\e$1\et\ec \e"flow into paragraph
3359: &&
3360: .P2
3361: The intended usage is ``\&\fC.lp\fR \fIlabel\fR\|'';
3362: \fIlabel\fR will begin at 0.2 inch, and
3363: cannot exceed a length of 0.3 inch without intruding into
3364: the paragraph.
3365: The label could be right adjusted against 0.4 inch by
3366: setting the tabs instead with \&\fC.ta|0.4iR|0.5i\fR.
3367: The last line of \&\fClp\fR ends with \&\fC\ec\fR so that
3368: it will become a part of the first line of the text
3369: that follows.
3370: .SH
3371: Multiple Column Output
3372: .PP
3373: The production of multiple column pages requires
3374: the footer macro to decide whether it was
3375: invoked by other than the last column,
3376: so that it will begin a new column rather than
3377: produce the bottom margin.
3378: The header can initialize a column register that
3379: the footer will increment and test.
3380: The following is arranged for two columns, but
3381: is easily modified for more.
3382: .P1 .1i
3383: &de hd \e"header
3384: & ---
3385: &nr cl 0 1 \e"init column count
3386: &mk \e"mark top of text
3387: &&
3388: .P2
3389: .P1 .1i
3390: &de fo \e"footer
3391: &ie \e\en+(cl<2 \e{\e
3392: &po +3.4i \e"next column; 3.1+0.3
3393: &rt \e"back to mark
3394: &ns \e} \e"no-space mode
3395: &el \e{\e
3396: &po \e\enMu \e"restore left margin
3397: & ---
3398: \&'bp \e}
3399: &&
3400: &ll 3.1i \e"column width
3401: &nr M \e\en(.o \e"save left margin
3402: .P2
3403: Typically a portion of the top of the first page
3404: contains full width text;
3405: the request for the narrower line length,
3406: as well as another \&\fC.mk\fR would
3407: be made where the two column output was to begin.
3408: .SH
3409: Footnotes
3410: .PP
3411: The footnote mechanism to be described is used by
3412: embedding the footnotes in the input text at the
3413: point of reference,
3414: demarcated by an initial \&\fC.fn\fR and a terminal \&\fC.ef\fR:
3415: .P1 .1i
3416: &fn
3417: \fIFootnote text and control lines...\fP
3418: &ef
3419: .P2
3420: In the following,
3421: footnotes are processed in a separate environment and diverted
3422: for later printing in the space immediately prior to the bottom
3423: margin.
3424: There is provision for the case where the last collected
3425: footnote doesn't completely fit in the available space.
3426: .P1 .1i
3427: &de hd \e"header
3428: & ---
3429: &nr x 0 1 \e"init footnote count
3430: &nr y 0-\e\enb \e"current footer place
3431: &ch fo -\e\enbu \e"reset footer trap
3432: &if \e\en(dn .fz \e"leftover footnote
3433: &&
3434: .P2
3435: .P1 .1i
3436: &de fo \e"footer
3437: &nr dn 0 \e"zero last diver. size
3438: &if \e\enx \e{\e
3439: &ev 1 \e"expand footnotes in ev1
3440: &nf \e"retain vertical size
3441: &FN \e"footnotes
3442: &rm FN \e"delete it
3443: .P2
3444: .P1 .1i
3445: &if "\e\en(.z"fy" .di \e"end overflow di
3446: &nr x 0 \e"disable fx
3447: &ev \e} \e"pop environment
3448: & ---
3449: \&'bp
3450: &&
3451: .P2
3452: .P1 .1i
3453: &de fx \e"process footnote overflow
3454: &if \e\enx .di fy \e"divert overflow
3455: &&
3456: .P2
3457: .P1 .1i
3458: &de fn \e"start footnote
3459: &da FN \e"divert (append) footnote
3460: &ev 1 \e"in environment 1
3461: &if \e\en+x=1 .fs \e"if 1st, separator
3462: &fi \e"fill mode
3463: &&
3464: .P2
3465: .P1 .1i
3466: &de ef \e"end footnote
3467: &br \e"finish output
3468: &nr z \e\en(.v \e"save spacing
3469: &ev \e"pop ev
3470: &di \e"end diversion
3471: &nr y -\e\en(dn \e"new footer position,
3472: &if \e\enx=1 .nr y -(\e\en(.v-\e\enz) \e
3473: \e"uncertainty correction
3474: &ch fo \e\enyu \e"y is negative
3475: &if (\e\en(nl+1v)>(\e\en(.p+\e\eny) \e
3476: &ch fo \e\en(nlu+1v \e"didn't fit
3477: &&
3478: .P2
3479: .P1 .1i
3480: &de fs \e"separator
3481: \el'1i' \e"1 inch rule
3482: &br
3483: &&
3484: .P2
3485: .P1 .1i
3486: &de fz \e"get leftover footnote
3487: &fn
3488: &nf \e"retain vertical size
3489: &fy \e"where fx put it
3490: &ef
3491: &&
3492: .P2
3493: .P1 .1i
3494: &nr b 1.0i \e"bottom margin size
3495: &wh 0 hd \e"header trap
3496: &wh 12i fo \e"footer trap->temp pos
3497: &wh -\e\enbu fx \e"fx at footer position
3498: &ch fo -\e\enbu \e"conceal fx with fo
3499: .P2
3500: .PP
3501: The header \&\fChd\fR initializes a footnote count register \&\fCx\fR,
3502: and sets both the current footer trap position register \&\fCy\fR and
3503: the footer trap itself to a nominal position specified in
3504: register \&\fCb\fR.
3505: In addition, if the register \&\fCdn\fR indicates a leftover footnote,
3506: \&\fCfz\fR is invoked to reprocess it.
3507: The footnote start macro \&\fCfn\fR begins a diversion (append) in environment 1,
3508: and increments the count \&\fCx\fR; if the count is one, the footnote separator \&\fCfs\fR
3509: is interpolated.
3510: The separator is kept in a separate macro to permit user redefinition.
3511: .PP
3512: The footnote end macro \&\fCef\fR restores
3513: the previous environment and ends the diversion after saving the spacing size in register \&\fCz\fR.
3514: \&\fCy\fR is then decremented by the size of the footnote, available in \&\fCdn\fR;
3515: then on the first footnote, \&\fCy\fR is further decremented by the difference
3516: in vertical baseline spacings of the two environments, to
3517: prevent the late triggering the footer trap from causing the last
3518: line of the combined footnotes to overflow.
3519: The footer trap is then set to the lower (on the page) of \&\fCy\fR or the current page position (\&\fCnl\fR)
3520: plus one line, to allow for printing the reference line.
3521: .PP
3522: If indicated by \&\fCx\fR, the footer \&\fCfo\fR rereads the footnotes from \&\fCFN\fR in nofill mode
3523: in environment 1,
3524: and deletes \&\fCFN\fR.
3525: If the footnotes were too large to fit, the macro \&\fCfx\fR will be trap-invoked to redivert
3526: the overflow into \&\fCfy\fR,
3527: and the register \&\fCdn\fR will later indicate to the header whether \&\fCfy\fR is empty.
3528: .PP
3529: Both \&\fCfo\fR and \&\fCfx\fR are planted in the nominal footer trap position in an order
3530: that causes \&\fCfx\fR to be concealed unless the \&\fCfo\fR trap is moved.
3531: The footer then terminates the overflow diversion, if necessary, and
3532: zeros \&\fCx\fR to disable \&\fCfx\fR,
3533: because the uncertainty correction
3534: together with a not-too-late triggering of the footer can result
3535: in the footnote rereading finishing before reaching the \&\fCfx\fR trap.
3536: .PP
3537: A good exercise for the student is to combine the multiple-column and footnote mechanisms.
3538: .SH
3539: The Last Page
3540: .PP
3541: After the last input file has ended, \*(NR and \*(TR
3542: invoke the \fIend macro\fR (\(sc7), if any,
3543: and when it finishes, eject the remainder of the page.
3544: During the eject, any traps encountered are processed normally.
3545: At the end of this last page, processing terminates
3546: unless a partial line, word, or partial word remains.
3547: If it is desired that another page be started, the end-macro
3548: .P1 .1i
3549: &de en \e"end-macro
3550: \ec
3551: \&'bp
3552: &&
3553: &em en
3554: .P2
3555: will deposit a null partial word,
3556: and produce another last page.
3557: .1C
3558: .sp 100
3559: .BP
3560: ........
3561: .TL
3562: Special Character Names
3563: .SP
3564: .PP
3565: The following table lists names for a set of characters,
3566: most of which have typically been available with \*(TR.
3567: Not all print on any particular device, including this one.
3568: .TS
3569: center;
3570: l l20fCW l l20fCW l l20fCW.
3571: \&\' \e' \(*m \e(*m \(~= \e(~=
3572: \` \e` \(*n \e(*n \(ap \e(ap
3573: \(em \e(em \(*c \e(*c \(!= \e(!=
3574: - \e- \(*o \e(*o \(-> \e(->
3575: \(hy \e(hy \(*p \e(*p \(<- \e(<-
3576: \- \e- \(*r \e(*r \(ua \e(ua
3577: \(bu \e(bu \(*s \e(*s \(da \e(da
3578: \(sq \e(sq \(ts \e(ts \(mu \e(mu
3579: \(ru \e(ru \(*t \e(*t \(di \e(di
3580: \(14 \e(14 \(*u \e(*u \(+- \e(+-
3581: \(12 \e(12 \(*f \e(*f \(cu \e(cu
3582: \(34 \e(34 \(*x \e(*x \(ca \e(ca
3583: \(fi \e(fi \(*q \e(*q \(sb \e(sb
3584: \(fl \e(fl \(*w \e(*w \(sp \e(sp
3585: \(ff \e(ff \(*A \e(*A \(ib \e(ib
3586: \(Fi \e(Fi \(*B \e(*B \(ip \e(ip
3587: \(Fl \e(Fl \(*G \e(*G \(if \e(if
3588: \(de \e(de \(*D \e(*D \(pd \e(pd
3589: \(dg \e(dg \(*E \e(*E \(gr \e(gr
3590: \(fm \e(fm \(*Z \e(*Z \(no \e(no
3591: \(ct \e(ct \(*Y \e(*Y \(is \e(is
3592: \(rg \e(rg \(*H \e(*H \(pt \e(pt
3593: \(co \e(co \(*I \e(*I \(es \e(es
3594: \(pl \e(pl \(*K \e(*K \(mo \e(mo
3595: \(mi \e(mi \(*L \e(*L \(br \e(br
3596: \(eq \e(eq \(*M \e(*M \(dd \e(dd
3597: \(** \e(** \(*N \e(*N \(rh \e(rh
3598: \(sc \e(sc \(*C \e(*C \(lh \e(lh
3599: \(aa \e(aa \(*O \e(*O \(L1 \e(bs
3600: \(ga \e(ga \(*P \e(*P \(or \e(or
3601: \(ul \e(ul \(*R \e(*R \(ci \e(ci
3602: \(sl \e(sl \(*S \e(*S \(lt \e(lt
3603: \(*a \e(*a \(*T \e(*T \(lb \e(lb
3604: \(*b \e(*b \(*U \e(*U \(rt \e(rt
3605: \(*g \e(*g \(*F \e(*F \(rb \e(rb
3606: \(*d \e(*d \(*X \e(*X \(lk \e(lk
3607: \(*e \e(*e \(*Q \e(*Q \(rk \e(rk
3608: \(*z \e(*z \(*W \e(*W \(bv \e(bv
3609: \(*y \e(*y \(sr \e(sr \(lf \e(lf
3610: \(*h \e(*h \(rn \e(rn \(rf \e(rf
3611: \(*i \e(*i \(>= \e(>= \(lc \e(lc
3612: \(*k \e(*k \(<= \e(<= \(rc \e(rc
3613: \(*l \e(*l \(== \e(==
3614: .TE
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.