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 / ch1.03 < prev    next >
Text File  |  1994-01-25  |  4KB  |  97 lines
  1. @Section
  2.    @Tag { cross }
  3.    @Title { Cross references }
  4. @Begin
  5. @PP
  6. A cross reference
  7. cross.ref @Index { Cross reference }
  8. in common terminology is something like `see Table 6'
  9. or `see page 57' -- a reference within a document to some other part of
  10. the document.  Readers find them very useful, but they are a major
  11. bookkeeping problem for authors.  As the document is revised, Table 6
  12. becomes Table 7, the thing on page 57 moves to page 63, and all the
  13. cross references must be changed.
  14. @PP
  15. The Scribe
  16. scribe @Index { Scribe }
  17. document formatter, developed by Brian K. Reid [{@Ref reid80}],
  18. reid.brian @Index { Reid, Brian K. }
  19. introduced a scheme for keeping track of cross
  20. references.  It allows you to give names to tables, figures, etc., and to
  21. refer to them by name.  The formatter inserts the appropriate numbers in
  22. place of the names, so that as the document is revised, the
  23. cross references are kept up to date automatically.  Lout has adopted
  24. and extended this scheme.
  25. @PP
  26. In Lout, automatic cross referencing works in the following way.  First
  27. define a symbol with a parameter with the special name @Code "@Tag":
  28. @ID @Code {
  29. "def @Table"
  30. "   left @Tag"
  31. "   right @Value"
  32. "{"
  33. "   ||1i  @Value"
  34. "}"
  35. }
  36. When this symbol is invoked, the value given to @Code "@Tag" should be a
  37. simple word like {@Code "cities"}, or several simple words juxtaposed
  38. like {@Code "cities.compare"}; it serves to name the invocation:
  39. @ID @Code {
  40. "cities @Table"
  41. "{"
  42. "    Washington  |0.5i  Canberra"
  43. "}"
  44. }
  45. We may now refer to this invocation elsewhere in the document, using the
  46. @I {cross reference} @Code "@Table&&cities".  Here @Code "&&" is the
  47. {@I {cross reference symbol}}; its left parameter is a symbol and its right
  48. parameter is the value of the @Code "@Tag" parameter of some invocation
  49. of that symbol.
  50. @PP
  51. A cross reference is not an object; the reader should think of it as
  52. an arrow in the final printed document, beginning at the cross reference
  53. symbol and ending at the top of the target
  54. target @Index { Target of cross reference }
  55. invocation, like this:
  56. @ID 8p @Font {
  57.   { @LittlePage // @LittlePage }
  58.   ||0io ||0.7c
  59.   { //2c 
  60.     { @Code "@Table&&cities" }
  61.     //0.1c
  62.     ||0.5c 90d @Rotate @Arrow 2.5c
  63.     //0.05c
  64.     @HContract @VContract
  65.       @Fig { @Box margin { 0c } paint { grey } { 1.5c @Wide 1c @High } }
  66.   }
  67. }
  68. @PP
  69. Two special values may be given to the right parameter of
  70. {@Code "&&"}:  @Code preceding
  71. preceding. @Index { @Code preceding }
  72. following. @Index { @Code following }
  73. and
  74. @Code following.  The cross
  75. reference @Code "@Table&&preceding" points to some table
  76. appearing earlier in the final printed document than itself; that is, the
  77. arrow is guaranteed to point backwards through the document.  Usually it
  78. points to the nearest preceding invocation.  Similarly, 
  79. @Code "@Table&&following" points forwards, usually to the
  80. nearest following invocation of @Code "@Table".
  81. @PP
  82. This section has been concerned with what a cross reference is -- an
  83. arrow from one point in a document to another -- but not with how it is
  84. used.  One simple way to use a cross reference is to put it where an
  85. object is expected, like this:
  86. @ID @Code {
  87. "a  |  @Table&&cities  |  c"
  88. }
  89. In this case the cross reference will be replaced by a copy of the
  90. invocation it points to:  in the example just given, a table will appear
  91. between @Code a and @Code c.  Other applications of cross references may be
  92. found in Chapter {@NumberOf examples}, including finding the number of
  93. the page where something appears, producing running page headers and footers,
  94. and accessing databases of Roman numerals, references, etc.  Cross
  95. references are also used by galleys, as will be explained in the next section.
  96. @End @Section
  97.