@Section
   @Title { Cross references }
   @Tag { cross }
@Begin
@PP
Cross references are a useful feature of documents, but they are a
cross.ref @Index { cross references }
problem for authors.  Suppose that at one point of your document
you have
@ID @OneRow @Code {
"We hold these truths to be self-evident, that all men are created equal,"
"that they are endowed by their Creator with certain inalienable Rights,"
"that among these are Life, Liberty, and the pursuit of Happiness..."
}
and that at some other point, earlier or later, you have
@ID @OneRow @Code {
"The anti-slavery cause, founded as it was on the Declaration"
"of Independence (page 181), could appeal to patriotic as"
"well as moral sentiments..."
}
This is a @I { cross reference }, and the problem is that as the document
is revised, the Declaration of Independence might move to page 185, and
the cross reference must be found and changed.
@PP
Lout has a simple solution to this problem.  Instead of writing the
pageof. @Index @Code "@PageOf"
page number, write
@ID @OneRow @Code {
"The anti-slavery cause, founded as it was on the Declaration"
"of Independence (page @PageOf { decl.of.ind }), could appeal to"
"patriotic as well as moral sentiments..."
}
instead, and at the point referred to, write
pagemark. @Index @Code "@PageMark"
@ID @OneRow @Code {
"We @PageMark decl.of.ind hold these truths to be self-evident, that..."
}
Inserting @Code "@PageMark decl.of.ind" will not affect the result,
but Lout makes a note of the number of the page on which the word
preceding it appears, and inserts that number in place of
{@Code "@PageOf decl.of.ind"}.  The tag, {@Code "decl.of.ind"}, may be
tag. @Index { tag }
any simple word (actually Lout will accept a multi-word tag, but they
are very inconvenient and better avoided).  The braces are there, as
usual, to control grouping:  we don't want the following punctuation
characters in the tag.
@PP
One tag called @Code "last.page" is created automatically
"last.page.tag" @Index { @Code "last.page" tag }
for you.  @Code "@PageOf last.page" gives the number of the last page
of the document.  For example, the result for this document is
{@PageOf last.page}.
@PP
Cross referencing also applies to large-scale structure symbols such as
@Code "@Chapter" and @Code "@Section" (any symbol with a @Code "@Title"
option), as well as @Code { "@FootNote" }, @Code { "@EndNote" },
@Code { "@Figure" }, @Code { "@Table" }, the numbered display
symbols, and @Code "@ListItem" and @Code "@DropListItem" (but not
@Code "@TagItem" and {@Code "@DropTagItem"}).  Each of these symbols
has a @Code "@Tag" option:
tag.sym @Index @Code "@Tag"
@ID @OneRow @Code {
"@Section"
"   @Title { Cross references }"
"   @Tag { cross }"
"@Begin"
"@PP"
"Cross references are a useful ..."
}
Now you can use the @Code "@PageOf" symbol to find the
number of the page on which the symbol's result begins, and the
@Code "@NumberOf" symbol to find its number:
numberof. @Index @Code "@NumberOf"
@ID @OneRow @Code {
"For further information on this point, please consult"
"Section @NumberOf cross (page @PageOf { cross })."
}
produces
@QD {
For further information on this point, please consult
Section @NumberOf cross (page @PageOf { cross }).
}
Like all tags, the value of the @Code "@Tag" option should be a simple
word (although Lout does accept multi-word tags).  Cross referencing of
list items yields just the number of the item, in Arabic, Roman, or
whatever; it does not include the surrounding parentheses or other
decorations introducted by the list's @Code "style" option.
@PP
To work cross references out, Lout has to process your document more
multiple.runs @Index { multiple runs, why needed }
than once, storing information between runs in special files it
creates whose names end in @Code ".li" and {@Code ".ld"}.  A complex
document like this Guide requires five runs, but since every run
produces a perfectly good PostScript file suitable for proof reading,
in fact you need two runs to start with and one run per cycle of
revision thereafter, only one more than would have been necessary
in any case.
@PP
The cross referencing system assumes that each Unix directory contains
directories @Index { directories, Lout files and }
only one Lout document (possibly spread over many files).  If you keep
several documents in one directory you can turn off the cross referencing
with the @Code "-s" flag:
@ID @Code "lout  -s  simple  >  simple.ps"
Since this will cause question marks to replace footnote and section
numbers, and other products of cross referencing, it is only feasible
for simple documents.  Alternatively, you can reset cross referencing
when switching from one document to another, by removing file
lout.li @Index { @Code lout.li file }
{@Code "lout.li"}.  You should also remove this file if your document
changes radically -- from a report to a book, say.
@End @Section