share/doc/usd/22.trofftut/tt14

   1 .\" This module is believed to contain source code proprietary to AT&T.
   2 .\" Use and redistribution is subject to the Berkeley Software License
   3 .\" Agreement and your Software Agreement with AT&T (Western Electric).
   4 .\"
   5 .\"     @(#)tt14        8.1 (Berkeley) 6/8/93
   6 .\" Copyright (C) Caldera International Inc. 2001-2002.  All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions are
  10 .\" met:
  11 .\"
  12 .\" Redistributions of source code and documentation must retain the above
  13 .\" copyright notice, this list of conditions and the following
  14 .\" disclaimer.
  15 .\"
  16 .\" Redistributions in binary form must reproduce the above copyright
  17 .\" notice, this list of conditions and the following disclaimer in the
  18 .\" documentation and/or other materials provided with the distribution.
  19 .\"
  20 .\" All advertising materials mentioning features or use of this software
  21 .\" must display the following acknowledgement:
  22 .\"
  23 .\" This product includes software developed or owned by Caldera
  24 .\" International, Inc.  Neither the name of Caldera International, Inc.
  25 .\" nor the names of other contributors may be used to endorse or promote
  26 .\" products derived from this software without specific prior written
  27 .\" permission.
  28 .\"
  29 .\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
  30 .\" INTERNATIONAL, INC.  AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
  31 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  32 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  33 .\" DISCLAIMED.  IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
  34 .\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
  35 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  36 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  37 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  38 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  39 .\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
  40 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  41 .\"
  42 .\" $FreeBSD$
  43 .\"
  44 .NH
  45 Diversions
  46 .PP
  47 There are numerous occasions in page layout when it is necessary to store some text
  48 for a period of time without actually printing it.
  49 Footnotes are the most obvious example:
  50 the text of the footnote usually appears in the input well before the place
  51 on the page where it is to be printed is reached.
  52 In fact,
  53 the place where it is output normally depends on how big it is,
  54 which implies that there must be a way
  55 to process the footnote at least
  56 enough to decide its size
  57 without printing it.
  58 .PP
  59 .UL troff
  60 provides a mechanism called a diversion
  61 for doing this processing.
  62 Any part of the output may be diverted into a macro instead
  63 of being printed,
  64 and then at some convenient time the macro may be put back into
  65 the input.
  66 .PP
  67 The command
  68 .BD .di\ xy
  69 begins a diversion _ all subsequent output is collected into the macro
  70 .BD xy
  71 until the command
  72 .BD .di
  73 with no arguments is encountered.
  74 This terminates the diversion.
  75 The processed text is available at any time thereafter, simply
  76 by giving the command
  77 .P1
  78 ^xy
  79 .P2
  80 The vertical size of the last finished diversion is contained in
  81 the built-in number register
  82 .BD dn .
  83 .PP
  84 As a simple example,
  85 suppose we want to implement a `keep-release'
  86 operation,
  87 so that text between the commands
  88 .BD .KS
  89 and
  90 .BD .KE
  91 will not be split across a page boundary
  92 (as for a figure or table).
  93 Clearly, when a
  94 .BD .KS
  95 is encountered, we have to begin diverting
  96 the output so we can find out how big it is.
  97 Then when a
  98 .BD .KE
  99 is seen, we decide
 100 whether the diverted text will fit on the current page,
 101 and print it either there if it fits, or at the top of the next page if it doesn't.
 102 So:
 103 .P1 2
 104 .ta .6i
 105 ^de KS  \e" start keep
 106 ^br     \e" start fresh line
 107 ^ev 1   \e" collect in new environment
 108 ^fi     \e" make it filled text
 109 ^di XX  \e" collect in XX
 110 ^^
 111 .P2
 112 .P1 2
 113 .ta .6i
 114 ^de KE  \e" end keep
 115 ^br     \e" get last partial line
 116 ^di     \e" end diversion
 117 ^if \e\en(dn>=\e\en(.t .bp   \e" bp if doesn't fit
 118 ^nf     \e" bring it back in no-fill
 119 ^XX     \e" text
 120 ^ev     \e" return to normal environment
 121 ^^
 122 .P2
 123 Recall that number register
 124 .BD nl
 125 is the current position
 126 on the output page.
 127 Since output was being diverted, this remains
 128 at its value when the diversion started.
 129 .BD dn
 130 is the amount of text in the diversion;
 131 .BD .t
 132 (another built-in register)
 133 is the distance to the next trap,
 134 which we assume is at the bottom margin of the page.
 135 If the diversion is large enough to go past the trap,
 136 the
 137 .BD .if
 138 is satisfied, and
 139 a
 140 .BD .bp
 141 is issued.
 142 In either case, the diverted output is then brought back with
 143 .BD .XX .
 144 It is essential to bring it back in no-fill mode so
 145 .UL troff
 146 will do no further processing on it.
 147 .PP
 148 This is not the most general keep-release,
 149 nor is it robust in the face of all conceivable inputs,
 150 but it would require more space than we have here to write it
 151 in full generality.
 152 This section is not intended
 153 to teach everything about diversions,
 154 but to sketch out enough that you can read
 155 existing macro packages with some comprehension.