aboutsummaryrefslogtreecommitdiffstats
path: root/doc/doc/expert/pri_cros
diff options
context:
space:
mode:
Diffstat (limited to 'doc/doc/expert/pri_cros')
-rw-r--r--doc/doc/expert/pri_cros112
1 files changed, 0 insertions, 112 deletions
diff --git a/doc/doc/expert/pri_cros b/doc/doc/expert/pri_cros
deleted file mode 100644
index 677794e..0000000
--- a/doc/doc/expert/pri_cros
+++ /dev/null
@@ -1,112 +0,0 @@
-@Section
- @Tag { cross }
- @Title { Cross references }
-@Begin
-@PP
-A cross reference
-cross.ref @Index { Cross reference }
-in common terminology is something like `see Table 6'
-or `see page 57' -- a reference within a document to some other part of
-it. Readers find them very useful, but they are a major
-problem for authors. As the document is revised, Table 6
-becomes Table 7, the thing on page 57 moves to page 63, and all the
-cross references must be changed.
-@PP
-The Scribe
-scribe @Index { Scribe }
-document formatter, developed by Brian K. Reid @Cite { $reid1980scribe },
-reid.brian @Index { Reid, Brian K. }
-introduced a scheme for keeping track of cross
-references. It allows you to give names to tables, figures, etc., and to
-refer to them by name. The formatter inserts the appropriate numbers in
-place of the names, so that as the document is revised, the
-cross references are kept up to date automatically. Lout has adopted
-and extended this scheme.
-@PP
-In Lout, automatic cross referencing works in the following way. First
-define a symbol with a parameter with the special name @Code "@Tag":
-@ID @OneRow @Code {
-"def @Table"
-" left @Tag"
-" right @Value"
-"{"
-" ||1i @Value"
-"}"
-}
-When this symbol is invoked, the value given to @Code "@Tag" should be a
-simple word like {@Code "cities"}, or several simple words juxtaposed
-like {@Code "cities compare"}; it serves to name the invocation:
-@ID @OneRow @Code {
-"{ cities compare } @Table"
-"{"
-" Washington |0.5i Canberra"
-"}"
-}
-We may now refer to this invocation elsewhere in the document, using the
-@I {cross reference} @Code "@Table&&{ cities compare }". Here @Code "&&"
-is the {@I {cross reference symbol}}; its left parameter is a symbol and
-its right parameter is the value of the @Code "@Tag" parameter of some
-invocation of that symbol. Of course it's simplest if you use just a
-one-word tag; then no braces are needed.
-@PP
-A cross reference is not an object; the reader should think of it as
-an arrow in the final printed document, beginning at the cross reference
-and ending at the top of the target
-target.cr @Index { Target of cross reference }
-#@ID 8p @Font {
-# { @LittlePage // @LittlePage }
-# ||0io ||0.7c
-# { //2c
-# { @Code "@Table&&cities" }
-# //0.1c
-# ||0.5c 90d @Rotate @Arrow 2.5c
-# //0.05c
-# @HContract @VContract
-# @Fig { @Box margin { 0c } paint { grey } { 1.5c @Wide 1c @High } }
-# }
-#}
-#@PP
-invocation. Three special values may be given to the right parameter of
-{@Code "&&"}: {@Code preceding}, {@Code following}, and
-preceding. @Index { @Code preceding }
-following. @Index { @Code following }
-foll_or_prec. @Index { @Code following }
-{@Code foll_or_prec}. The cross
-reference @Code "@Table&&preceding" points to some table
-appearing earlier in the final printed document than itself; that is, the
-arrow is guaranteed to point backwards through the document. Usually it
-points to the nearest preceding invocation. Similarly,
-@Code "@Table&&following" points forwards, usually to the
-nearest following invocation. @Code "@Table&&foll_or_prec" is the same as
-@Code "@Table&&following" if it exists, otherwise it is the same as
-{@Code "@Table&&preceding"}.
-@PP
-This section has been concerned with what a cross reference is -- an
-arrow from one point in a document to another -- but not with how it is
-used. One simple way to use a cross reference is to put it where an
-object is expected, like this:
-@ID @Code {
-"a | @Table&&cities | c"
-}
-In this case the cross reference will be replaced by a copy of the
-invocation it points to: in the example just given, a table will appear
-between @Code a and @Code c. Other applications of cross references may be
-found in Chapter {@NumberOf examples}, including finding the number of
-the page where something appears, producing running page headers and footers,
-and accessing databases of Roman numerals, references, etc. Cross
-references are also used by galleys, as will be explained in the next section.
-@PP
-The implementation of cross referencing copies every symbol invocation with
-a @Code "@Tag" parameter into the @I { cross-reference database },
-a collection of files whose names end in {@Code ".ld"} indexed by one file
-whose name is {@Code "lout.li"}. It is generally the case that the bulk
-content of a symbol such as the table above is contained in its right or
-body parameter, and that this bulk content is not needed by cross references
-to the symbol. Hence, to save space in the database, Lout replaces the
-right parameter of each symbol it writes into it by the word "???" whenever
-the right parameter appears to be large. The table above would appear as
-"???" because of this optimization, and in general, the user must ensure
-that any content required by cross references is contained in parameters
-other than the right or body parameter. This optimization does not apply
-when the symbol being written into the cross-reference database is a galley.
-@End @Section