![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tt14 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 25.trofftut|
Return to tt14 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 25.trofftut |
1.1 root 1: .\" @(#)tt14 6.1 (Berkeley) 5/23/86
2: .\"
3: .NH
4: Diversions
5: .PP
6: There are numerous occasions in page layout when it is necessary to store some text
7: for a period of time without actually printing it.
8: Footnotes are the most obvious example:
9: the text of the footnote usually appears in the input well before the place
10: on the page where it is to be printed is reached.
11: In fact,
12: the place where it is output normally depends on how big it is,
13: which implies that there must be a way
14: to process the footnote at least
15: enough to decide its size
16: without printing it.
17: .PP
18: .UL troff
19: provides a mechanism called a diversion
20: for doing this processing.
21: Any part of the output may be diverted into a macro instead
22: of being printed,
23: and then at some convenient time the macro may be put back into
24: the input.
25: .PP
26: The command
27: .BD .di\ xy
28: begins a diversion _ all subsequent output is collected into the macro
29: .BD xy
30: until the command
31: .BD .di
32: with no arguments is encountered.
33: This terminates the diversion.
34: The processed text is available at any time thereafter, simply
35: by giving the command
36: .P1
37: ^xy
38: .P2
39: The vertical size of the last finished diversion is contained in
40: the built-in number register
41: .BD dn .
42: .PP
43: As a simple example,
44: suppose we want to implement a `keep-release'
45: operation,
46: so that text between the commands
47: .BD .KS
48: and
49: .BD .KE
50: will not be split across a page boundary
51: (as for a figure or table).
52: Clearly, when a
53: .BD .KS
54: is encountered, we have to begin diverting
55: the output so we can find out how big it is.
56: Then when a
57: .BD .KE
58: is seen, we decide
59: whether the diverted text will fit on the current page,
60: and print it either there if it fits, or at the top of the next page if it doesn't.
61: So:
62: .P1 2
63: .ta .6i
64: ^de KS \e" start keep
65: ^br \e" start fresh line
66: ^ev 1 \e" collect in new environment
67: ^fi \e" make it filled text
68: ^di XX \e" collect in XX
69: ^^
70: .P2
71: .P1 2
72: .ta .6i
73: ^de KE \e" end keep
74: ^br \e" get last partial line
75: ^di \e" end diversion
76: ^if \e\en(dn>=\e\en(.t .bp \e" bp if doesn't fit
77: ^nf \e" bring it back in no-fill
78: ^XX \e" text
79: ^ev \e" return to normal environment
80: ^^
81: .P2
82: Recall that number register
83: .BD nl
84: is the current position
85: on the output page.
86: Since output was being diverted, this remains
87: at its value when the diversion started.
88: .BD dn
89: is the amount of text in the diversion;
90: .BD .t
91: (another built-in register)
92: is the distance to the next trap,
93: which we assume is at the bottom margin of the page.
94: If the diversion is large enough to go past the trap,
95: the
96: .BD .if
97: is satisfied, and
98: a
99: .BD .bp
100: is issued.
101: In either case, the diverted output is then brought back with
102: .BD .XX .
103: It is essential to bring it back in no-fill mode so
104: .UL troff
105: will do no further processing on it.
106: .PP
107: This is not the most general keep-release,
108: nor is it robust in the face of all conceivable inputs,
109: but it would require more space than we have here to write it
110: in full generality.
111: This section is not intended
112: to teach everything about diversions,
113: but to sketch out enough that you can read
114: existing macro packages with some comprehension.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.