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