home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / unix / riscbsd / 1_1_contri / usd / 25_trofftu / tt14 < prev    next >
Encoding:
Text File  |  1986-05-23  |  3.0 KB  |  115 lines
  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.
  115.