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.02 < prev    next >
Text File  |  1994-01-25  |  8KB  |  236 lines
  1. @Section
  2.    @Title { Paragraphs, displays, and lists }
  3.    @Tag { paras }
  4. @Begin
  5. @PP
  6. The remaining sections of this chapter are all based on the
  7. DocumentLayout package, described from the user's perspective in the
  8. document.layout @Index { DocumentLayout package }
  9. Beginners' Guide [{@Ref kingston92begin}].  In 26 pages of Lout,
  10. the package defines many features required in the formatting of simple
  11. documents, technical reports, and books, including displays, lists, page
  12. layout, cross references, tables of contents, footnotes, figures,
  13. tables, references, chapters, sections, and sorted indexes.
  14. @PP
  15. The symbols used for separating paragraphs and producing displays and
  16. document.layout.paras @SubIndex { paragraphs }
  17. lists may lack the excitement of more exotic features, but they can
  18. teach some important lessons about robust design.  The following macro
  19. for separating paragraphs produces a 0.3 cm vertical space and a 1 cm
  20. indent on the following line, and is clearly on the right track:
  21. @ID @Code "macro  @PP  { //0.3c &1c }"
  22. Nevertheless it has several major problems.
  23. @PP
  24. The @Code "&" symbol is subject to widening during line adjustment, so
  25. it should be replaced by {@Code "1c @Wide {}"}.  But then white space
  26. following the symbol will affect the result, so an extra @Code "&0i" must
  27. be added.  If the document is printed double spaced, this paragraph gap
  28. will fail to widen:  it should be expressed in terms of the @Code "v" unit,
  29. with mark-to-mark spacing mode.  Similarly, the paragraph indent should
  30. probably be made proportional to the font size.
  31. @PP
  32. `Magic numbers' like @Code "0.3c" should not be buried in definitions
  33. where they cannot be changed easily, or kept consistent with similar
  34. definitions during tuning.  They are much better placed as symbols,
  35. possibly parameters of the enclosing package:
  36. @ID @Code {
  37. "def @DocumentLayout" pp.example @Index { @Code "@PP" example }
  38. "    named @ParaGap { 1.3vx }"
  39. "    named @ParaIndent { 2f }"
  40. "    ..."
  41. "@Begin"
  42. ""
  43. "    macro @PP { //@ParaGap @ParaIndent @Wide &0i }"
  44. "    macro @LP { //@ParaGap }"
  45. "    ..."
  46. "@End @DocumentLayout"
  47. }
  48. and we have arrived at the definition of @Code "@PP" as it appears in
  49. the DocumentLayout package.
  50. @PP
  51. A display is a table in which the first column is blank:
  52. document.layout.displays @SubIndex { displays }
  53. @ID lines @Break {
  54. @I { preceding text }
  55. @Code "//@DispGap |@DispIndent"  @I display
  56. @Code "//@DispGap"
  57. @I { following text }
  58. }
  59. Edge-to-edge is the appropriate spacing mode before and after displays,
  60. since the display could be a table or figure whose mark does not
  61. correspond to a baseline.  Thus, @Code "1v" is a reasonable value for
  62. {@Code "@DispGap"}.
  63. @PP
  64. The ordinary user cannot be expected to type the Lout source shown
  65. above; a more appropriate syntax is
  66. indented.display.example @Index { @Code "@IndentedDisplay" example }
  67. @ID lines @Break {
  68. @I { preceding text }
  69. @Code "@IndentedDisplay {"  @I display  @Code "}"
  70. @I { following text }
  71. }
  72. This presents a problem:  if @Code "@IndentedDisplay" is made a definition
  73. with a right parameter, its result will be an object separated from the
  74. surrounding text only by white space, hence part of the paragraph; while
  75. if it is a macro, the final @Code "//@DispGap" cannot be included in it.
  76.  The solution adopted in the DocumentLayout package uses a galley and a macro:
  77. @ID @Code {
  78. "    def @DispPlace { @Galley }"
  79. "    def @Disp into { @DispPlace&&preceding }"
  80. "        right x"
  81. "    {"
  82. "        @OneRow x"
  83. "    }"
  84. ""
  85. "    macro @IndentedDisplay"
  86. "    {"
  87. "        //@DispGap  |@DispIndent  @DispPlace  |"
  88. "        //@DispGap  //  @Disp"
  89. "    }"
  90. }
  91. @Code "@DispPlace" and @Code "@Disp" are not exported, so there is
  92. no danger of a name clash with some other symbol.  The ordinary user's
  93. syntax expands to
  94. @ID lines @Break {
  95. @I { preceding text }
  96. @Code "//@DispGap  |@DispIndent  @DispPlace  |"
  97. @Code "//@DispGap  //  @Disp {" @I display @Code "}"
  98. @I { following text }
  99. }
  100. and the @Code "@Disp" galley appears at the preceding
  101. {@Code "@DispPlace"}, being itself replaced by @@Null.  The @Code "//"
  102. symbol protects the preceding @Code "//@DispGap" from being deleted by
  103. this @@Null when there is no following text.
  104. @PP
  105. An automatically numbered list
  106. document.layout.lists @SubIndex { lists }
  107. numbered @Index { Numbered list }
  108. could have an arbitrarily large number of
  109. items, so, by analogy with sequences of pages, we see immmediately that
  110. recursion must be involved:
  111. @ID @Code {
  112. "def @List right num"
  113. "{"
  114. "    @DispIndent @Wide num.  |  @ItemPlace"
  115. "    //@DispGap @List @Next num"
  116. "}"
  117. }
  118. Notice how the @@Next symbol works in conjunction with the recursion to
  119. produce an ascending sequence of numbers; the result of @Code "@List 1"
  120. will be
  121. @ID @Code {
  122. "1.   @ItemPlace"
  123. "2.   @ItemPlace"
  124. "3.   @ItemPlace"
  125. "..."
  126. }
  127. We can follow this with items which are galleys targeted to
  128. {@Code "@ItemPlace&&preceding"}, and @Code "@List" will expand just
  129. enough to accommodate them.
  130. @PP
  131. The usual problem with recursive-receptive symbols now arises:  there is
  132. always one unexpanded {@Code "@List"}, and until it can be removed the
  133. galley containing it will appear to be incomplete and will be prevented at
  134. that point from flushing into its parent (see page {@PageOf forcing}).  We
  135. adopt the usual solution:  a forcing galley into a later target will
  136. replace the last @Code "@List" by @@Null.  This brings us to the
  137. definitions as they appear in DocumentLayout:
  138. indented.list.example @Index { @Code "@IndentedList" example }
  139. @IndentedList
  140. @LI @Code {
  141. "def @ItemPlace { @Galley }"
  142. "def @ListItem into { @ItemPlace&&preceding }"
  143. "    right x"
  144. "{ x }"
  145. }
  146. @LI @Code {
  147. "def @EndListPlace { @Galley }"
  148. "def @EndList force into { @EndListPlace&&preceding }"
  149. "{}"
  150. }
  151. @LI @Code {
  152. "def @RawIndentedList"
  153. "   named style right tag {}"
  154. "   named indent { @DispIndent }"
  155. "   named gap { @DispGap }"
  156. "   named start { 1 }"
  157. "{"
  158. "    def @IList right num"
  159. "    {"
  160. "        indent @Wide {style num} | @ItemPlace"
  161. "        //gap @IList @Next num"
  162. "    }"
  163. ""
  164. "    @IList start  //  @EndListPlace"
  165. "}"
  166. }
  167. @EndList
  168. Now given the input
  169. @ID @Code {
  170. "@RawIndentedList"
  171. "@ListItem { first item }"
  172. "@ListItem { second item }"
  173. "..."
  174. "@ListItem { last item }"
  175. "@EndList"
  176. }
  177. @Code "@RawIndentedList" will expand to receive the items, and will be
  178. closed off by {@Code "@EndList"}.
  179. @PP
  180. The {@Code indent}, {@Code gap}, and {@Code start} parameters are
  181. straightforward (note that the burden of typing @Code 1 has been lifted
  182. from the ordinary user), but the @Code style parameter has a parameter
  183. of its own (see page {@PageOf strange}).  It is used like this:
  184. @ID @Code {
  185. "def @RawNumberedList { @RawIndentedList style { tag. } }"
  186. "def @RawParenNumberedList { @RawIndentedList style { (tag) } }"
  187. }
  188. In {@Code "@RawNumberedList"}, @Code "style" is given the value
  189. {@Code "tag."}, where @Code tag is its own right parameter, so the value
  190. of @Code "{style num}" within @Code "@IList" is {@Code "num."}; while in
  191. {@Code "@RawParenNumberedList"}, @Code "{style num}" is {@Code "(num)"}.  In
  192. this way we achieve an unlimited variety of numbering formats without
  193. having to rewrite @Code "@RawIndentedList" over and over.
  194. @PP
  195. These list symbols are objects without surrounding space, so macros
  196. similar to those used for displays are needed:
  197. @ID @Code {
  198. "macro @NumberedList { //@DispGap @RawNumberedList //@DispGap }"
  199. "macro @ParenNumberedList { //@DispGap @RawParenNumberedList //@DispGap }"
  200. }
  201. and so on.
  202. @PP
  203. Lists numbered by Roman numerals
  204. roman @Index { Roman numerals }
  205. present a problem, because @@Next will
  206. not increment Roman numerals.  Instead, they must be stored in a
  207. database:
  208. @ID @Code {
  209. "def @Roman"
  210. "    left @Tag"
  211. "    right @Val"
  212. "{ @Val }"
  213. ""
  214. "@SysDatabase @Roman { standard }"
  215. }
  216. @Code "@SysDatabase" is preferred over @Code "@Database" here because
  217. this database should be kept in a standard place and shared by
  218. everyone.  The database itself, a file called @Code "standard.ld" in
  219. Basser Lout, contains invocations of {@Code "@Roman"}, each enclosed in
  220. braces:
  221. @ID @Code {
  222. "{ 1 @Roman i }"
  223. "{ 2 @Roman ii }"
  224. "..."
  225. "{ 100 @Roman c }"
  226. }
  227. Then @Code "@Roman&&12" for example has value {@Roman&&12}, and
  228. @ID @Code {
  229. "def @RawRomanList { @RawIndentedList style { {@Roman&&tag}. } }"
  230. }
  231. produces a list numbered by Roman numerals.  The counting still
  232. proceeds in Arabic, but each Arabic numeral is converted to Roman by the
  233. cross reference.  Since arbitrary objects may be stored in databases,
  234. arbitrary finite sequences of objects may be `counted' in this way.
  235. @End @Section
  236.