![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tut.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 tut.ms CVS log | Up to [Research Unix] / researchv10dc / vol2 / troff |
1.1 root 1: .so ../ADM/mac
2: .XX trofftut 223 "A Troff Tutorial"
3: .nr PI .2i
4: .nr PD 2u
5: .de UC
6: \\$3\s-1\\$1\s+1\\$2
7: ..
8: .de BD
9: \&\\$3\f1\\$1\h'-\w'\\$1'u+3u'\\$1\fP\\$2
10: ..
11: .....TM 76-1273-7 39199 39199-11
12: .TL
13: A Troff Tutorial\(dg
14: .AU
15: Brian W. Kernighan
16: .AI
17: .MH
18: .AB
19: .PP
20: .IT Troff
21: is a text-formatting program for typesetters and laser printers.
22: Such devices normally provide multiple fonts,
23: and a substantial number of mathematical symbols
24: and other special characters.
25: Characters can be printed in a range of sizes,
26: and placed anywhere on the page.
27: .PP
28: .IT Troff
29: allows the user full control over fonts,
30: sizes, and character positions,
31: as well as the usual features of a formatter \(em
32: right-margin justification, automatic hyphenation,
33: page titling and numbering, and so on.
34: It also provides macros, arithmetic variables and operations,
35: and conditional testing, for complicated formatting tasks.
36: .PP
37: This document is an introduction to the most basic use of
38: .IT troff .
39: It presents just enough information to enable the user
40: to do simple formatting
41: tasks like making viewgraphs,
42: and to make incremental changes to existing packages
43: of
44: .IT troff
45: commands.
46: .AE
47: .2C
48: .NH
49: Introduction
50: .tr ^.
51: .PP
52: .FS
53: \(dg This is a version of |reference(troff tutorial v7man) revised by B. W. Kernighan.
54: .FE
55: .IT Troff
56: is a text-formatting program,
57: written by J. F. Ossanna,
58: for producing
59: high-quality printed output from phototypesetters and laser printers.
60: This document is an example of
61: .IT troff
62: output.
63: .PP
64: The single most important rule
65: of using
66: .IT troff
67: is
68: not to use it directly, but through some intermediary.
69: In many ways,
70: .IT troff
71: resembles an assembly language \(em
72: a remarkably powerful and flexible one \(em
73: but nonetheless such that many operations must be specified
74: at a level of detail and in a form that is too hard
75: for most people to use effectively.
76: .PP
77: For some special applications, there are programs that provide
78: an interface to
79: .IT troff
80: for the majority of users.
81: For example,
82: .IT eqn
83: |reference(latest eqn)
84: provides an easy to learn language for typesetting mathematics;
85: the
86: .IT eqn
87: user
88: need know no
89: .IT troff
90: whatsoever
91: to typeset mathematics.
92: .IT Tbl
93: |reference(latest tbl)
94: provides the same convenience for producing tables.
95: .PP
96: For producing straight text (which may well contain mathematics or tables), there are a number of ``macro packages''
97: that define formatting rules and operations for specific styles
98: of documents,
99: and reduce the amount of
100: direct contact with
101: .IT troff .
102: In particular, the
103: .CW -ms ,
104: .CW -mpm
105: and
106: .CW -mm
107: packages
108: for Bell Labs internal memoranda and external papers
109: provide most of the facilities needed
110: for a wide range of document preparation.
111: (This paper was prepared with
112: .CW -mpm .)
113: There are also packages for viewgraphs,
114: various journals,
115: and other special applications.
116: Typically you will find these packages easier to use
117: than
118: .IT troff
119: once you get beyond the most trivial operations;
120: you should always consider them first.
121: .PP
122: In the few cases where existing packages don't do the whole job,
123: the solution is
124: .ul
125: not
126: to write an entirely new set of
127: .IT troff
128: instructions from scratch, but to make small changes
129: to adapt packages that already exist.
130: .PP
131: In accordance with this philosophy of letting someone else
132: do the work,
133: the part of
134: .IT troff
135: described here is only a small part of the whole,
136: although it tries to concentrate on the more useful parts.
137: In any case, there is no attempt to be complete.
138: Rather, the emphasis is on showing how to do simple things,
139: and how to make incremental changes to what already exists.
140: The contents of the remaining sections are:
141: .SP .5
142: .nf
143: .in .1i
144: .ta .3i
145: \02. Point sizes; line spacing
146: \03. Fonts and special characters
147: \04. Indents and line lengths
148: \05. Tabs
149: \06. Local motions: drawing lines and characters
150: \07. Strings
151: \08. Introduction to macros
152: \09. Titles, pages and numbering
153: 10. Number registers and arithmetic
154: 11. Macros with arguments
155: 12. Conditionals
156: 13. Environments
157: 14. Diversions
158: Appendix A: Character set
159: .SP .5
160: .in 0
161: .fi
162: .PP
163: To use
164: .IT troff
165: you have to prepare not only the actual text you want printed,
166: but some information that tells
167: .ul
168: how
169: you want it printed.
170: For
171: .IT troff
172: the text
173: and
174: the formatting information are often intertwined quite intimately.
175: Most commands to
176: .IT troff
177: are placed on a line separate from the text itself,
178: beginning with a period (one command per line).
179: For example,
180: .P1
181: Some text.
182: ^ps 14
183: Some more text.
184: .P2
185: will change the `point size',
186: that is,
187: the size of the letters being printed,
188: to `14 point' (one point is 1/72 inch) like this:
189: .P1
190: .ft 1
191: .fi
192: Some text.
193: .ps 14
194: Some more text.
195: .ps 10
196: .P2
197: .PP
198: Occasionally, though,
199: something special occurs in the middle of a line \(em
200: to produce
201: .P1
202: .ft 1
203: Area = \(*p\fIr\fR\|\s8\u2\d\s0
204: .P2
205: you have to type
206: .P1
207: Area = \e(*p\efIr\efR\e\^|\^\es8\eu2\ed\es0
208: .P2
209: (which we will explain shortly).
210: The backslash character
211: .CW \e
212: is used
213: to introduce
214: .IT troff
215: commands and special characters within a line of text.
216: .NH
217: Point Sizes; Line Spacing
218: .PP
219: As mentioned above,
220: the command
221: .CW .ps
222: sets the point size.
223: One point is 1/72 inch,
224: so 6-point characters are at most 1/12 inch high,
225: and 36-point characters are \(12 inch.
226: Different devices provide different sets of sizes;
227: a representative set is shown below.
228: .P1 1
229: .ft 1
230: .ps 6
231: 6 point: Pack my box with five dozen liquor jugs.
232: .ps 7
233: .vs 8p
234: 7 point: Pack my box with five dozen liquor jugs.
235: .vs 9p
236: .ps 8
237: 8 point: Pack my box with five dozen liquor jugs.
238: .vs 10p
239: .ps 9
240: 9 point: Pack my box with five dozen liquor jugs.
241: .vs 11p
242: .ps 10
243: 10 point: Pack my box with five dozen liquor
244: .vs 12p
245: .ps 11
246: 11 point: Pack my box with five dozen
247: .vs 14p
248: .ps 12
249: 12 point: Pack my box with five dozen
250: .vs 16p
251: .ps 14
252: 14 point: Pack my box with five
253: .vs 24p
254: \s1616 point\s18 18 point\s20 20 point
255: .vs 40p
256: \s2222\s24 24\s28 28\s36 36
257: .ps 10
258: .vs 12p
259: .P2
260: .PP
261: If the number after
262: .CW .ps
263: is not a
264: legal size,
265: it is rounded up to the next valid value.
266: If no number follows
267: .CW .ps ,
268: .IT troff
269: reverts to the previous size, whatever it was.
270: .IT troff
271: begins with point size 10,
272: which is usually fine.
273: This document is printed in \n(.s point.
274: .PP
275: The point size can also be changed in the middle of a line
276: or even a word
277: with the in-line command
278: .CW \es .
279: To produce
280: .P1
281: .ft 1
282: \s8UNIX\s10 ran on a \s8PDP-\s1011/45
283: .P2
284: type
285: .P1 0
286: \es8UNIX\es10 ran on a \es8PDP-\es1011/45
287: .P2
288: As above,
289: .CW \es
290: should be followed by a legal point size,
291: except that
292: .CW \es0
293: causes the size to revert to
294: its previous value.
295: Notice that
296: .CW \es1011
297: can be understood correctly as `size 10, followed by an 11', if the size is legal,
298: but not otherwise.
299: Be cautious with similar constructions.
300: .PP
301: Relative size changes are also legal and useful:
302: .P1
303: \es-2UNIX\es+2
304: .P2
305: temporarily decreases the size, whatever it is, by two points, then
306: restores it, producing \s-2UNIX\s+2.
307: Relative size changes have the advantage that the size difference
308: is independent of the starting size of the document.
309: The amount of the relative change is restricted
310: to a single digit.
311: .PP
312: The other parameter that determines what the type looks like
313: is the spacing between lines,
314: which is set independently of the point size.
315: Vertical spacing is measured from the bottom of one line to
316: the bottom of the next.
317: The command to control vertical spacing is
318: .CW .vs .
319: For running text, it is usually best to set the vertical spacing
320: about 20% bigger than the character size.
321: For example, so far in this document, we have used
322: ``10 on 12'', that is,
323: .P1
324: ^ps 10
325: ^vs 12p
326: .P2
327: If we changed to
328: .P1
329: ^ps 10
330: ^vs 10p
331: .P2
332: .vs 10p
333: .ne 3
334: the running text would look like this.
335: After a few lines, you will agree it looks a little cramped.
336: The right vertical spacing is partly a matter of taste, depending on how
337: much text you want to squeeze into a given space,
338: and partly a matter of traditional printing style.
339: By default,
340: .IT troff
341: uses 10 on 12.
342: .PP
343: .vs 14p
344: .ps 12
345: Point size and vertical spacing make a substantial difference in the amount of text
346: per square inch.
347: This is 12 on 14.
348: .ne 2
349: .PP
350: .ne 2
351: .ps 6
352: .vs 7p
353: Point size and vertical spacing make a substantial difference in the amount of text
354: per square inch.
355: For example,
356: 10 on 12 uses about twice as much space as 7 on 8.
357: This is 6 on 7, which is even smaller.
358: It packs a lot more words per line,
359: but you can go blind trying to read it.
360: .PP
361: When used without arguments,
362: .CW .ps
363: and
364: .CW .vs
365: revert to the previous size and vertical spacing
366: respectively.
367: .PP
368: The command
369: .CW .sp
370: is used to get extra vertical space.
371: Unadorned,
372: it gives you one extra blank line (one
373: .CW .vs ,
374: whatever that has been set to).
375: Typically, that's more or less than you want,
376: so
377: .CW .sp
378: can be followed by
379: information about how much space you want \(em
380: .P1
381: ^sp 2i
382: .P2
383: means `two inches of vertical space'.
384: .P1
385: ^sp 2p
386: .P2
387: means `two points of vertical space';
388: and
389: .P1
390: ^sp 2
391: .P2
392: means `two vertical spaces' \(em two of whatever
393: .CW .vs
394: is set to
395: (this can also be made explicit with
396: .CW .sp\ 2v );
397: .IT troff
398: also understands decimal fractions in most places,
399: so
400: .P1
401: ^sp 1.5i
402: .P2
403: is a space of 1.5 inches.
404: These same scale factors can be used after
405: .CW .vs
406: to define line spacing, and in fact after most commands
407: that deal with physical dimensions.
408: .PP
409: It should be noted that all size numbers are converted internally
410: to `machine units', which are much smaller, reflecting the finer
411: resolution of particular output devices.
412: Many laser printers run at 300 units/inch;
413: typesetters are often more than 1000 units/inch.
414: .NH
415: Fonts and Special Characters
416: .PP
417: .IT Troff
418: allows many different fonts at any one time.
419: Normally a family of serif fonts (Times roman, italic and bold),
420: a family of san-serif fonts (Helvetica), and a collection of special characters
421: are available.
422: .P1 .2i
423: .ft R
424: abcdefghijklmnopqrstuvwxyz 0123456789
425: ABCDEFGHIJKLMNOPQRSTUVWXYZ
426: .ft I
427: abcdefghijklmnopqrstuvwxyz 0123456789
428: ABCDEFGHIJKLMNOPQRSTUVWXYZ
429: .ft B
430: abcdefghijklmnopqrstuvwxyz 0123456789
431: ABCDEFGHIJKLMNOPQRSTUVWXYZ
432: .ft BI
433: abcdefghijklmnopqrstuvwxyz 0123456789
434: ABCDEFGHIJKLMNOPQRSTUVWXYZ
435: .sp 3p
436: .ft H
437: abcdefghijklmnopqrstuvwxyz 0123456789
438: ABCDEFGHIJKLMNOPQRSTUVWXYZ
439: .ft HI
440: abcdefghijklmnopqrstuvwxyz 0123456789
441: ABCDEFGHIJKLMNOPQRSTUVWXYZ
442: .ft HB
443: abcdefghijklmnopqrstuvwxyz 0123456789
444: ABCDEFGHIJKLMNOPQRSTUVWXYZ
445: .P2
446: A representative collection of
447: greek, mathematical symbols and miscellaneous other characters are
448: listed in Appendix A.
449: Appendix B shows the font families commonly available on Postscript printers;
450: your mileage may vary.
451: .PP
452: .IT Troff
453: prints in roman unless told otherwise.
454: To switch into bold, use
455: the
456: .CW .ft
457: command
458: .P1
459: ^ft B
460: .P2
461: and for italics,
462: .P1
463: ^ft I
464: .P2
465: To return to roman, use
466: .CW .ft\ R ;
467: to return to the previous font,
468: whatever it was,
469: use either
470: .CW .ft\ P
471: or just
472: .CW .ft .
473: The `underline' command
474: .P1
475: ^ul
476: .P2
477: causes the next input line to print in italics.
478: .CW .ul
479: can be followed by a count to
480: indicate that more than one line is to be italicized.
481: .PP
482: Fonts can also be changed within a line or word
483: with the in-line command
484: .CW \ef :
485: .P1
486: \fBbold\fIface\fR text
487: .P2
488: is produced by
489: .P1
490: \efBbold\efIface\efR text
491: .P2
492: If you want to do this so the previous font, whatever it was,
493: is left undisturbed, insert extra
494: .CW \efP
495: commands, like this:
496: .P1
497: \efBbold\efP\efIface\efP\efR text\efP
498: .P2
499: Because only the immediately previous font is remembered,
500: you have to restore the previous font after each change
501: or you can lose it.
502: The same is true of
503: .CW .ps
504: and
505: .CW .vs
506: when used without an argument.
507: .PP
508: There are many other fonts available besides the standard set.
509: Normally you can just use a font by naming it,
510: but if an entire document is to be printed
511: in a non-standard set of fonts,
512: it is best to mount the fonts explicitly.
513: This tells
514: .IT troff
515: which fonts you will make the most use of.
516: The
517: .CW .fp
518: command
519: .P1
520: ^fp 3 PB
521: .P2
522: says that the Palatino Bold font
523: .ft PB
524: (which looks like this)
525: .ft
526: is mounted on position 3.
527: .PP
528: It is possible to make a document relatively independent
529: of the actual fonts used to print it
530: by using font numbers instead of names;
531: for example,
532: .CW \ef3
533: and
534: .CW ".ft 3
535: mean `whatever font is mounted at position 3',
536: and thus work for any setting.
537: The standard macro packages assume that fonts 1 through 4 contain
538: roman, italic, bold, and bold italic members of a family.
539: .PP
540: There is also a way to get synthetic bold fonts
541: by overstriking letters with a slight offset,
542: with the
543: .CW .bd
544: command;
545: it is illustrated in Section 11.
546: .PP
547: Special characters have four-character names beginning with
548: .CW \e( ;
549: they may be inserted anywhere.
550: For example,
551: .P1
552: .ft 1
553: \(14 + \(12 = \(34
554: .P2
555: is produced by
556: .P1
557: \e(14 + \e(12 = \e(34
558: .P2
559: In particular,
560: greek letters are all of the form
561: .CW \e(*\- ,
562: where
563: .CW -
564: is an upper or lower case roman letter
565: reminiscent of the greek.
566: Thus
567: to get
568: .P1
569: .ft 1
570: \(*S(\(*a\(mu\(*b) \(-> \(if
571: .P2
572: in bare
573: .IT troff
574: we have to type
575: .P1
576: \e(*S(\e(*a\e(mu\e(*b) \e(\(mi> \e(if
577: .P2
578: That line is unscrambled as follows:
579: .P1
580: .ta 1i 2i 3i
581: \e(*S \(*S
582: ( (
583: \e(*a \(*a
584: \e(mu \(mu
585: \e(*b \(*b
586: ) )
587: \e(\(mi> \(->
588: \e(if \(if
589: .P2
590: Appendix A contains a sample of special names.
591: .PP
592: In
593: .IT eqn
594: the same effect can be achieved with the input
595: .P1
596: SIGMA ( alpha times beta ) \-> inf
597: .P2
598: which is less concise, but clearer to the uninitiated.
599: .PP
600: Notice that
601: each
602: four-character name is a single character
603: as far as
604: .IT troff
605: is concerned \(em
606: the
607: `translate' command
608: .P1
609: ^tr \e(mi\e(em
610: .P2
611: is perfectly clear, meaning
612: .P1
613: ^tr \f1\(mi\h'.1m'\(em
614: .P2
615: that is, to translate \(mi into \(em.
616: .PP
617: Some characters are automatically translated into others:
618: grave \(ga and acute \(aa accents (apostrophes) become open and close single quotes
619: `\0';
620: the combination of ``...'' is generally preferable to the double quotes "...".
621: Similarly a typed minus sign becomes a hyphen -.
622: To print an explicit \- sign, use
623: .CW \e- .
624: To print a backslash, use
625: .CW \ee .
626: .NH
627: Indents and Line Lengths
628: .PP
629: .IT Troff
630: starts with a line length of 6.5 inches,
631: too wide for 8\(12\(mu11 paper.
632: To reset the line length,
633: use
634: the
635: .CW .ll
636: command:
637: .P1
638: ^ll 6i
639: .P2
640: As with
641: .CW .sp ,
642: the actual length can be specified in several ways;
643: inches are probably the most intuitive.
644: .PP
645: Output is normally positioned an inch from the left edge of the paper.
646: To reset the default physical left margin (``page offset''),
647: use the
648: .CW .po
649: command.
650: .P1
651: ^po 0
652: .P2
653: sets the offset as far to the left as it will go.
654: .PP
655: The indent command
656: .CW .in
657: causes the left margin to be indented
658: by some specified amount from the page offset.
659: If we use
660: .CW .in
661: to move the left margin in,
662: and
663: .CW .ll
664: to move the right margin to the left,
665: we can
666: make offset blocks of text:
667: .P1
668: ^in 0.3i
669: ^ll \(mi0.3i
670: text to be set into a block
671: ^ll +0.3i
672: ^in \(mi0.3i
673: .P2
674: will create a block that looks like this:
675: .P1
676: .fi
677: .ll -0.3i
678: .ft 1
679: Pater noster qui est in caelis sanctificetur nomen tuum;
680: adveniat regnum tuum; fiat voluntas tua, sicut in caelo,
681: et in terra. ...
682: Amen.
683: .ll +0.3i
684: .P2
685: Notice the use of `+' and `\(mi'
686: to specify the amount of change.
687: These change the previous setting by the specified amount,
688: rather than just overriding it.
689: The distinction is quite important:
690: .CW .ll\ +1i
691: makes lines one inch longer;
692: .CW .ll\ 1i
693: makes them one inch
694: .ul
695: long.
696: .PP
697: With
698: .CW .in ,
699: .CW .ll
700: and
701: .CW .po ,
702: the previous value is used if no argument is specified.
703: .PP
704: To indent a single line, use the `temporary indent'
705: command
706: .CW .ti .
707: For example, all paragraphs in this memo
708: effectively begin with the command
709: .P1
710: ^ti 3
711: .P2
712: Three of what?
713: The default unit for
714: .CW .ti ,
715: as for most horizontally oriented commands
716: .CW .ll , (
717: .CW .in ,
718: .CW .po ),
719: is ems;
720: an em is roughly the width of the letter `m'
721: in the current point size.
722: (Precisely, a em in size
723: .ul
724: p
725: is
726: .ul
727: p
728: points.)
729: Although inches are usually clearer than ems to people who don't set type
730: for a living,
731: ems have a place:
732: they are a measure of size that is proportional to the current point size.
733: If you want to make text that keeps its proportions
734: regardless of point size,
735: you should use ems for all dimensions.
736: Ems can be specified as scale factors directly,
737: as in
738: .CW .ti\ 2.5m .
739: .PP
740: Lines can also be indented negatively
741: if the indent is already positive:
742: .P1
743: ^ti \(mi0.3i
744: .P2
745: causes the next line to be moved back three tenths of an inch.
746: Thus to make a decorative initial capital,
747: we indent the whole paragraph, then move the letter `P' back with
748: a
749: .CW .ti
750: command:
751: .KS
752: .SP .5
753: .ll -0.3i
754: .fi
755: .in +.6i
756: .ti -0.3i
757: .ft 1
758: \s36\v'2'P\v'-2'\s0ater noster qui est in caelis sanctificetur
759: nomen tuum;
760: adveniat regnum tuum;
761: 'in -.3i
762: fiat voluntas tua,
763: sicut in caelo, et in terra. ...
764: Amen.
765: .ll +0.3i
766: .in 0
767: .br
768: .SP .5
769: .KE
770: .LP
771: Of course, there is also some trickery to make the `P'
772: bigger (just a
773: .CW \es36P\es0 ),
774: and to move it
775: down from its normal position
776: (see the section on local motions).
777: .NH
778: Tabs
779: .PP
780: Tabs
781: (the \s8ASCII\s0 `horizontal tab' character)
782: can be used to produce output in columns,
783: or to set the horizontal position of output.
784: Typically
785: tabs are used only in unfilled text.
786: Tab stops are set by default every half inch from the
787: current indent,
788: but
789: can be changed by the
790: .CW .ta
791: command.
792: To set stops every inch, for example,
793: .P1
794: ^ta 1i 2i 3i 4i 5i 6i
795: .P2
796: .PP
797: By default the stops are left-justified
798: (as on a typewriter),
799: but there are also centering and right-adjusting tabs.
800: .PP
801: For a handful of numeric columns, use right-adjusting tabs:
802: .P1
803: ^nf
804: ^ta .5iR 1iR 1.5iR
805: \fItab\f(CW 1\fI tab \f(CW2\fI tab \f(CW3
806: \fItab \f(CW40\fI tab \f(CW50\fI tab \f(CW60
807: \fItab \f(CW700\fI tab \f(CW800\fI tab \f(CW900\f(CW
808: ^fi
809: .P2
810: The
811: .CW R
812: means ``right adjust.''
813: When printed, this will produce
814: .P1 0
815: .ft 1
816: .ta .5iR 1iR 1.5iR
817: 1 2 3
818: 40 50 60
819: 700 800 900
820: .P2
821: If you have many numbers,
822: or if you need more complicated table layout,
823: don't
824: use
825: .IT troff
826: directly;
827: use
828: .IT tbl .
829: .PP
830: It is also possible to fill up tabbed-over space with
831: some character other than blanks by setting the `tab replacement character'
832: with the
833: .CW .tc
834: command:
835: .P1
836: ^ta 1.5i 2.5i
837: ^tc \e(ru (\e(ru is "\(ru")
838: Name \fItab\fR Age \fItab\fR
839: .P2
840: produces
841: .P1 3
842: .ft 1
843: .ta 1.5i 2.5i
844: .tc \(ru
845: Name Age
846: .tc
847: .P2
848: To reset the tab replacement character to a blank, use
849: .CW .tc
850: with no argument.
851: (Lines can also be drawn with the
852: .CW \el
853: command, described in Section 6.)
854: .PP
855: .IT Troff
856: also provides a very general mechanism called `fields'
857: for setting up complicated columns.
858: (This is used by
859: .IT tbl .)
860: We will not go into it in this paper.
861: .NH
862: Local Motions: Drawing lines and characters
863: .PP
864: .sp 10p
865: Remember `Area = \(*pr\u2\d' and the big `P'
866: in the Paternoster.
867: How are they done?
868: .IT Troff
869: provides a host of commands for placing characters of any size
870: at any place.
871: You can use them to draw special characters
872: or to tune your output for a particular appearance.
873: Most of these commands are straightforward, but messy to read
874: and tough to type correctly.
875: .PP
876: If you won't use
877: .IT eqn ,
878: subscripts and superscripts are most easily done with
879: the half-line local motions
880: .CW \eu
881: and
882: .CW \ed .
883: To go back up the page half a point-size, insert a
884: .CW \eu
885: at the desired place;
886: to go down, insert a
887: .CW \ed .
888: .CW \eu \& (
889: and
890: .CW \ed
891: should always
892: be used in pairs, as explained below.)
893: Thus
894: .P1
895: Area = \e(*pr\eu2\ed
896: .P2
897: produces
898: .P1
899: .ft 1
900: Area = \(*pr\u2\d
901: .P2
902: To make the `2' smaller, bracket it with
903: .CW \es\-2
904: and
905: .CW \es0 .
906: Since
907: .CW \eu
908: and
909: .CW \ed
910: refer to the current point size,
911: be sure to put them either both inside or both outside
912: the size changes,
913: or you will get an unbalanced vertical motion.
914: .PP
915: Sometimes the space given by
916: .CW \eu
917: and
918: .CW \ed
919: isn't the right amount.
920: The
921: .CW \ev
922: command can be used to request an arbitrary amount of vertical motion.
923: The in-line command
924: .P1
925: \ev'\f2amount\fP'
926: .P2
927: causes motion up or down the page by the amount specified in
928: `\f2amount\fP'.
929: For example, to move the `P' down, we used
930: .P1 2
931: .ta 1i
932: ^in +0.6i (move paragraph in)
933: ^ll \-0.3i (shorten lines)
934: ^ti \-0.3i (move P back)
935: \ev'2'\es36P\es0\ev'\-2'ater noster qui est
936: in caelis ...
937: .P2
938: A minus sign causes upward motion, while
939: no sign or a plus sign means down the page.
940: Thus
941: .CW \ev'\-2'
942: causes an upward vertical motion
943: of two line spaces.
944: .PP
945: There are many other ways to specify the amount of motion \(em
946: .P1
947: \ev'0.1i'
948: \ev'3p'
949: \ev'\-0.5m'
950: .P2
951: and so on are all legal.
952: Notice that the scale specifier
953: .CW i
954: or
955: .CW p
956: or
957: .CW m
958: goes inside the quotes.
959: Any character can be used in place of the quotes;
960: this is also true of all other
961: .IT troff
962: commands described in this section.
963: .PP
964: Since
965: .IT troff
966: does not take within-the-line vertical motions into account
967: when figuring out where it is on the page,
968: output lines can have unexpected positions
969: if the left and right ends aren't at the same
970: vertical position.
971: Thus
972: .CW \ev ,
973: like
974: .CW \eu
975: and
976: .CW \ed ,
977: should always balance upward vertical motion in a line with
978: the same amount in the downward direction.
979: .PP
980: Arbitrary horizontal motions are also available \(em
981: .CW \eh
982: is like
983: .CW \ev ,
984: except that the default scale factor is ems instead of line spaces.
985: As an example,
986: .P1
987: \eh'\-0.1i'
988: .P2
989: causes a backwards motion of a tenth of an inch.
990: Consider printing the mathematical symbol
991: `>>'.
992: The default spacing is a bit too wide, so
993: .IT eqn
994: replaces this by
995: .P1
996: >\eh'\-0.1m'>
997: .P2
998: to produce >\h'-.1m'>.
999: .PP
1000: Frequently
1001: .CW \eh
1002: is used with the `width function'
1003: .CW \ew
1004: to generate motions equal to the width
1005: of some character string.
1006: The construction
1007: .P1
1008: \ew'thing'
1009: .P2
1010: is a number equal to the width of `thing' in machine units.
1011: All
1012: .IT troff
1013: computations are ultimately done in these units.
1014: To move horizontally the width of an `x',
1015: we can say
1016: .P1
1017: \eh'\ew'x'u'
1018: .P2
1019: As we mentioned above,
1020: the default scale factor for
1021: all horizontal dimensions is
1022: .CW m ,
1023: ems, so here we must have the
1024: .CW u
1025: for machine units,
1026: or the motion produced will be far too large.
1027: .IT Troff
1028: is quite happy with the nested quotes, by the way,
1029: so long as you don't leave any out.
1030: .SP
1031: .PP
1032: There are also several special-purpose
1033: .IT troff
1034: commands for local motion.
1035: .CW \e0
1036: is an unpaddable white space
1037: of the same width as a digit.
1038: `Unpaddable' means that it will never be widened
1039: or split across a line by line justification and filling.
1040: There is also
1041: .CW \e (blank),
1042: .tr ^^
1043: which is an unpaddable character the width of a space,
1044: .CW \e| ,
1045: which is half that width,
1046: .CW \e^ ,
1047: which is one quarter of the width of a space,
1048: and
1049: .CW \e& ,
1050: which has zero width.
1051: .tr ^.
1052: (This last one is useful, for example, in entering
1053: a text line which would otherwise begin with a `.'.)
1054: .PP
1055: The command
1056: .CW \eo ,
1057: used like
1058: .P1
1059: \eo'set of characters'
1060: .P2
1061: causes (up to 9)
1062: characters to be overstruck,
1063: centered on the widest.
1064: This is nice for accents, as in
1065: .P1
1066: m\eo"e\e(aa"long\eo"e\e(ga"ne
1067: .P2
1068: which makes
1069: .P1
1070: .ft 1
1071: m\o"e\(aa"long\o"e\(ga"ne
1072: .P2
1073: The accents are
1074: .CW \e(ga
1075: and
1076: .CW \e(aa ,
1077: or
1078: .CW \e\`
1079: and
1080: .CW \e\' ;
1081: remember that each is just one character to
1082: .IT troff .
1083: .SP
1084: .PP
1085: You can make your own overstrikes with another special convention,
1086: .CW \ez ,
1087: the zero-motion command.
1088: .CW \ezx
1089: suppresses the normal horizontal motion
1090: after printing the single character
1091: .CW x ,
1092: so another character can be laid on top of it.
1093: Although sizes can be changed within
1094: .CW \eo ,
1095: it centers the characters on the widest,
1096: and
1097: there can be no horizontal or vertical motions,
1098: so
1099: .CW \ez
1100: may be the only way to get what you want:
1101: .P1
1102: .sp 2
1103: \s8\z\(sq\s14\z\(sq\s22\z\(sq\s36\(sq
1104: .P2
1105: is produced by
1106: .P1 0
1107: ^sp 2
1108: \es8\ez\e(sq\es14\ez\e(sq\es22\ez\e(sq\es36\e(sq
1109: .P2
1110: The
1111: .CW .sp
1112: is needed to leave room for the result.
1113: .PP
1114: As another example, an extra-heavy semicolon
1115: that looks like
1116: .P1
1117: .ft 1
1118: \s+6\z,\v'-0.25m'.\v'0.25m'\s0 instead of ; or \s+6;\s0
1119: .P2
1120: can be constructed with a big comma and a big period above it:
1121: .P1
1122: \es+6\ez,\ev'\(mi0.25m'.\ev'0.25m'\es0
1123: .P2
1124: `0.25m' is an empirical constant.
1125: .SP
1126: .PP
1127: A more ornate overstrike is given by the bracketing function
1128: .CW \eb ,
1129: which piles up characters vertically,
1130: centered on the current baseline.
1131: Thus we can get big brackets,
1132: constructing them with piled-up smaller pieces:
1133: .P1
1134: .sp
1135: .ne 3
1136: \b'\(lt\(lk\(lb' \b'\(lc\(lf' x \b'\(rc\(rf' \b'\(rt\(rk\(rb'
1137: .sp
1138: .P2
1139: by typing in only this:
1140: .P1 0
1141: .ps -2
1142: \&^sp
1143: \eb'\e(lt\e(lk\e(lb' \eb'\e(lc\e(lf' x \e
1144: \eb'\e(rc\e(rf' \eb'\e(rt\e(rk\e(rb'
1145: .P2
1146: .PP
1147: .IT Troff
1148: also provides a convenient facility for drawing horizontal and vertical
1149: lines of arbitrary length with arbitrary characters.
1150: .CW \el'1i'
1151: draws a line one inch long, like this:
1152: \l'1i'\|.
1153: The length can be followed by
1154: the character to use if the \(ru isn't appropriate;
1155: .CW \el'0.5i.'\&
1156: draws a half-inch line of dots: \l'.5i.'.
1157: The construction
1158: .CW \eL
1159: is analogous to
1160: .CW \el ,
1161: except that it draws a vertical line instead of horizontal.
1162: .NH
1163: Strings
1164: .PP
1165: Obviously if a paper contains a large number of occurrences
1166: of an acute accent over a letter `e',
1167: typing
1168: .CW \eo"e\e\'"
1169: for each \*e
1170: would be a great nuisance.
1171: .PP
1172: Fortunately,
1173: .IT troff
1174: provides a way in which you can store an arbitrary
1175: collection of text in a `string',
1176: and thereafter use the string name as a shorthand
1177: for its contents.
1178: Strings are one of several
1179: .IT troff
1180: mechanisms whose judicious use
1181: lets you type a document
1182: with less effort and organize
1183: it
1184: so that extensive format changes
1185: can be made with few editing changes.
1186: .PP
1187: Strings are defined with the command
1188: .CW .ds .
1189: The line
1190: .P1
1191: \&^ds e \eo"e\e'"
1192: .P2
1193: defines the string
1194: .CW e
1195: to have the value
1196: .CW \eo"e\e\'" .
1197: .PP
1198: A reference to a string is replaced by whatever
1199: text
1200: the string was defined as.
1201: String names may be either one or two characters long,
1202: and are referred to by
1203: .CW \e*x
1204: for one character names or
1205: .CW \e*(xy
1206: for two character names.
1207: Thus to get
1208: .ds e \o"e\*'"
1209: t\*el\*ephone,
1210: given the definition of the string
1211: .CW e
1212: as above,
1213: we can type
1214: .CW t\e*el\e*ephone ,
1215: to produce t\*el\*ephone.
1216: .PP
1217: If a string must begin with blanks, define it as
1218: .P1
1219: \&.ds xx " text
1220: .P2
1221: The double quote signals the beginning of the definition.
1222: There is no trailing quote;
1223: the end of the line terminates the string.
1224: .PP
1225: A string may actually be several lines long;
1226: if
1227: .IT troff
1228: encounters a
1229: .CW \e
1230: at the end of
1231: .ul
1232: any
1233: line, it is thrown away and the next line
1234: added to the current one.
1235: So you can make a long string simply by ending each line
1236: but the last with a backslash:
1237: .P1
1238: \&^ds xx this \e
1239: is a very \e
1240: long string
1241: .P2
1242: .PP
1243: Strings may be defined in terms of other strings, or even in terms of themselves;
1244: we will discuss some of these possibilities later.
1245: .NH
1246: Introduction to Macros
1247: .PP
1248: Before we can go much further in
1249: .IT troff ,
1250: we need to learn a bit about the
1251: macro
1252: facility.
1253: In its simplest form, a macro is just a shorthand notation
1254: quite similar to a string.
1255: Suppose we want every paragraph to start
1256: in exactly the same way \(em
1257: with a space and a temporary indent of two ems:
1258: .P1
1259: ^sp
1260: ^ti +2m
1261: .P2
1262: Then to save typing, we would like to collapse these into
1263: one shorthand line,
1264: a
1265: .IT troff
1266: `command' like
1267: .P1
1268: ^PP
1269: .P2
1270: that would be treated by
1271: .IT troff
1272: exactly as
1273: .P1
1274: ^sp
1275: ^ti +2m
1276: .P2
1277: .CW .PP
1278: is called a
1279: .ul
1280: macro.
1281: The way we tell
1282: .IT troff
1283: what
1284: .CW .PP
1285: means is to
1286: .ul
1287: define
1288: it with the
1289: .CW .de
1290: command:
1291: .P1
1292: ^de PP
1293: ^sp
1294: ^ti +2m
1295: ^^
1296: .P2
1297: The first line names the macro
1298: (we used
1299: .CW .PP ' `
1300: for `paragraph',
1301: and upper case so it wouldn't conflict with
1302: any name that
1303: .IT troff
1304: might
1305: already know about).
1306: The last line
1307: .CW ..\&
1308: marks the end of the definition.
1309: In between is the text,
1310: which is simply inserted whenever
1311: .IT troff
1312: sees the `command'
1313: or macro call
1314: .P1
1315: ^PP
1316: .P2
1317: A macro
1318: can contain any mixture of text and formatting commands.
1319: .PP
1320: The definition of
1321: .CW .PP
1322: has to precede its first use;
1323: undefined macros are simply ignored.
1324: Names are restricted to one or two characters.
1325: .PP
1326: Using macros for commonly occurring sequences of commands
1327: is critically important.
1328: Not only does it save typing,
1329: but it makes later changes much easier.
1330: Suppose we decide that the paragraph indent is too small,
1331: the vertical space is much too big,
1332: and roman font should be forced.
1333: Instead of changing the whole document,
1334: we need only change the definition of
1335: .CW .PP
1336: to
1337: something like
1338: .P1
1339: ^de PP \e" paragraph macro
1340: ^sp 2p
1341: ^ti +3m
1342: ^ft R
1343: ^^
1344: .P2
1345: and the change takes
1346: effect everywhere we used
1347: .CW .PP .
1348: .PP
1349: .CW \e"
1350: is a
1351: .IT troff
1352: command that causes the rest of the line to be ignored.
1353: We use it here to add comments to the macro
1354: definition
1355: (a wise idea once definitions get complicated).
1356: .PP
1357: As another example of macros,
1358: consider these two which start and end a block of offset,
1359: unfilled text, like most of the examples in this paper:
1360: .P1
1361: ^de BS \e" start indented block
1362: ^sp
1363: ^nf
1364: ^in +0.3i
1365: ^ft CW \e" constant width font
1366: ^^
1367: ^de BE \e" end indented block
1368: ^sp
1369: ^ft 1
1370: ^fi
1371: ^in \(mi0.3i
1372: ^^
1373: .P2
1374: Now we can surround text like
1375: .P1
1376: Copy to
1377: John Doe
1378: Richard Roberts
1379: Stanley Smith
1380: .P2
1381: by the commands
1382: .CW .BS
1383: and
1384: .CW .BE ,
1385: and it will come out as it did above.
1386: Notice that we indented by
1387: .CW .in
1388: .CW +0.3i
1389: instead of
1390: .CW .in
1391: .CW 0.3i .
1392: This way we can nest our uses of
1393: .CW .BS
1394: and
1395: .CW .BE
1396: to get blocks within blocks.
1397: .PP
1398: If later on we decide that the indent
1399: should be 0.5i, then it is only necessary to
1400: change the definitions of
1401: .CW .BS
1402: and
1403: .CW .BE ,
1404: not the whole paper.
1405: .NH
1406: Titles, Pages and Numbering
1407: .PP
1408: This is an area where things get tougher,
1409: because nothing is done for you automatically.
1410: Of necessity, some of this section is a cookbook,
1411: to be copied literally until you get some experience.
1412: .PP
1413: Suppose you want a title at the top of each page,
1414: saying just
1415: .sp 3p
1416: .lt 2.8i
1417: .tl '\ \ \ \ left top'center top'right top\ \ \ \ '
1418: .lt
1419: .sp 3p
1420: Unfortunately, this requires work.
1421: .PP
1422: You have to say what the actual title is (easy);
1423: when to print it (easy enough);
1424: and what to do at and around the title line (harder).
1425: Taking these in reverse order,
1426: first we define a macro
1427: .CW .NP
1428: (for `new page') to process
1429: titles and the like at the end of one page
1430: and the beginning of the next:
1431: .P1 .2i
1432: ^de NP
1433: \&'bp
1434: \&'sp 0.5i
1435: \&\&.tl 'left top'center top'right top'
1436: \&'sp 0.3i
1437: \&^^
1438: .P2
1439: To make sure we're at the top of a page,
1440: we issue a `begin page' command
1441: .CW 'bp ,
1442: which causes a skip to top-of-page
1443: (we'll explain the
1444: .CW '
1445: shortly).
1446: Then we space down half an inch,
1447: print the title
1448: (the use of
1449: .CW .tl
1450: should be self explanatory; later we will discuss parameterizing the titles),
1451: space another 0.3 inches,
1452: and we're done.
1453: .PP
1454: To ask for
1455: .CW .NP
1456: at the bottom of each page,
1457: we have to say something like
1458: `when the text is within an inch
1459: of the bottom of the page,
1460: start the processing
1461: for a new page.'
1462: This is done with a `when' command
1463: .CW .wh :
1464: .P1
1465: ^wh \-1i NP
1466: .P2
1467: (No `.' is used before
1468: .CW NP ;
1469: this is simply the name of a macro, not a macro call.)
1470: The minus sign means
1471: `measure up from the bottom of the page',
1472: so
1473: .CW -1i
1474: means `one inch from the bottom'.
1475: .PP
1476: The
1477: .CW .wh
1478: command appears in the input outside the definition of
1479: .CW .NP ;
1480: typically the input would be
1481: .P1
1482: ^de NP
1483: ^^^
1484: ^^
1485: ^wh \-1i NP
1486: .P2
1487: .PP
1488: Now what happens?
1489: As text is actually being output,
1490: .IT troff
1491: keeps track of its vertical position on the page,
1492: and after a line is printed within one inch from the bottom,
1493: the
1494: .CW .NP
1495: macro is activated.
1496: (In the jargon, the
1497: .CW .wh
1498: command sets a
1499: .ul
1500: trap
1501: at the specified place,
1502: which is `sprung' when that point is passed.)
1503: .CW .NP
1504: causes a skip to the top of the next page
1505: (that's what the
1506: .CW 'bp
1507: was for),
1508: then prints the title with the appropriate margins.
1509: .PP
1510: Why
1511: .CW 'bp
1512: and
1513: .CW 'sp
1514: instead of
1515: .CW .bp
1516: and
1517: .CW .sp ?
1518: The answer is that
1519: .CW .sp
1520: and
1521: .CW .bp ,
1522: like several other commands,
1523: cause a
1524: .ul
1525: break
1526: to take place.
1527: That is, all the input text collected but not yet printed
1528: is flushed out as soon as possible,
1529: and the next input line is guaranteed to start
1530: a new line of output.
1531: If we had used
1532: .CW .sp
1533: or
1534: .CW .bp
1535: in the
1536: .CW .NP
1537: macro,
1538: this would cause a break in the middle
1539: of the current output line when a new page is started.
1540: The effect would be to print the left-over part of that line
1541: at the top of the page, followed by the next input line on a new output line.
1542: This is
1543: .ul
1544: not
1545: what we want.
1546: Using
1547: .CW '
1548: instead of
1549: .CW . \&
1550: for a command
1551: tells
1552: .IT troff
1553: that
1554: no break is to take place \(em
1555: the output line
1556: currently being filled
1557: should
1558: .ul
1559: not
1560: be forced out before the space or new page.
1561: .PP
1562: The list of commands that cause a break
1563: is short and natural:
1564: .P1 .1i
1565: ^bp ^br ^ce ^fi ^nf ^sp ^in ^ti
1566: .P2
1567: All others cause
1568: .ul
1569: no
1570: break,
1571: regardless of whether you use a
1572: .CW . \&
1573: or a
1574: .CW ' .
1575: If you really need a break, add a
1576: .CW .br
1577: command at the appropriate place.
1578: .PP
1579: One other thing to beware of \(em
1580: if you're changing fonts or point sizes a lot,
1581: you may find that
1582: if you cross a page boundary
1583: in an unexpected font or size,
1584: your titles come out in that size and font
1585: instead of what you intended.
1586: Furthermore, the length of a title is independent of the current line length,
1587: so titles will come out at the default length of 6.5 inches
1588: unless you change it,
1589: which is done with the
1590: .CW .lt
1591: command.
1592: .PP
1593: There are several ways to fix the problems of point sizes
1594: and fonts in titles.
1595: For the simplest applications, we can change
1596: .CW .NP
1597: to set the proper size and font for the title,
1598: then restore the previous values as shown below.
1599: .KF
1600: .P1 .2i
1601: .ta .8i
1602: ^de NP
1603: \&'bp
1604: \&'sp 0.5i
1605: ^ft R \e" set title font to roman
1606: ^ps 10 \e" and size to 10 point
1607: ^lt 6i \e" and length to 6 inches
1608: ^tl 'left'center'right'
1609: ^ps \e" revert to previous size
1610: ^ft P \e" and to previous font
1611: \&'sp 0.3i
1612: ^^
1613: .P2
1614: .KE
1615: .PP
1616: This version of
1617: .CW .NP
1618: does
1619: .ul
1620: not
1621: work if the fields in the
1622: .CW .tl
1623: command contain size or font changes.
1624: To cope with that
1625: requires
1626: .IT troff 's
1627: `environment' mechanism,
1628: which we will discuss in Section 13.
1629: .PP
1630: To get a footer at the bottom of a page,
1631: you can modify
1632: .CW .NP
1633: so it does
1634: some processing before
1635: the
1636: .CW 'bp
1637: command,
1638: or split the job into a footer macro invoked
1639: at the bottom margin and a header macro invoked
1640: at the top of the page.
1641: These variations are left as exercises.
1642: .SP
1643: .PP
1644: Output page numbers are computed automatically
1645: as each page is produced (starting at 1),
1646: but no numbers are printed unless you ask for them explicitly.
1647: To get page numbers printed,
1648: include the character
1649: .CW %
1650: in the
1651: .CW .tl
1652: line at
1653: the position where you want the number to appear.
1654: For example
1655: .P1
1656: ^tl ''- % -''
1657: .P2
1658: centers the page number inside hyphens, as on this page.
1659: You can set the page number at any time
1660: with either
1661: .CW .bp\ n ,
1662: which immediately starts a new page numbered
1663: .CW n ,
1664: or with
1665: .CW .pn\ n ,
1666: which sets the page number for the next page
1667: but doesn't cause a skip to the new page.
1668: Again,
1669: .CW .bp\ +n
1670: sets the page number to
1671: .CW n
1672: more than its current value;
1673: .CW .bp
1674: means
1675: .CW .bp\ +1 .
1676: .NH
1677: Number Registers and Arithmetic
1678: .PP
1679: .IT Troff
1680: has a facility for doing arithmetic,
1681: and for defining and using variables with numeric values,
1682: called
1683: .ul
1684: number registers.
1685: Number registers, like strings and macros, can be useful in setting up a document
1686: so it is easy to change later.
1687: And of course they serve for any sort of arithmetic computation.
1688: .PP
1689: Like strings, number registers have one or two character names.
1690: They are set by the
1691: .CW .nr
1692: command,
1693: and are referenced anywhere by
1694: .CW \enx
1695: (one character name) or
1696: .CW \en(xy
1697: (two character name).
1698: .PP
1699: There are quite a few pre-defined number registers maintained by
1700: .IT troff ,
1701: among them
1702: .CW %
1703: for the current page number;
1704: .CW nl
1705: for the current vertical position on the page;
1706: .CW dy ,
1707: .CW mo
1708: and
1709: .CW yr
1710: for the current day, month and year; and
1711: .CW .s
1712: and
1713: .CW .f
1714: for the current size and font.
1715: (The font is a number from 1 to typically around 10.)
1716: Any of these can be used in computations like any other register,
1717: but some, like
1718: .CW .s
1719: and
1720: .CW .f ,
1721: cannot be changed with
1722: .CW .nr .
1723: .PP
1724: As an example of the use of number registers,
1725: in the
1726: .CW -ms
1727: macro package,
1728: most significant parameters are defined in terms of the values
1729: of a handful of number registers.
1730: These include the point size for text, the vertical spacing,
1731: and the line and title lengths.
1732: To set the point size and vertical spacing for the following paragraphs, for example, a user may say
1733: .P1
1734: ^nr PS 9
1735: ^nr VS 11
1736: .P2
1737: The paragraph macro
1738: .CW .PP
1739: is defined (roughly) as follows:
1740: .P1
1741: .ta 1i
1742: ^de PP
1743: ^ps \e\en(PS \e" reset size
1744: ^vs \e\en(VSp \e" spacing
1745: ^ft 1 \e" font
1746: ^sp 0.5v \e" half a line
1747: ^ti +3m
1748: ^^
1749: .P2
1750: This sets the font to font 1 and the point size and line spacing
1751: to whatever values are stored in the number registers
1752: .CW PS
1753: and
1754: .CW VS .
1755: .PP
1756: Why are there two backslashes?
1757: This is the eternal problem of how to quote a quote.
1758: When
1759: .IT troff
1760: originally reads the macro definition,
1761: it peels off one backslash
1762: to see what's coming next.
1763: To ensure that another is left in the definition when the
1764: macro is
1765: .ul
1766: used,
1767: we have to put in two backslashes in the definition.
1768: If only one backslash is used,
1769: point size and vertical spacing will be frozen at the time the macro
1770: is defined, not when it is used.
1771: .PP
1772: Protecting by an extra layer of backslashes
1773: is only needed for
1774: .CW \en ,
1775: .CW \e* ,
1776: .CW \e$
1777: (which we haven't come to yet),
1778: and
1779: .CW \e
1780: itself.
1781: Things like
1782: .CW \es ,
1783: .CW \ef ,
1784: .CW \eh ,
1785: .CW \ev ,
1786: and so on do not need an extra backslash,
1787: since they are converted by
1788: .IT troff
1789: to an internal code immediately upon being seen.
1790: .SP
1791: .PP
1792: Arithmetic expressions can appear anywhere that
1793: a number is expected.
1794: As a trivial example,
1795: .P1
1796: ^nr PS \e\en(PS\-2
1797: .P2
1798: decrements
1799: .CW PS
1800: by 2.
1801: Expressions can use the arithmetic operators +, \-, *, /, % (mod),
1802: the relational operators >, >=, <, <=, =, and != (not equal),
1803: and parentheses.
1804: .PP
1805: Although the arithmetic we have done so far
1806: has been straightforward,
1807: more complicated things are somewhat tricky.
1808: First,
1809: number registers hold only integers.
1810: .IT troff
1811: arithmetic uses truncating integer division, just like Fortran.
1812: Second, in the absence of parentheses,
1813: evaluation is done left-to-right
1814: without any operator precedence
1815: (including relational operators).
1816: Thus
1817: .P1
1818: 7*\-4+3/13
1819: .P2
1820: becomes `\-1'.
1821: Number registers can occur anywhere in an expression,
1822: and so can scale indicators like
1823: .CW p ,
1824: .CW i ,
1825: .CW m ,
1826: and so on (but no spaces).
1827: Although integer division causes truncation,
1828: each number and its scale indicator is converted
1829: to machine units before any arithmetic is done,
1830: so
1831: .CW 1i/2u
1832: evaluates to
1833: 0.5i
1834: correctly.
1835: .PP
1836: The scale indicator
1837: .CW u
1838: often has to appear
1839: when you wouldn't expect it \(em
1840: in particular, when arithmetic is being done
1841: in a context that implies horizontal or vertical dimensions.
1842: For example,
1843: .P1
1844: ^ll 7/2i
1845: .P2
1846: would seem obvious enough \(em
1847: 3\(12 inches.
1848: Sorry.
1849: Remember that the default units for horizontal parameters like
1850: .CW .ll
1851: are ems.
1852: That's really `7 ems / 2 inches',
1853: and when translated into machine units, it becomes zero.
1854: How about
1855: .P1
1856: ^ll 7i/2
1857: .P2
1858: Sorry, still no good \(em
1859: the `2' is `2 ems', so `7i/2' is small,
1860: although not zero.
1861: You
1862: .ul
1863: must
1864: use
1865: .P1
1866: ^ll 7i/2u
1867: .P2
1868: So again, a safe rule is to
1869: attach a scale indicator to every number,
1870: even constants.
1871: .PP
1872: For arithmetic done within a
1873: .CW .nr
1874: command,
1875: there is no implication of horizontal or vertical dimension,
1876: so the default units are `units',
1877: and
1878: .CW 7i/2
1879: and
1880: .CW 7i/2u
1881: mean the same thing.
1882: Thus
1883: .P1
1884: ^nr ll 7i/2
1885: ^ll \e\en(llu
1886: .P2
1887: does just what you want,
1888: so long as you
1889: don't forget the
1890: .CW u
1891: on the
1892: .CW .ll
1893: command.
1894: .NH
1895: Macros with arguments
1896: .PP
1897: The next step is to define macros that can change from one
1898: use to the next
1899: according to parameters supplied as arguments.
1900: To make this work, we need two things.
1901: First, when we define the macro, we have to indicate that some
1902: parts of it will be provided as arguments when the macro is called.
1903: Then when the macro is
1904: called
1905: we have to provide actual arguments
1906: to be plugged into the definition.
1907: .PP
1908: Let us illustrate by defining a macro
1909: .CW .SM
1910: that will print its argument two points
1911: smaller than the surrounding text.
1912: That is, the macro call
1913: .P1
1914: ^SM UNIX
1915: .P2
1916: will produce
1917: \s-2UNIX\s0
1918: instead of UNIX.
1919: .PP
1920: The definition of
1921: .CW .SM
1922: is
1923: .P1
1924: ^de SM
1925: \es\-2\e\e$1\es+2
1926: ^^
1927: .P2
1928: Within a macro definition,
1929: the symbol
1930: .CW \e\e$n
1931: refers to the
1932: .CW n th
1933: argument
1934: that the macro was called with.
1935: Thus
1936: .CW \e\e$1
1937: is the string to be placed in a smaller point
1938: size when
1939: .CW .SM
1940: is called.
1941: .PP
1942: As a slightly more complicated version, the following definition of
1943: .CW .SM
1944: permits optional second and third arguments
1945: that will be printed in the normal size:
1946: .P1
1947: ^de SM
1948: \e\e$3\es\-2\e\e$1\es+2\e\e$2
1949: ^^
1950: .P2
1951: Arguments not provided when the macro is called are treated
1952: as empty,
1953: so
1954: .P1
1955: ^SM UNIX ),
1956: .P2
1957: produces
1958: .UC UNIX ),
1959: while
1960: .P1
1961: ^SM UNIX ). (
1962: .P2
1963: produces
1964: .UC UNIX ). (
1965: It is convenient to reverse
1966: the order of arguments because trailing punctuation
1967: is much more common than leading.
1968: .PP
1969: By the way, the number of arguments that a macro was called with
1970: is available in number register
1971: .CW .$ .
1972: .PP
1973: The following macro
1974: .CW ^BD
1975: is used to make
1976: `bold roman',
1977: .BD like
1978: .BD this
1979: .BD phrase.
1980: It combines horizontal motions, width computations,
1981: and argument rearrangement.
1982: .P1 .05i
1983: \&.de BD
1984: \e&\e\e$3\ef1\e\e$1\eh'-\ew'\e\e$1'u+3u'\e\e$1\efP\e\e$2
1985: \&..
1986: .P2
1987: The
1988: .CW \eh
1989: and
1990: .CW \ew
1991: commands need no extra backslash, as we discussed above.
1992: The
1993: .CW \e&
1994: is there in case the argument begins with a period.
1995: .SP
1996: .PP
1997: Two backslashes are needed with the
1998: .CW \e\e$n
1999: commands, though,
2000: to protect one of them when the macro is
2001: being defined.
2002: Perhaps a second example will make this clearer.
2003: Consider a macro called
2004: .CW .NH
2005: which
2006: produces numbered headings rather like those in this paper,
2007: with the sections numbered automatically,
2008: and the title in bold in a smaller size.
2009: The use is
2010: .P1
2011: ^NH "Section title ..."
2012: .P2
2013: (If the argument to a macro is to contain blanks,
2014: then it must be
2015: .ul
2016: surrounded
2017: by double quotes,
2018: unlike a string, where only one leading quote is permitted.)
2019: .PP
2020: Here is the definition of the
2021: .CW .NH
2022: macro:
2023: .P1 .1i
2024: .ta .75i 1.15i
2025: ^nr NH 0 \e" initialize section number
2026: ^de NH
2027: ^sp 0.3i
2028: ^ft B
2029: ^nr NH \e\en(NH+1 \e" increment number
2030: ^ps \e\en(PS\-1 \e" decrease PS
2031: \e\en(NH. \e\e$1 \e" number. title
2032: ^ps \e\en(PS \e" restore PS
2033: ^sp 0.3i
2034: ^ft R
2035: ^^
2036: .P2
2037: The section number is kept in number register
2038: .CW NH ,
2039: which is incremented each
2040: time just before it is used.
2041: (A number register, but not a string, may have the same name as a macro
2042: without conflict.)
2043: .PP
2044: We used
2045: .CW \e\en(NH
2046: instead of
2047: .CW \en(NH
2048: and
2049: .CW \e\en(PS
2050: instead of
2051: .CW \en(PS .
2052: If we had used
2053: .CW \en(NH ,
2054: we would get the value of the register at the time the macro was
2055: .ul
2056: defined,
2057: not at the time it was
2058: .ul
2059: used.
2060: If that's what you want, fine,
2061: but not here.
2062: Similarly,
2063: by using
2064: .CW \e\en(PS ,
2065: we get the point size at the time the macro is called.
2066: .SP
2067: .PP
2068: As an example that does not involve numbers,
2069: recall our
2070: .CW .NP
2071: macro which had a
2072: .P1
2073: ^tl 'left'center'right'
2074: .P2
2075: We could make these into parameters by using instead
2076: .P1
2077: ^tl '\e\e*(LT'\e\e*(CT'\e\e*(RT'
2078: .P2
2079: so the title comes from three strings called
2080: .CW LT ,
2081: .CW CT
2082: and
2083: .CW RT .
2084: If these are empty, then the title will be a blank line.
2085: Normally
2086: .CW CT
2087: would be set with something like
2088: .P1
2089: \&^ds CT - % -
2090: .P2
2091: to give just the page number between hyphens,
2092: but a user could supply private definitions for
2093: any of the strings.
2094: .NH
2095: Conditionals
2096: .PP
2097: Suppose we want the
2098: .CW .NH
2099: macro to leave two extra inches of space just before section 1,
2100: but nowhere else.
2101: The cleanest way to do that is to test inside the
2102: .CW .NH
2103: macro
2104: whether
2105: the section number is 1,
2106: and add some space if it is.
2107: The
2108: .CW .if
2109: command provides the conditional test
2110: that we can add
2111: just before the heading line is output:
2112: .P1 0
2113: ^if \e\en(NH=1 ^sp 2i \e" 1st section only
2114: .P2
2115: .PP
2116: The condition after the
2117: .CW .if
2118: can be any arithmetic or logical expression.
2119: If the condition is logically true, or arithmetically greater than zero,
2120: the rest of the line is treated as if
2121: it were text \(em
2122: here a command.
2123: If the condition is false, or zero or negative,
2124: the rest of the line is skipped.
2125: .PP
2126: It is possible to do more than one command if a condition is true.
2127: Suppose several operations are to be done before section 1.
2128: One possibility is to define a macro
2129: .CW .S1
2130: and invoke it
2131: if we are about to do section 1
2132: (as determined by an
2133: .CW .if ).
2134: .P1
2135: ^de S1
2136: --- processing for section 1 ---
2137: ^^
2138: ^de NH
2139: ^^^
2140: ^if \e\en(NH=1 ^S1
2141: ^^^
2142: ^^
2143: .P2
2144: .PP
2145: An alternate way is to use the
2146: extended form of the
2147: .CW .if ,
2148: like this:
2149: .P1
2150: ^if \e\en(NH=1 \e{--- processing
2151: for section 1 ----\e}
2152: .P2
2153: The braces
2154: .CW \e{
2155: and
2156: .CW \e}
2157: must occur in the positions shown
2158: or you will get unexpected extra lines in your output.
2159: .IT Troff
2160: also provides
2161: an `if-else' construction,
2162: which we will not go into here.
2163: .PP
2164: A condition can be negated by preceding it with
2165: .CW ! ;
2166: we get the same effect as above (but less clearly) by using
2167: .P1
2168: ^if !\e\en(NH>1 ^S1
2169: .P2
2170: .PP
2171: There are a handful of
2172: other conditions that can be tested with
2173: .CW .if .
2174: For example, is the current page even or odd?
2175: .P1
2176: ^if e ^tl ''even page title''
2177: ^if o ^tl ''odd page title''
2178: .P2
2179: gives facing pages different titles
2180: when used inside an appropriate new page macro.
2181: .PP
2182: Two other conditions
2183: are
2184: .CW t
2185: and
2186: .CW n ,
2187: which tell you whether the formatter is
2188: .IT troff
2189: or
2190: .IT nroff .
2191: .P1
2192: ^if t troff stuff ...
2193: ^if n nroff stuff ...
2194: .P2
2195: .PP
2196: Finally, string comparisons may be made in an
2197: .CW .if :
2198: .P1
2199: ^if 'string1'string2' stuff
2200: .P2
2201: does `stuff' if
2202: .CW string1
2203: is the same as
2204: .CW string2 .
2205: The character separating the strings can be anything
2206: reasonable that is
2207: not contained in either string.
2208: The strings themselves can reference strings with
2209: .CW \e* ,
2210: arguments with
2211: .CW \e$ ,
2212: and so on.
2213: .NH
2214: Environments
2215: .PP
2216: As we mentioned, there is a potential problem
2217: when going across a page boundary:
2218: parameters like size and font
2219: for a page title may well be different from those
2220: in effect in the text when the page boundary occurs.
2221: .IT Troff
2222: provides a very general way to deal with this and
2223: similar situations.
2224: There are three `environments',
2225: each of which has independently settable versions of
2226: many of the parameters associated with processing,
2227: including size, font, line and title lengths,
2228: fill/nofill mode, tab stops, and even partially collected lines.
2229: Thus the titling problem may be readily solved by processing the main text
2230: in one environment and titles in a separate one
2231: with its own suitable parameters.
2232: .PP
2233: The command
2234: .CW .ev\ n
2235: shifts to environment
2236: .CW n ;
2237: .CW n
2238: must be 0, 1 or 2.
2239: The command
2240: .CW .ev
2241: with no argument returns to the
2242: previous environment.
2243: Environment names are maintained in a stack, so calls
2244: for different environments may be nested and unwound consistently.
2245: .PP
2246: Suppose we say that the main text is processed in environment 0,
2247: which is where
2248: .IT troff
2249: begins by default.
2250: Then we can modify the new page macro
2251: .CW .NP
2252: to process titles in environment 1 like this:
2253: .P1 2
2254: ^de NP
2255: ^ev 1 \e" shift to new environment
2256: ^lt 6i \e" set parameters here
2257: ^ft 1
2258: ^ps 10
2259: \&... any other processing ...
2260: ^ev \e" return to prev environment
2261: ^^
2262: .P2
2263: It is also possible to initialize the parameters for an environment
2264: outside the
2265: .CW .NP
2266: macro,
2267: but the version shown keeps all the processing in one place
2268: and is thus easier to understand and change.
2269: .NH
2270: Diversions
2271: .PP
2272: There are numerous occasions in page layout when it is necessary to store some text
2273: for a period of time without actually printing it.
2274: Footnotes are one obvious example:
2275: the text of the footnote usually appears in the input well before the place
2276: on the page where it is to be printed is reached.
2277: In fact,
2278: the place where it is output normally depends on how big it is,
2279: which implies that there must be a way
2280: to process the footnote at least
2281: enough to decide its size
2282: without printing it.
2283: .PP
2284: .IT Troff
2285: provides a mechanism called a diversion
2286: for doing this processing.
2287: Any part of the output may be diverted into a macro instead
2288: of being printed,
2289: and then at some convenient time the macro may be put back into
2290: the input.
2291: .PP
2292: The command
2293: .CW .di\ xy
2294: begins a diversion \(em all subsequent output is collected into the macro
2295: .CW xy
2296: until the command
2297: .CW .di
2298: with no arguments is encountered.
2299: This terminates the diversion.
2300: The processed text is available at any time thereafter, simply
2301: by giving the command
2302: .P1
2303: ^xy
2304: .P2
2305: The vertical size of the last finished diversion is contained in
2306: the built-in number register
2307: .CW dn .
2308: .PP
2309: As a simple example,
2310: suppose we want to implement a `keep-release'
2311: operation,
2312: so that text between the commands
2313: .CW .KS
2314: and
2315: .CW .KE
2316: will not be split across a page boundary
2317: (as for a figure or table).
2318: Clearly, when a
2319: .CW .KS
2320: is encountered, we have to begin diverting
2321: the output so we can find out how big it is.
2322: Then when a
2323: .CW .KE
2324: is seen, we decide
2325: whether the diverted text will fit on the current page,
2326: and print it either there if it fits, or at the top of the next page if it doesn't.
2327: So:
2328: .P1 2
2329: .ta .6i
2330: ^de KS \e" start keep
2331: ^br \e" start fresh line
2332: ^ev 1 \e" collect in new environment
2333: ^fi \e" make it filled text
2334: ^di XX \e" collect in XX
2335: ^^
2336: .P2
2337: .P1 2
2338: .ta .6i
2339: ^de KE \e" end keep
2340: ^br \e" get last partial line
2341: ^di \e" end diversion
2342: ^if \e\en(dn>=\e\en(.t .bp \e" bp if too big
2343: ^nf \e" bring it back in no-fill
2344: ^XX \e" text
2345: ^ev \e" return to normal environment
2346: ^^
2347: .P2
2348: Recall that number register
2349: .CW nl
2350: is the current position
2351: on the output page.
2352: Since output was being diverted, this remains
2353: at its value when the diversion started.
2354: .CW dn
2355: is the amount of text in the diversion;
2356: .CW .t
2357: (another built-in register)
2358: is the distance to the next trap,
2359: which we assume is at the bottom margin of the page.
2360: If the diversion is large enough to go past the trap,
2361: the
2362: .CW .if
2363: is satisfied, and
2364: a
2365: .CW .bp
2366: is issued.
2367: In either case, the diverted output is then brought back with
2368: .CW .XX .
2369: It is essential to bring it back in no-fill mode so
2370: .IT troff
2371: will do no further processing on it.
2372: .PP
2373: This is not the most general keep-release,
2374: nor is it robust in the face of all conceivable inputs,
2375: but it would require more space than we have here to write it
2376: in full generality.
2377: This section is not intended
2378: to teach everything about diversions,
2379: but to sketch out enough that you can read
2380: existing macro packages with some comprehension.
2381: .NH
2382: Acknowledgements
2383: .PP
2384: I am deeply indebted to the late J. F. Ossanna,
2385: the author of
2386: .IT troff ,
2387: for his repeated patient explanations
2388: of
2389: fine points,
2390: and for his continuing willingness to
2391: adapt
2392: .IT troff
2393: to make other uses easier.
2394: .PP
2395: I am also grateful to Jim Blinn, Ted Dolotta,
2396: Doug McIlroy, Mike Lesk and Joel Sturman
2397: for helpful comments on this paper.
2398: .NH
2399: References
2400: .LP
2401: |reference_placement
2402: .sp 100
2403: .BP
2404: .1C
2405: .........
2406: .SH
2407: Appendix A: Character Set
2408: .SP .5
2409: .PP
2410: Different output devices support different character sets,
2411: although there is considerable commonality.
2412: To get the one on the left, type the
2413: four-character name on the right.
2414: .TS
2415: center;
2416: l l6fCW l l6fCW l l6fCW l l6fCW.
2417: \(ff \e(ff \(fi \e(fi \(fl \e(fl \(Fi \e(Fi \(Fl \e(Fl
2418: \(ru \e(ru \(em \e(em \(14 \e(14 \(12 \e(12 \(34 \e(34
2419: \(co \e(co \(de \e(de \(dg \e(dg \(fm \e(fm \(ct \e(ct
2420: \(rg \e(rg \(bu \e(bu \(sq \e(sq \(hy \e(hy
2421: .TE
2422: .PP
2423: The following are special-font characters:
2424: .TS
2425: center;
2426: l l6fCW l l6fCW l l6fCW l l6fCW.
2427: \(pl \e(pl \(mi \e(mi \(mu \e(mu \(di \e(di
2428: \(eq \e(eq \(== \e(== \(>= \e(>= \(<= \e(<=
2429: \(!= \e(!= \(+- \e(+- \(no \e(no \(sl \e(sl
2430: \(ap \e(ap \(~= \e(~= \(pt \e(pt \(gr \e(gr
2431: \(-> \e(-> \(<- \e(<- \(ua \e(ua \(da \e(da
2432: \(is \e(is \(pd \e(pd \(if \e(if \(sr \e(sr
2433: \(sb \e(sb \(sp \e(sp \(cu \e(cu \(ca \e(ca
2434: \(ib \e(ib \(ip \e(ip \(mo \e(mo \(es \e(es
2435: \(aa \e(aa \(ga \e(ga \(ci \e(ci \(L1 \e(L1
2436: \(sc \e(sc \(dd \e(dd \(lh \e(lh \(rh \e(rh
2437: \(lt \e(lt \(rt \e(rt \(lc \e(lc \(rc \e(rc
2438: \(lb \e(lb \(rb \e(rb \(lf \e(lf \(rf \e(rf
2439: \(lk \e(lk \(rk \e(rk \(bv \e(bv \(ts \e(ts
2440: \(br \e(br \(or \e(or \(ul \e(ul \(rn \e(rn
2441: \(** \e(**
2442: .TE
2443: .PP
2444: These
2445: four
2446: characters also have two-character names.
2447: The \' is the apostrophe on terminals;
2448: the \` is the other quote mark.
2449: .TS
2450: center;
2451: l l6fCW l l6fCW l l6fCW l l6fCW.
2452: \' \e\(aa \` \e\(ga \(mi \e\(mi \(em \e(em
2453: .TE
2454: .PP
2455: For greek, precede the roman letter by
2456: .CW \e(*
2457: to get the corresponding greek;
2458: for example,
2459: .CW \e(*a
2460: is
2461: \(*a.
2462: .sp
2463: .in 0.5i
2464: .nf
2465: .cs R 36
2466: abgdezyhiklmncoprstufxqw
2467: \(*a\(*b\(*g\(*d\(*e\(*z\(*y\(*h\(*i\(*k\(*l\(*m\(*n\(*c\(*o\(*p\(*r\(*s\(*t\(*u\(*f\(*x\(*q\(*w
2468: .sp
2469: ABGDEZYHIKLMNCOPRSTUFXQW
2470: \(*A\(*B\(*G\(*D\(*E\(*Z\(*Y\(*H\(*I\(*K\(*L\(*M\(*N\(*C\(*O\(*P\(*R\(*S\(*T\(*U\(*F\(*X\(*Q\(*W
2471: .cs R
2472: .in 0
2473: .fi
2474: .BP
2475: .2C
2476: .SH
2477: Appendix B: Some Common Fonts
2478: .LP
2479: The following fonts are currently available on our Laserwriter II printers.
2480: The magic
2481: .I troff
2482: short name is given as well as the name in the font catalog.
2483: .de XX
2484: .KS
2485: .SP .5
2486: \f1\\$1 (\f(CW\\$2\f1)
2487: .br
2488: .nf
2489: .ft \\$2
2490: abcdefghijklmnopqrstuvwxyz 0123456789
2491: ABCDEFGHIJKLMNOPQRSTUVWXYZ
2492: .ft
2493: .KE
2494: ..
2495: .XX AvantGarde-BookOblique AI
2496: .XX AvantGarde-Book AR
2497: .XX AvantGarde-DemiOblique AX
2498: .XX AvantGarde-Demi AB
2499: .XX Bookman-DemiItalic KX
2500: .XX Bookman-Demi KB
2501: .XX Bookman-LightItalic KI
2502: .XX Bookman-Light KR
2503: .XX Courier-BoldOblique CX
2504: .XX Courier-Bold CB
2505: .XX Courier-Oblique CI
2506: .XX Courier CW
2507: .XX Helvetica-BoldOblique HX
2508: .XX Helvetica-Bold HB
2509: .XX Helvetica-Narrow-BoldOblique Hx
2510: .XX Helvetica-Narrow-Bold Hb
2511: .XX Helvetica-Narrow-Oblique Hi
2512: .XX Helvetica-Narrow Hr
2513: .XX Helvetica-Oblique HI
2514: .XX Helvetica H
2515: .XX NewCenturySchlbk-BoldItalic NX
2516: .XX NewCenturySchlbk-Bold NB
2517: .XX NewCenturySchlbk-Italic NI
2518: .XX NewCenturySchlbk-Roman NR
2519: .XX Palatino-BoldItalic PX
2520: .XX Palatino-Bold PB
2521: .XX Palatino-Italic PI
2522: .XX Palatino-Roman PA
2523: .XX Times-BoldItalic BI
2524: .XX Times-Bold B
2525: .XX Times-Italic I
2526: .XX Times-Roman R
2527: .XX ZapfChancery-MediumItalic ZI
2528: .ig
2529: show dingbats here
2530: ..
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.