home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / APPS / lout2.lzh / LOUT2 / DOC / TR.LOUT / ch4.04 < prev    next >
Text File  |  1994-01-25  |  11KB  |  273 lines
  1. @Section
  2.    @Title { Chapters and sections }
  3.    @Tag { chapters }
  4. @Begin
  5. @PP
  6. The definitions of chapters and sections from the DocumentLayout package
  7. chapters @Index { Chapters and sections }
  8. form the subject of this section.  They allow a chapter to be entered
  9. like this:
  10. document.layout.chapters @SubIndex { chapters and sections }
  11. @ID @Code {
  12. "@Chapter"
  13. "    @Title { ... }"
  14. "    @Tag { ... }"
  15. "@Begin"
  16. "    ..."
  17. "@End @Chapter"
  18. }
  19. Within the chapter a sequence of sections may be included by writing
  20. @ID @Code {
  21. "@BeginSections"
  22. "@Section { ... }"
  23. "..."
  24. "@Section { ... }"
  25. "@EndSections"
  26. }
  27. These are numbered automatically, and an entry is made for each in a
  28. table of contents.
  29. @PP
  30. The user of the DocumentLayout package can find the number of the chapter or
  31. section with a given tag by writing @Code "@NumberOf tag" at any point
  32. in the document.  This feature is based on the following definitions:
  33. numberof.example @Index { @Code "@NumberOf" example }
  34. @ID @Code {
  35. "export @Tag"
  36. "def @NumberMarker right @Tag { @Null }"
  37. ""
  38. "def @NumberOf right x"
  39. "{  @NumberMarker&&x @Open { @Tag }  }"
  40. }
  41. Each chapter and section will contain one invocation of
  42. {@Code "@NumberMarker"}; a full explanation will be given later.
  43. @PP
  44. A sequence of places for receiving chapters is easily defined:
  45. @ID @Code {
  46. "export @Tag"
  47. "def @ChapterList right @Tag"
  48. "{"
  49. "    @Galley"
  50. "    //@ChapterGap  @ChapterList @Next @Tag"
  51. "}"
  52. }
  53. @Code "@ChapterGap" will usually be {@Code "1.1b"}, ensuring that each
  54. chapter begins on a new page.  The @Code "@Chapter" galley itself is
  55. defined as follows:
  56. chapter.example @Index { @Code "@Chapter" example }
  57. @IndentedList
  58. @LI @Code {
  59. "export @FootNote @BeginSections @EndSections @Section"
  60. "def @Chapter force into { @ChapterList&&preceding }"
  61. "    named @Tag {}"
  62. "    named @Title {}"
  63. "    named @RunningTitle { dft }"
  64. "    body @Body"
  65. "{"
  66. "    def @FootNote right x { @ColFootNote x }"
  67. ""
  68. "    def @BeginSections ..."
  69. "    def @EndSections ..."
  70. "    def @Section ..."
  71. }
  72. @LI @Code {
  73. "    def @ChapterTitle"
  74. "    {"
  75. "        @ChapterNumbers @Case {"
  76. "            {Yes yes}  @Yield  { Chapter {@NumberOf @Tag}.  |2s  @Title }"
  77. "            else  @Yield  @Title"
  78. "        }"
  79. "    }"
  80. ""
  81. "    def @ChapterNum"
  82. "    {"
  83. "        @ChapterNumbers @Case {"
  84. "            {Yes yes}  @Yield  { Chapter {@NumberOf @Tag} }"
  85. "            else  @Yield @Null"
  86. "        }"
  87. "    }"
  88. }
  89. @LI @Code {
  90. "        ragged @Break @BookTitleFormat @ChapterTitle"
  91. "    //  @NumberMarker {"
  92. "            @ChapterList&&@Tag @Open { @Tag }"
  93. "        }"
  94. "    //  @ChapterList&&preceding  @Tagged @Tag"
  95. "    //  @NumberMarker&&preceding @Tagged @Tag"
  96. "    //  @PageMarker&&preceding   @Tagged @Tag"
  97. "    //  { @ChapterTitle } @MajorContentsEntry {@PageOf @Tag}"
  98. "    //  @Runner"
  99. "            @FootEven { |0.5rt 0.8f @Font @B @PageNum }"
  100. "            @FootOdd  { |0.5rt 0.8f @Font @B @PageNum }"
  101. "    //  @Body"
  102. "    //@SectionGap @ChapRefSection"
  103. "    //  @Runner"
  104. "            @TopEven { @B @PageNum |1rt @I @ChapterNum }"
  105. "            @TopOdd  { @I {@RunningTitle @OrElse @Title} |1rt @B @PageNum }"
  106. "}"
  107. }
  108. @EndList
  109. We will see the symbols for sections shortly.  Notice how their use has
  110. been restricted to within the right parameter of {@Code "@Chapter"}, by
  111. nesting them and using a body parameter.
  112. @PP
  113. The meaning of @Code "@FootNote" within @Code "@Chapter" has been set
  114. to {@Code "@ColFootNote"}, which produces a footnote targeted to
  115. {@Code "@ColFootList"} (see Section {@NumberOf pagelayout}).  In other
  116. words, footnotes within chapters go at the foot of the column, not at
  117. the foot of the page.  (Of course, in single-column books this
  118. distinction is insignificant.)  @Code "@ChapterTitle" and
  119. @Code "@ChapterNum" are trivial definitions which vary depending on
  120. whether the user has requested numbered chapters or not.
  121. @PP
  122. Each invocation of @Code "@Chapter" has its own unique {@Code "@Tag"},
  123. either supplied by the user or else inserted automatically by Lout.  We
  124. now trace the cross referencing of chapter numbers on a hypothetical
  125. third chapter whose tag is {@Code "euclid"}.
  126. @PP
  127. @Code "@ChapterList&&preceding @Tagged euclid" attaches @Code "euclid"
  128. as an extra tag to the first invocation of @Code "@ChapterList"
  129. preceding itself in the final printed document.  But this
  130. @Code "@ChapterList" must be the target of the chapter, and so
  131. @ID @Code "@ChapterList&&euclid @Open { @Tag }"
  132. is 3, the number of the chapter ({@Code "@Tag"} refers to the parameter
  133. of {@Code "@ChapterList"}, not the parameter of {@Code "@Chapter"}).
  134.  Consequently the invocation of
  135. @Code "@NumberMarker" within the chapter is equal to
  136. {@Code "@NumberMarker 3"}.
  137. @PP
  138. @Code "@NumberMarker&&preceding @Tagged euclid" attaches @Code "euclid"
  139. to {@Code "@NumberMarker 3"} as an extra tag, and so
  140. {@Code "@NumberOf euclid"}, which expands to
  141. @ID @Code "@NumberMarker&&euclid @Open { @Tag }"
  142. must be equal to 3, as required.  This scheme could be simplified by
  143. placing the invocation of @Code "@NumberMarker" within
  144. @Code "@ChapterList" rather than within {@Code "@Chapter"}, but it turns
  145. out that that scheme does not generalize well to sections and subsections.
  146. @PP
  147. There is a trap for the unwary in the use of @Code preceding and
  148. {@Code following}.  Suppose that the invocation of @Code "@NumberMarker"
  149. within @Code "@Chapter" is replaced by the seemingly equivalent
  150. @ID @Code "@NumberMarker { @ChapterList&&preceding @Open { @Tag } }"
  151. Now suppose that @Code "@NumberOf euclid" appears somewhere within
  152. Chapter 7.  It will expand to
  153. @ID @Code "@NumberMarker&&euclid @Open { @Tag }"
  154. which would now be equal to
  155. @ID @Code "@ChapterList&&preceding @Open { @Tag }"
  156. whose value, evaluated as it is within Chapter 7, is 7, not 3.  Use of
  157. @Code preceding or @Code following within the parameter
  158. of a symbol, rather than within the body, is likely to be erroneous.
  159. @PP
  160. Much of the remainder of the definition of @Code "@Chapter" is fairly
  161. self-explanatory:  there is a heading, a tag sent to mark the page on
  162. which the chapter begins, a @Code "@ContentsEntry" galley sent to the
  163. table of contents, galleys for the figures and tables of the chapter to
  164. collect in, @Code "@Body" where the body of the chapter goes, and
  165. @Code "@ChapRefSection" to hold a concluding list of references.  This
  166. leaves only the two invocations of @Code "@Runner" to explain.
  167. @PP
  168. The first @Code "@Runner" is just below the heading.  It will be the target
  169. of the @Code "@Runner&&following" cross reference at the beginning of the
  170. first page of the chapter (see Section {@NumberOf pagelayout}), which
  171. consequently will have null running headers and the given footers.
  172. @PP
  173. The second @Code "@Runner" appears at the very end of the chapter, hence
  174. on its last page.  Since no invocations of @Code "@Runner" lie between
  175. it and the first {@Code "@Runner"}, it will be the target of
  176. @Code "@Runner&&following" on every page from the second page of the
  177. chapter to the last, inclusive, and will supply the format of their
  178. headers and footers.
  179. @PP
  180. The interested reader might care to predict the outcome in unusual
  181. cases, such as when the heading occupies two pages, or when a chapter
  182. occupies only one, or (assuming a change to the gap between chapters)
  183. when a chapter starts halfway down a page.  Such predictions can be made
  184. with great confidence.
  185. @PP
  186. The expression @Code "@RunningTitle @OrElse @Title" appearing in the second
  187. @Code "@Runner" returns the value of the @Code "@RunningTitle" parameter
  188. of @Code "@Chapter" if this is not equal to the default value
  189. {@Code "dft"}, or @Code "@Title" otherwise:
  190. orelse.example @Index { @Code "@OrElse" example }
  191. @ID @Code {
  192. "def @OrElse"
  193. "    left x"
  194. "    right y"
  195. "{"
  196. "    x @Case {"
  197. "        dft  @Yield  y"
  198. "        else  @Yield  x"
  199. "    }"
  200. "}"
  201. }
  202. This produces the effect of
  203. @ID @Code {
  204. "named  @RunningTitle  {  @Title  }"
  205. }
  206. which unfortunately is not permissible as it stands, because @Code "@Title"
  207. is not visible within the default value of {@Code "@RunningTitle"}.
  208. @PP
  209. Finally, the definitions for sections omitted earlier are as follows:
  210. section.example @Index { @Code "@Section" example }
  211. @IndentedList
  212. @LI @Code {
  213. "def @EndSectionsPlace { @Galley }"
  214. "def @EndSections force into { @EndSectionsPlace&&preceding } {}"
  215. "macro @BeginSections { //@SectionGap @SectionList 1 // @EndSectionsPlace // }"
  216. }
  217. @LI @Code {
  218. "def @Section force into { @SectionList&&preceding }"
  219. "    named @Tag {}"
  220. "    named @Title {}"
  221. "    named @RunningTitle { dft }"
  222. "    body @Body"
  223. "{"
  224. "    def @SectionTitle"
  225. "    {"
  226. "        @SectionNumbers @Case {"
  227. "            {Yes yes} @Yield { {@NumberOf @Tag}.  |2s  @Title }"
  228. "            else      @Yield @Title"
  229. "        }"
  230. "    }"
  231. ""
  232. "        @Heading @Protect @SectionTitle"
  233. "    //  @NumberMarker {"
  234. "            {@ChapterList&&@Tag @Open { @Tag }}.{"
  235. "             @SectionList&&@Tag @Open { @Tag }}"
  236. "        }"
  237. "    //  @ChapterList&&preceding  @Tagged @Tag"
  238. "    //  @SectionList&&preceding  @Tagged @Tag"
  239. "    //  @NumberMarker&&preceding @Tagged @Tag"
  240. "    //  @PageMarker&&preceding   @Tagged @Tag"
  241. "    //  { &3f @SectionTitle } @ContentsEntry {@PageOf @Tag}"
  242. "    //0io @Body"
  243. "}"
  244. }
  245. @EndList
  246. The @Code "@BeginSections" macro invokes {@Code "@SectionList"},
  247. preceded by the appropriate gap and followed by an @Code "@EndSectsPlace"
  248. for closing the list of sections when the @Code "@EndSections" symbol is
  249. found.  @Code "@Section" itself is just a copy of @Code "@Chapter" with
  250. slight changes to the format.  The parameter of @Code "@NumberMarker" is
  251. a simple generalization of the one within {@Code "@Chapter"}.  Notice
  252. that we have taken care that the value of this parameter be
  253. a juxtaposition of simple words:  although
  254. @ID @Code {
  255. "{@ChapterList&&@Tag @Open { @Tag }}. &"
  256. "{@SectionList&&@Tag @Open { @Tag }}"
  257. }
  258. is formally equivalent, @Code "&" is not permitted within a
  259. @Code "@Tag" parameter.
  260. @PP
  261. The DocumentLayout package also contains definitions for subsections in the
  262. same style.  They raise the question of whether Lout is capable of
  263. producing subsections should the user place {@Code "@BeginSections"},
  264. {@Code "@Section"}, and {@Code "@EndSections"} within a {@I section},
  265. and whether such nesting could proceed to arbitrary depth.  Arbitrary
  266. nesting of sections within sections is available now, although the
  267. numbering would of course be wrong.  The author has worked out
  268. definitions which provide correct numbering to arbitrary depth, with an
  269. arbitrary format for each level.  These were not incorporated into
  270. DocumentLayout because the author considers sub-subsections to be poor
  271. style, and he prefers separate names for the symbols at each level.
  272. @End @Section
  273.