1 files changed, 112 insertions, 0 deletions
diff --git a/doc/user/str_cros b/doc/user/str_cros
new file mode 100644
index 0000000..7eb74c3
--- /dev/null
+++ b/doc/user/str_cros
@@ -0,0 +1,112 @@
+@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