Lout 3.17.

git-svn-id: http://svn.savannah.nongnu.org/svn/lout/trunk@2 9365b830-b601-4143-9ba8-b4a8e2c3339c

1 files changed, 98 insertions, 0 deletions

diff --git a/doc/user/ap_byp b/doc/user/ap_byp
new file mode 100644
index 0000000..a1c1bd7
--- /dev/null
+++ b/doc/user/ap_byp
@@ -0,0 +1,98 @@
+@Appendix
+    @Title { Bypass Symbols }
+    @Tag { bypass }
+@Begin
+@PP
+The `bypass' symbols described in this appendix are intended to be
+used only in Lout which is generated by computer programs.  Their
+purpose is to bypass the Lout cross reference database, and so reduce
+the number of passes needed to finalise a document.  These symbols
+should not be used by people, because that would only lead back to the
+consistency problems that prompted the introduction of cross references
+in the first place.
+@PP
+To produce a bypass table of contents, set the @Code "@MakeContents"
+setup file option to @Code "Bypass" and use @Code "@BypassContentsEntry"
+symbols at the outermost level just before the introduction or first
+chapter:
+@ID @Tab
+    @Fmta { @Col @Code A ! @Col ! @Col B }
+    vmargin { 0.5vx }
+{
+@Rowa
+    A { "@BypassContentsEntry" }
+@Rowa
+    A { "    indent { 0f }" }
+    B { the indent, e.g. {@Code "0f"}, {@Code "2f"}, {@Code "4f"} ... }
+@Rowa
+    A { "    number {}" }
+    B { the section (etc.) number e.g. {@Code "5.2"} }
+@Rowa
+    A { "    title {}" }
+    B { the section (etc.) title e.g. @Code "Azaleas" }
+@Rowa
+    A { "    pagenum {}" }
+    B { the page number e.g. @Code "@PageOf azaleas" }
+}
+For major entries such as chapters, use @Code "@BypassMajorContentsEntry"
+with the same options.  This increases the vertical spacing and uses
+bold font.  When @Code "@MakeContents" is {@Code "Bypass"}, no contents
+entries will be produced automatically.
+@PP
+To bypass Lout's automatic numbering of large-scale structure symbols,
+use the @Code "@BypassNumber" option:
+@ID @Code {
+"@Section"
+"    @Title { Azaleas }"
+"    @Tag { azaleas }"
+"    @BypassNumber { 5.2 }"
+"..."
+}
+Give the full `path number' (5.2, B.3 or whatever) of the symbol.  There is
+a @Code "@BypassNumber" option for every symbol that has a @Code "@Title"
+option and is usually assigned a number automatically by Lout, plus
+@Code "@Figure" and {@Code "@Table"}.  No changes to the setup file are
+required in order to use {@Code "@BypassNumber"}, and it is permitted
+for some large-scale structure symbols to have this option and others not.
+@PP
+To produce a bypass reference list, set the @Code "@MakeReferences"
+setup file option to @Code "Bypass" and place reference entries at the
+end of the document, after the last chapter or other large-scale structure
+symbol but before any bypass index entries (see below), like this:
+@ID @Code {
+"@BypassReference"
+"    label { [Kin94a] }"
+"    value { @RefPrint kingston1995lout.expert }"
+}
+The two options are objects which become the label and value of the
+reference entry.  The @Code "value" option can be any object, including
+an explicit reference; but @Code "@RefPrint" does not introduce any
+cross-referencing delay if the @Code "@Reference" symbols lie in a
+separate database file.  No sorting or removal of duplicate entries
+will be done by Lout.  When @Code "@MakeReferences" is {@Code "Bypass"},
+@Code "@Cite" and related symbols are ignored.
+@PP
+There is also @Code "@BypassChapReference" with the same options for
+producing bypass chapter reference lists; these symbols should be
+placed at the outer level immediately after the preface, introduction,
+chapter or appendix that they refer to.
+@PP
+To produce bypass indexes, set the @Code "@MakeIndex" setup file
+option to {@Code Bypass} and use the @Code "@BypassRawIndex" symbol
+repeatedly at the very end of the document, enclosed in
+@Code "@BypassBeginIndex" and @Code "@BypassEndIndex" symbols:
+@ID @Code {
+"@BypassBeginIndex"
+"@BypassRawIndex  indent { 0f }  { Azaleas, @PageOf azaleas }"
+"..."
+"@BypassEndIndex"
+}
+The @Code "indent" option gives the indent ({@Code "0f"}, @Code {"1f"},
+@Code {2f}, etc.), and the right parameter is as for @Code "@RawIndex".  No
+@Code "@PageMark" operations, sorting, merging, or attachment of page
+numbers will be done by Lout.  When @Code "@MakeIndex" is {@Code Bypass},
+@Code "@Index" and related symbols are ignored.  At present, bypass
+index symbols work only in books, not with ordinary documents or
+technical reports.  There are corresponding symbols for creating
+bypass indexes A and B.
+@End @Appendix