14.  Diversions

      There are numerous occasions in page layout when it is necessary to store some text for a period of time without actually printing it. Footnotes are the most obvious example: the text of the footnote usually appears in the input well before the place on the page where it is to be printed is reached. In fact, the place where it is output normally depends on how big it is, which implies that there must be a way to process the footnote at least enough to decide its size without printing it.

      troff provides a mechanism called a diversion for doing this processing. Any part of the output may be diverted into a macro instead of being printed, and then at some convenient time the macro may be put back into the input.

      The command .di xybegins a diversion _ all subsequent output is collected into the macro xyuntil the command .diwith no arguments is encountered. This terminates the diversion. The processed text is available at any time thereafter, simply by giving the command ^xy
The vertical size of the last finished diversion is contained in
the built-in number register
dn

      As a simple example, suppose we want to implement a `keep-release' operation, so that text between the commands .KSand .KEwill not be split across a page boundary (as for a figure or table). Clearly, when a .KSis encountered, we have to begin diverting the output so we can find out how big it is. Then when a .KEis seen, we decide whether the diverted text will fit on the current page, and print it either there if it fits, or at the top of the next page if it doesn't. So: ^de KS \" start keep
^br \" start fresh line
^ev 1 \" collect in new environment
^fi \" make it filled text
^di XX \" collect in XX
^^
^de KE \" end keep
^br \" get last partial line
^di \" end diversion
^if \\n(dn>=\\n(.t .bp \" bp if doesn't fit
^nf \" bring it back in no-fill
^XX \" text
^ev \" return to normal environment
^^
Recall that number register
nlis the current position
on the output page.
Since output was being diverted, this remains
at its value when the diversion started.
dnis the amount of text in the diversion;
.t(another built-in register)
is the distance to the next trap,
which we assume is at the bottom margin of the page.
If the diversion is large enough to go past the trap,
the
.ifis satisfied, and
a
.bpis issued.
In either case, the diverted output is then brought back with
.XXIt is essential to bring it back in no-fill mode so
troff
will do no further processing on it.

      This is not the most general keep-release, nor is it robust in the face of all conceivable inputs, but it would require more space than we have here to write it in full generality. This section is not intended to teach everything about diversions, but to sketch out enough that you can read existing macro packages with some comprehension.

Acknowledgements

      I am deeply indebted to J. F. Ossanna, the author of troff, for his repeated patient explanations of fine points, and for his continuing willingness to adapt troff to make other uses easier. I am also grateful to Jim Blinn, Ted Dolotta, Doug McIlroy, Mike Lesk and Joel Sturman for helpful comments on this paper.

References

[1]

J. F. Ossanna, NROFF/TROFF User's Manual, Bell Laboratories Computing Science Technical Report 54, 1976.

[2]

B. W. Kernighan, A System for Typesetting Mathematics _ User's Guide (Second Edition), Bell Laboratories Computing Science Technical Report 17, 1977.

[3]

M. E. Lesk, TBL _ A Program to Format Tables, Bell Laboratories Computing Science Technical Report 49, 1976.

[4]

M. E. Lesk, Typing Documents on UNIX, Bell Laboratories, 1978.

[5]

J. R. Mashey and D. W. Smith, PWB/MM _ Programmer's Workbench Memorandum Macros, Bell Laboratories internal memorandum.

Appendix A: Phototypesetter Character Set

These characters exist in roman, italic, and bold. To get the one on the left, type the four-character name on the right.

ff \(ff fi \(fi fl \(fl ffi \(Fi ffl \(Fl
_ \(ru -- \(em ¼ \(14 ½ \(12 ¾ \(34
© \(co ° \(de ** \(dg ' \(fm ¢ \(ct
® \(rg + \(bu o \(sq ­ \(hy
(In bold, \(sq is o.)

The following are special-font characters:

+ \(pl - \(mi × \(mu ÷ \(di
= \(eq == \(== >= \(>= <= \(<=
\(!= \(!= ± \(+- ¬ \(no / \(sl
~ \(ap ~ \(~= \(pt \(pt \(gr \(gr
-> \(-> <- \(<- \(ua \(ua \(da \(da
\(is \(is \(pd \(pd \(if \(if \(sr \(sr
\(sb \(sb \(sp \(sp \(cu \(cu \(ca \(ca
\(ib \(ib \(ip \(ip \(mo \(mo Ø \(es
' \(aa ` \(ga O \(ci \(bs \(bs
§ \(sc *** \(dd <= \(lh => \(rh
\(lt \(lt \(rt \(rt \(lc \(lc \(rc \(rc
\(lb \(lb \(rb \(rb \(lf \(lf \(rf \(rf
\(lk \(lk \(rk \(rk | \(bv \(ts
| \(br | \(or _ \(ul \(rn \(rn
* \(**

These four characters also have two-character names. The ' is the apostrophe on terminals; the ` is the other quote mark.

' \' ` \` - \- _ \_

These characters exist only on the special font, but they do not have four-character names:

" { } < > ~ ^ \ # @

For greek, precede the roman letter by \(*to get the corresponding greek; for example, \(*ais .

abgdezyhiklmncoprstufxqw
µ

ABGDEZYHIKLMNCOPRSTUFXQW
ABEZHIKMNOPTX

Index

! (negating conditionals)~17 #$ (macro argument)~16 #*x, #(xy (invoke string macro)~14 #b (bracketing function)~13 #d (subscript)~11 #f (font change)~5 #h (horizontal motion)~12 #nx, #n(xy (number register)~15 #o (overstrike)~13 #s (size change)~3 #u (superscript)~11 #v (vertical motion)~11 #w (width function)~12 #z (zero motion)~13 'command instead of ^command~9 % (page number register)~10,15 ^^ (end of macro definition)~7 ^bp~9,10 ^br (break)~9 ^ce (center)~2 ^ds (define string macro)~7,14 ^fi (fill)~2 ^ft (change font)~5 ^if (conditional test)~16 ^in (indent)~6 ^lg (set ligatures~5 ^ll (line length)~6 ^nf (nofill)~2 ^nr (set number register)~14 ^pn (page number)~10 ^ps (change point size)~1,3 ^sp (space)~4 ^ss (set space size)~10 ^ta (set tab stops)~11 ^tc (set tab character)~10 ^tl (title)~9 ^tr (translate characters)~2,6 ^ul (italicize)~6 ^vs (vertical spacing)~3 ^wh (when conditional)~9,17 accents~6,13 apostrophes~6 arithmetic~15 backslash~1,3,5,14,16 begin page (^bp)~9 block macros (B1,B2)~8 bold font (.ft B)~5 boustrophedon~12 bracketing function (##b)~13 break (^br)~9 break-causing commmands~9 centering (^ce)~2 changing fonts (^ft, #f)~5 changing macros~15 character set~4,5,19 character translation (^tr)~2,6 columnated output~10 commands~1 commands that cause break~9 conditionals (^if)~16 constant proportion~7 default break list~9 define macro (^de)~7 define string macro (^ds)~14 drawing lines~11 em~7,11 end of macro (^^)~7 even page test (e)~17 fill (^fi)~2 fonts (^ft)~4,19 Greek (#(*-)~5,19 hanging indent (^ti)~12 hints~20 horizontal motion (#h)~12 hp (horizontal position register)~15 hyphen~6 i scale indicator~4 indent (^in)~6 index~21 italic font (.ft I)~4 italicize (^ul)~6 legal point sizes~3 ligatures (ff,fi,fl; ^lg)~5 line length (^ll)~6 line spacing (^vs)~3 local motions (#u,#d,#v,#h,#w,#o,#z,#b)~11 ff m scale indicator~7 machine units~4,12 macro arguments~15 macros~7 macros that change~15 multiple backslashes~14 negating conditionals (!)~17 new page macro (NP)~8 nl (current vertical position register)~15 nofill (^nf)~2 NROFF test (n)~17 nested quotes~12 number registers (^nr,#n)~14 numbered paragraphs~12 odd page test (o)~17 order of evaluation~14 overstrike (#o)~13 p scale indicator~3 page number register (%)~10 page numbers (^pn, ^bp)~10 paragraph macro (PG)~7 Paternoster~6 point size (^ps)~1,3 previous font (#fP, ^ft P)~5 previous point size (#s0,^ps)~3 quotes~6 relative change (±)~6 ROFF~1 ROFF header and footer~8 Roman font (.ft R)~4 scale indicator i~4 scale indicator m~7 scale indicator p~3 scale indicator u~12 scale indicators in arithmetic~15 section heading macro (SC)~15 set space size (^ss)~10 size _ see point size space (^sp)~4 space between lines (^vs)~3 special characters (#(xx)~5,19 string macros (^ds,#*)~14 subscripts (#d)~11 superscripts (#u)~11 tab character (^tc)~11 tabs (^ta)~10 temporary indent (^ti)~7 titles (^tl)~8 translate (^tr)~2,6,12 TROFF examples~19 TROFF test (t)~17 truncating division~15 type faces _ see fonts u scale indicator~12 underline (^ul)~6 valid point sizes~3 vertical motion (#v)~11 vertical position on page~9 vertical spacing (^vs)~3 when (^wh)~9,17 width function (#w)~12 width of digits~10 zero motion (#z)~13