Lout 3.17.

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

130 files changed, 20473 insertions, 0 deletions

diff --git a/doc/user/README b/doc/user/README
new file mode 100644
index 0000000..fd69ccb
--- /dev/null
+++ b/doc/user/README
@@ -0,0 +1,37 @@
+Directory lout/doc/user
+
+This directory contains the Lout source files for the User's Guide
+to the Lout Document Formatting System.  To produce the Guide,
+type the command
+
+	lout all > op
+
+in this directory.  This must be done five times to completely
+resolve all cross references, although the PostScript file op is
+printable after the first run.  Auxiliary files with .li and .ld
+suffixes will be created in this directory.
+
+The first run will produce a large number of error messages,
+nearly all beginning with "unresolved cross reference".  These
+should gradually go away on later runs.  The following shows the
+error message output on the fifth run for A4 size printing:
+
+lout file "cpp_tabs" (from "cpp" line 24, from "all" line 38):
+   53,23: c2lout: C text ended inside a comment
+   55,35: c2lout: C text ended inside a comment
+
+These two warnings point to two places where a C program text ended
+inside a comment, which in these cases was deliberate so is no problem.
+If you set the document in Letter size paper, you will also get a
+couple of other warning messages pointing to places where Lout had
+to slightly scale a display to fit the smaller page.
+
+Optimal page breaking has been turned off for this document owing to
+repeated failure to converge, caused by footnotes and floating figures
+close to large unbreakable displays.
+
+A copy of the final PostScript output file (A4 paper size) is
+stored at "ftp://ftp.cs.su.oz.au/jeff/lout/lout.3.17.user.ps.gz".
+
+Jeffrey H. Kingston
+17 September 1999
diff --git a/doc/user/all b/doc/user/all
new file mode 100644
index 0000000..1b131f6
--- /dev/null
+++ b/doc/user/all
@@ -0,0 +1,47 @@
+@SysInclude { tab }
+@SysInclude { tbl }
+@SysInclude { eq }
+@SysInclude { fig }
+@SysInclude { graph }
+@SysInclude { pas }
+@SysInclude { diag }
+@SysInclude { cprint }
+@SysInclude { book }
+# @Include { letterbook } # for testing Letter size formatting
+
+@SysDatabase @Reference { loutrefs }
+
+@Book
+    @Title { A User's Guide to the
+
+Lout
+
+Document Formatting System
+}
+    @Author { Jeffrey H. Kingston }
+    @Edition { Version 3.17
+September, 1999 }
+    @Publisher {
+Copyright @CopyRight 1991, 1999 Jeffrey H. Kingston,
+Basser Department of Computer Science,
+The University of Sydney 2006, Australia.  ISBN 0 86758 951 5.
+}
+    @InitialLanguage { English }
+    # @OptimizePages { Yes }
+//
+
+@Include { preface }
+@Include { bas     }
+@Include { str     }
+@Include { typ     }
+@Include { fmt     }
+@Include { ref     }
+@Include { tbl     }
+@Include { equ     }
+@Include { bgr     }
+@Include { dia     }
+@Include { gra     }
+@Include { cpp     }
+@Include { pascal  }
+@Include { ap_qck  }
+@Include { ap_byp  }
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
diff --git a/doc/user/ap_qck b/doc/user/ap_qck
new file mode 100644
index 0000000..92ea7ad
--- /dev/null
+++ b/doc/user/ap_qck
@@ -0,0 +1,369 @@
+@Appendix
+    @Title { Lout Quick Reference Guide }
+@Begin
+10p @Font 1.15fx @Break @OneCol
+@Tab @Fmta { @Col 20c @Wide A ! @Col 20c @Wide B }
+{
+@Rowa A {
+@Heading { 1.  Running Lout }
+@LD @Code {
+"lout filename > postscript.ps"
+}
+
+@LP
+@Heading { 2.  Ordinary documents (simple form) }
+@LD @Code {
+"@SysInclude { doc }"
+"@Doc @Text @Begin"
+"..."
+"@End @Text"
+}
+
+@LP
+@Heading { 3.  Ordinary documents (full form) }
+@LD @Code {
+"@SysInclude { doc }"
+"@Document"
+"    @InitialFont { Times Base 12p }"
+"    @InitialBreak { adjust 1.2fx hyphen }"
+"    @InitialLanguage { English }"
+"    @PageHeaders { Simple }"
+"    @FirstPageNumber { 1 }"
+"    @ColumnNumber { 1 }"
+"    @PageOrientation { Portrait }"
+"//"
+"@Text @Begin"
+"..."
+"@BeginSections"
+"@Section ... @End @Section"
+"@EndSections"
+"@End @Text"
+}
+
+@LP
+@Heading { 4.  Technical reports }
+@LD @Code {
+"@SysInclude { report }"
+"@Report"
+"    @Title { ... }"
+"    @Author { ... }"
+"    @Institution { ... }"
+"    @DateLine { No }"
+"    @CoverSheet { Yes }"
+"    @InitialFont { Times Base 12p }"
+"    @InitialBreak { adjust 1.2fx hyphen }"
+"    @InitialLanguage { English }"
+"    @PageHeaders { Simple }"
+"    @FirstPageNumber { 1 }"
+"    @ColumnNumber { 1 }"
+"//"
+"@Abstract ... @End @Abstract"
+"@Section ... @End @Section"
+"@Appendix ... @End @Appendix"
+}
+}
+
+B {
+@Heading { 5.  Large-scale structure symbols }
+@LL
+@LI @Code {
+"@Section"
+"    @Title { ... }"
+"    @RunningTitle { ... }"
+"    @Tag { ... }"
+"@Begin"
+"@PP"
+"..."
+"@End @Section"
+}
+@LI lines @Break {
+@Code "@Section / @SubSection / @SubSubSection"
+@Code "@Appendix / @SubAppendix / @SubSubAppendix"
+@Code "@BeginSubSections" ... @Code "@EndSubSections" if inner.
+}
+@EndList
+
+@LP
+@Heading { 6.  Cross references }
+@LD @Tab
+    @Fmta { @Col @Code A ! @Col ! @Col @Code B }
+{
+@Rowa
+    A { "@Tag { foo }" }
+    B { "@PageOf foo" }
+@Rowa
+    A { "@PageMark foo" }
+    B { "@NumberOf foo" }
+}
+
+@LP
+@Heading { 7.  Font changes }
+@LL
+@LI @Tab 
+    @Fmta { @Col @Code A ! @Col @Code B }
+    vmargin { 0.5vx }
+{
+@Rowa
+    A { "@B { bold font }" }
+    B { "@I { italic font }" }
+@Rowa
+    A { "@BI { bold-italic font }" }
+    B { "@R { Roman font }" }
+@Rowa
+    A { "@S { small-caps font}" }
+    B { "@F { fixed-width font }" }
+@Rowa
+    B { "@II { italic bold or Roman }" }
+}
+@LI @Code {
+"{ family face size } @Font { ... }"
+}
+@LI @Code {
+"Times  Helvetica  Courier  ..."
+"Base  Slope  Bold  BoldSlope  ..."
+"10p  12p  +2p  -2p  2.0f  ..."
+}
+@EndList
+
+@LP
+@Heading { 8.  Paragraph breaking styles }
+@LL
+@LI @Code {
+"{ breakstyle linesep hyphen } @Break { ... }"
+}
+@LI @Code {
+"adjust  ragged  lines  clines  ..."
+"1.2fx  2vx  0.9vx  ..."
+"hyphen  nohyphen"
+}
+@EndList
+
+@LP
+@Heading { 9.  New paragraph and new page }
+@LD @Tab
+    @Fmta { @Col @Code A ! @Col B }
+    vmargin { 0.5vx }
+{
+@Rowa A { "@PP"  } B { Plain paragraph }
+@Rowa A { "@LP"  } B { Left paragraph }
+@Rowa A { "@LLP" } B { New line }
+@Rowa A { "@DP"  } B { Display paragraph }
+@Rowa A { "@NP"  } B { New page }
+@Rowa A { "@CNP" } B { Conditional new page }
+}
+}
+
+} # end first table
+@LP
+10p @Font 1.15fx @Break @OneCol
+@Tab @Fmta { @Col 20c @Wide A ! @Col 20c @Wide B }
+{
+@Rowa A {
+@Heading { 10.  Displays and headings }
+@LL
+@LI @Code {
+"@CD @Heading { A centred heading }"
+"@ID { An indented display }"
+}
+@LI @Tab
+    @Fmta { @Col @Code A ! @Col @Code B }
+    vmargin { 0.5vx }
+{
+@Rowa A { "@D"  } B { "@Display" }
+@Rowa A { "@LD" } B { "@LeftDisplay" }
+@Rowa A { "@ID" } B { "@IndentedDisplay" }
+@Rowa A { "@QD" } B { "@QuotedDisplay" }
+@Rowa A { "@CD" } B { "@CentredDisplay" }
+@Rowa             B { "@CenteredDisplay" }
+@Rowa             B { "@RightDisplay" }
+}
+@EndList
+
+@LP
+@Heading { 11. Lists}
+@LL
+@LI @Code {
+"@List"
+"@ListItem { A list item }"
+"@ListItem { Another list item }"
+"@EndList"
+}
+@LI @Tab
+    @Fmta { @Col @Code A ! @Col @Code B }
+    vmargin { 0.5vx }
+{
+@Rowa
+    A { "@L" }
+    B { "@List" }
+@Rowa
+    A { "@LL" }
+    B { "@LeftList" }
+@Rowa
+    A { "@IL" }
+    B { "@IndentedList" }
+@Rowa
+    A { "@QL" }
+    B { "@QuotedList" }
+@Rowa
+    A { "@CL" }
+    B { "@CentredList" }
+@Rowa
+    B { "@CenteredList" }
+@Rowa
+    A { "@NL" }
+    B { "@NumberedList" }
+@Rowa
+    A { "@RL" }
+    B { "@RomanList" }
+@Rowa
+    A { "@UCRL" }
+    B { "@UCRomanList" }
+@Rowa
+    A { "@AL" }
+    B { "@AlphaList" }
+@Rowa
+    A { "@UCAL" }
+    B { "@UCAlphaList" }
+@Rowa
+    A { "@PNL" }
+    B { "@ParenNumberedList" }
+@Rowa
+    A { "@PRL" }
+    B { "@ParenRomanList" }
+@Rowa
+    A { "@PUCRL" }
+    B { "@ParenUCRomanList" }
+@Rowa
+    A { "@PAL" }
+    B { "@ParenAlphaList" }
+@Rowa
+    A { "@PUCAL" }
+    B { "@ParenUCAlphaList" }
+@Rowa
+    A { "@BL" }
+    B { "@BulletList" }
+@Rowa
+    A { "@SL" }
+    B { "@StarList" }
+@Rowa
+    A { "@DL" }
+    B { "@DashList" }
+}
+@LI @Code {
+"@TaggedList"
+"@TagItem { label } { A list item }"
+"@TagItem { label } { Another list item }"
+"@EndList"
+}
+@LI @Tab
+    @Fmta { @Col @Code A ! @Col @Code B }
+    vmargin { 0.5vx }
+{
+@Rowa
+    A { "@TL" }
+    B { "@TaggedList" }
+@Rowa
+    A { "@WTL" }
+    B { "@WideTaggedList" }
+@Rowa
+    A { "@VWTL" }
+    B { "@VeryWideTaggedList" }
+}
+@EndList
+
+@LP
+@Heading { 12.  Footnotes, endnotes, margin notes }
+@LD @Tab
+    @Fmta { @Col @Code A ! @Col @Code B }
+    vmargin { 0.5vx }
+{
+@Rowa
+    A { "@FootNote { ... }"  }
+    B { "@EndNote { ... }"   }
+@Rowa
+    A { "@LeftNote { ... }"  }
+    B { "@RightNote { ... }" }
+@Rowa
+    A { "@OuterNote { ... }" }
+    B { "@InnerNote { ... }" }
+}
+}
+
+B {
+@Heading { 13.  Floating figures and tables }
+@LD @Tab
+    @Fmta { @Col @Code A ! @Col ! @Col ! @Col @Code B }
+{
+@Rowa
+    A {
+"@Figure"
+"    @Caption { ... }"
+"    @Tag { ... }"
+"@Begin"
+"..."
+"@End @Figure"
+}
+    B {
+"@Table"
+"    @Caption { ... }"
+"    @Tag { ... }"
+"@Begin"
+"..."
+"@End @Table"
+}
+}
+
+@LP
+@Heading { 14.  Tables }
+@LD @Code {
+"@SysInclude { tbl }"
+"@SysInclude { doc }"
+"..."
+"@Tbl"
+"    aformat { @Cell A | @Cell B }"
+"    marginvertical { 0.5vx }"
+"{"
+"@Rowa"
+"    A { ... }"
+"    B { ... }"
+"@Rowa"
+"    ..."
+"}"
+}
+
+@LP
+@Heading { 15.  Equations }
+@LD @Code {
+"@SysInclude { eq }"
+"@SysInclude { doc }"
+"..."
+"@Eq { sum from i=0 to n { r sup i over sqrt pi } }"
+}
+
+@LP
+@Heading { 16.  Basic graphics }
+@LD @Code {
+"grey @Colour { ... }"
+"gray @Color { ... }"
+"@Box { ... }"
+"@CurveBox { ... }"
+"@ShadowBox { ... }"
+"60d @Rotate { ... }"
+"0.71 @Scale { ... }"
+"@QuotedDisplay @Scale { ... }"
+"@IncludeGraphic filename.eps"
+}
+
+@LP
+@Heading { 17.  Miscellaneous }
+@LD lines @Break {
+@Code "@Underline { will be underlined }"
+@Code "@Date"
+@Code "@Time"
+@Code "German @Language { ... }"
+@Code "\# comment to end of line"
+@Code "\"#&/@^{}|~\""   (enclose these characters in quotes)
+}
+}
+} # end second table
+@End @Appendix
diff --git a/doc/user/bas b/doc/user/bas
new file mode 100644
index 0000000..239d35a
--- /dev/null
+++ b/doc/user/bas
@@ -0,0 +1,31 @@
+@Chapter
+    @Title { The Basics }
+    @Tag { basics }
+@Begin
+@LP
+The Lout document formatting system has been designed with the needs of
+the ordinary user very much in mind.  Although the features of Lout are
+virtually endless, and include mathematical equations, diagrams made from
+lines and shapes, bibliographic databases, and so on, the system is very
+simple to use.
+@BeginSections
+@Include { bas_star }
+@Include { bas_objs }
+@Include { bas_spac }
+@Include { bas_char }
+@Include { bas_empt }
+@Include { bas_font }
+@Include { bas_head }
+@Include { bas_par1 }
+@Include { bas_par2 }
+@Include { bas_line }
+@Include { bas_hyph }
+@Include { bas_unde }
+@Include { bas_date }
+@Include { bas_lang }
+@Include { bas_supe }
+@Include { bas_verb }
+@Include { bas_drop }
+@Include { bas_conv }
+@EndSections
+@End @Chapter
diff --git a/doc/user/bas_char b/doc/user/bas_char
new file mode 100644
index 0000000..7efa566
--- /dev/null
+++ b/doc/user/bas_char
@@ -0,0 +1,325 @@
+@Section
+   @Title { Characters }
+   @Tag { characters }
+@Begin
+@PP
+The usual way to get characters into a document is simply to type them as
+characters. @Index characters
+we have been doing all along.  However, for some characters this is not
+possible, either because they have some special meaning, as @Code "{"
+and @Code "}" do, or because the keyboard has no button for them.  This
+section explains how to get every possible character:  every printable
+character in the ISO-LATIN-1 character set, every character in the Adobe
+Systems Symbol font, plus the characters {@Char quotesinglbase},
+{@Char quotedblbase}, {@Char ellipsis}, {@Char OE}, {@Char oe},
+{@Char quotedblleft}, {@Char quotedblright}, {@Char fi},
+{@Char fl}, {@Char endash}, {@Char emdash}, {@Char bullet}, {@Char dagger},
+{@Char daggerdbl}, {@Char florin}, {@Char fraction}, and @Euro.  If it
+exists at all, you will find it here.  ISO-LATIN-2 and Russian characters
+are available separately.  In principle, there is no limit to the characters
+available, but to go beyond those given in this section requires expertise
+in defining encoding vectors and fonts @Cite { $kingston1995lout.expert}.
+@PP
+First up we have the characters that you get simply by typing
+them.  The characters themselves are shown at the left, and what you
+type to get them at the right:
+@ID @OneRow @Tab
+    vmargin { 0.5vx }
+    @Fmta { @Col @CC A ! @Col @Code A ! @Col ! @Col @CC B ! @Col @Code B !
+     @Col ! @Col @CC C ! @Col @Code C ! @Col ! @Col @CC D ! @Col @Code D !
+     @Col ! @Col @CC E ! @Col @Code E ! @Col ! @Col @CC F ! @Col @Code F }
+{
+@Rowa A { ! } B { $ } C { % } D { ' } E { ( } F { ) }
+@Rowa A { * } B { + } C { , } D { - } E { 0 } F { 1 }
+@Rowa A { 2 } B { 3 } C { 4 } D { 5 } E { 6 } F { 7 }
+@Rowa A { 8 } B { 9 } C { : } D { ; } E { < } F { = }
+@Rowa A { > } B { ? } C { A } D { B } E { C } F { D }
+@Rowa A { E } B { F } C { G } D { H } E { I } F { J }
+@Rowa A { K } B { L } C { M } D { N } E { O } F { P }
+@Rowa A { Q } B { R } C { S } D { T } E { U } F { V }
+@Rowa A { W } B { X } C { Y } D { Z } E { [ } F { ] }
+@Rowa A { _ } B { ` } C { a } D { b } E { c } F { d }
+@Rowa A { e } B { f } C { g } D { h } E { i } F { j }
+@Rowa A { k } B { l } C { m } D { n } E { o } F { p }
+@Rowa A { q } B { r } C { s } D { t } E { u } F { v }
+@Rowa A { w } B { x } C { y } D { z } E {   } F {   }
+}
+Next come characters that have buttons but have a special meaning if
+they are typed directly, and consequently have to be enclosed in double
+quotes to turn off this meaning:
+quote.chars @Index { quote characters }
+@ID @OneRow @Tab
+    @Fmta { @Col @CC A ! @Col @Code B ! @Col !
+	    @Col @CC C ! @Col @Code D ! @Col !
+	    @Col @CC E ! @Col @Code F ! @Col !
+	    @Col @CC G ! @Col @Code H ! @Col I
+	    }
+{
+@Rowa
+  A { "\"" } B { "\"\\\"\"" }
+  C { "#"  } D { "\"#\"" }
+  E { "&"  } F { "\"&\"" }
+  G { "/"  } H { "\"/\"" }
+@Rowa
+  A { "@"  } B { "\"@\"" }
+  C { "\\" } D { "\"\\\\\"" }
+  E { "^"  } F { "\"^\"" }
+  G { "{"  } H { "\"{\"" }
+@Rowa
+  A { "|"  } B { "\"|\"" }
+  C { "}"  } D { "\"}\"" }
+  E { "~"  } F { "\"~\"" }
+  G {      } H { "\" \"" }
+  I { (space character) }
+}
+If you think you want {@Code "\""}, you probably really want `` and '',
+for which see below.  You can place whole sequences of characters, special
+or not, inside one pair of double quotes:
+@ID @OneRow @Tab
+    @Fmta { @Col A ! @Col ! @Col @Code B }
+{
+@Rowa
+    A { "jeff/includes/su_crest.eps" }
+    B { "\"jeff/includes/su_crest.eps\"" }
+@Rowa
+    A { "\"@PP\"" }
+    B { "\"\\\"@PP\\\"\"" }
+}
+Next we have some miscellaneous characters which have been deemed
+sufficiently important to deserve their own symbols:
+@ID @OneRow @Tab
+    vmargin { 0.5vx }
+    @Fmta { @Col A ! @Col @Code B ! @Col ! @Col C ! @Col @Code D !
+		                    @Col ! @Col E ! @Col @Code F }
+{
+    @Rowa
+	A { ``		}
+	B { "``"	}
+	C { ,,		}
+	D { ",,"	}
+	E { --		}
+	F { "--"	}
+    @Rowa
+	A { ''		}
+	B { "''"	}
+	C { ...		}
+	D { "..."	}
+	E { ---		}
+	F { "---"	}
+    @Rowa
+	A { @Bullet	bullet @Index @Code "@Bullet"	}
+	B { "@Bullet"	}
+	C { @Star	star @Index @Code "@Star" }
+	D { "@Star"	}
+	E { @ParSym	parsym @Index @Code "@ParSym"	}
+	F { "@ParSym"	}
+    @Rowa
+	A { @SectSym	sectsym @Index @Code "@SectSym" }
+	B { "@SectSym"	}
+	C { @Dagger	dagger @Index @Code "@Dagger"	}
+	D { "@Dagger"	}
+	E { @DaggerDbl	daggerdbl @Index @Code "@DaggerDbl" }
+	F { "@DaggerDbl"}
+    @Rowa
+	A { @CDot	cdot @Index @Code "@CDot"	}
+	B { "@CDot"	}
+	C { @Sterling	sterling @Index @Code "@Sterling" }
+	D { "@Sterling"	}
+	E { @Yen	yen @Index @Code "@Yen"		}
+	F { "@Yen"	}
+    @Rowa
+	A { @Florin	florin @Index @Code "@Florin" }
+	B { "@Florin"	}
+	C { @Degree	degree @Index @Code "@Degree"	}
+	D { "@Degree"	}
+	E { @Minute	minute @Index @Code "@Minute" }
+	F { "@Minute"	}
+    @Rowa
+	A { @Second	second @Index @Code "@Second"	}
+	B { "@Second"	}
+	C { @Lozenge	lozenge @Index @Code "@Lozenge" }
+	D { "@Lozenge"	}
+	E { @Multiply	multiply @Index @Code "@Multiply"}
+	F { "@Multiply"	}
+    @Rowa
+	A { @Divide	divide @Index @Code "@Divide" }
+	B { "@Divide"	}
+	C { @CopyRight	copyright @Index @Code "@CopyRight" }
+	D { "@CopyRight"}
+	E { @Register	register @Index @Code "@Register" }
+	F { "@Register"	}
+    @Rowa
+	A { @TradeMark	trademark @Index @Code "@TradeMark" }
+	B { "@TradeMark"}
+	C { @Euro	euro @Index @Code "@Euro" }
+	D { "@Euro"}
+}
+Next we have the complete ISO-LATIN-1 character set, whose members you
+iso.latin.1 @Index { ISO-LATIN-1 character set }
+char. @Index { @Code "@Char" symbol }
+get with the @Code "@Char" symbol followed by the name of the character
+you want:
+@ID @OneRow -3p @Font @Tab
+    hmargin { 0.1c }
+    vmargin { 0.4vo }
+    @Fmta { @Col @CC @Char A ! @Col @Code { "@Char" A } ! @Col !
+            @Col @CC @Char B ! @Col @Code { "@Char" B } ! @Col !
+            @Col @CC @Char C ! @Col @Code { "@Char" C } ! @Col !
+            @Col @CC @Char D ! @Col @Code { "@Char" D } }
+    @Fmtb { @Col @CC @Char A ! @Col @Code { "@Char" A } ! @Col !
+            @Col ! @Col ! @Col ! @Col ! @Col  ! @Col ! @Col ! @Col  }
+{
+@Rowa A { space } B { exclam } C { quotedbl } D { numbersign }
+@Rowa A { dollar } B { percent } C { ampersand } D { quoteright }
+@Rowa A { parenleft } B { parenright } C { asterisk } D { plus }
+@Rowa A { comma } B { hyphen } C { period } D { slash }
+@Rowa A { zero } B { one } C { two } D { three }
+@Rowa A { four } B { five } C { six } D { seven }
+@Rowa A { eight } B { nine } C { colon } D { semicolon }
+@Rowa A { less } B { equal } C { greater } D { question }
+@Rowa A { at } B { A } C { B } D { C }
+@Rowa A { D } B { E } C { F } D { G }
+@Rowa A { H } B { I } C { J } D { K }
+@Rowa A { L } B { M } C { N } D { O }
+@Rowa A { P } B { Q } C { R } D { S }
+@Rowa A { T } B { U } C { V } D { W }
+@Rowa A { X } B { Y } C { Z } D { bracketleft }
+@Rowa A { backslash } B { bracketright } C { asciicircum } D { underscore }
+@Rowa A { quoteleft } B { a } C { b } D { c }
+@Rowa A { d } B { e } C { f } D { g }
+@Rowa A { h } B { i } C { j } D { k }
+@Rowa A { l } B { m } C { n } D { o }
+@Rowa A { p } B { q } C { r } D { s }
+@Rowa A { t } B { u } C { v } D { w }
+@Rowa A { x } B { y } C { z } D { braceleft }
+@Rowa A { bar } B { braceright } C { asciitilde } D { dotlessi }
+@Rowa A { grave } B { acute } C { circumflex } D { tilde }
+@Rowa A { macron } B { breve } C { dotaccent } D { dieresis }
+@Rowa A { ring } B { cedilla } C { hungarumlaut } D { ogonek }
+@Rowa A { caron } B { space } C { exclamdown } D { cent }
+@Rowa A { sterling } B { currency } C { yen } D { brokenbar }
+@Rowa A { section } B { dieresis } C { copyright } D { ordfeminine }
+@Rowa A { guillemotleft } B { logicalnot } C { hyphen } D { registered }
+@Rowa A { macron } B { degree } C { plusminus } D { twosuperior }
+@Rowa A { threesuperior } B { acute } C { mu } D { paragraph }
+@Rowa A { periodcentered } B { cedilla } C { onesuperior } D { ordmasculine }
+@Rowa A { guillemotright } B { onequarter } C { onehalf } D { threequarters }
+@Rowa A { questiondown } B { Agrave } C { Aacute } D { Acircumflex }
+@Rowa A { Atilde } B { Adieresis } C { Aring } D { AE }
+@Rowa A { Ccedilla } B { Egrave } C { Eacute } D { Ecircumflex }
+@Rowa A { Edieresis } B { Igrave } C { Iacute } D { Icircumflex }
+@Rowa A { Idieresis } B { Eth } C { Ntilde } D { Ograve }
+@Rowa A { Oacute } B { Ocircumflex } C { Otilde } D { Odieresis }
+@Rowa A { multiply } B { Oslash } C { Ugrave } D { Uacute }
+@Rowa A { Ucircumflex } B { Udieresis } C { Yacute } D { Thorn }
+@Rowa A { germandbls } B { agrave } C { aacute } D { acircumflex }
+@Rowa A { atilde } B { adieresis } C { aring } D { ae }
+@Rowa A { ccedilla } B { egrave } C { eacute } D { ecircumflex }
+@Rowa A { edieresis } B { igrave } C { iacute } D { icircumflex }
+@Rowa A { idieresis } B { eth } C { ntilde } D { ograve }
+@Rowa A { oacute } B { ocircumflex } C { otilde } D { odieresis }
+@Rowa A { divide } B { oslash } C { ugrave } D { uacute }
+@Rowa A { ucircumflex } B { udieresis } C { yacute } D { thorn }
+@Rowb A { ydieresis }
+}
+Of course, many of these characters can also be typed directly, or with the
+aid of double quotes, as we have seen.  If your keyboard has accented
+accented @Index { accented characters }
+characters on it, you can type them directly too; if not, you need to
+use the @Code "@Char" symbol, in which case you will probably need
+braces as well:
+@ID @Code "gar{@Char ccedilla}on"
+to distinguish the @Code "@Char" symbol and the character name from
+adjacent letters.
+@PP
+Next we have the Adobe Systems Symbol font, a treasure trove of
+symbol. @Index { Symbol font }
+sym. @Index { @Code "@Sym" symbol }
+exotic characters obtained with the @Code "@Sym" symbol:
+@ID @OneRow -3p @Font @Tab
+    hmargin { 0.1c }
+    vmargin { 0.4vo }
+    @Fmta { @Col @CC @Sym A ! @Col @Code { "@Sym" A } ! @Col !
+            @Col @CC @Sym B ! @Col @Code { "@Sym" B } ! @Col !
+            @Col @CC @Sym C ! @Col @Code { "@Sym" C } ! @Col !
+            @Col @CC @Sym D ! @Col @Code { "@Sym" D } }
+{
+@Rowa A { space } B { exclam } C { universal } D { numbersign }
+@Rowa A { existential } B { percent } C { ampersand } D { suchthat }
+@Rowa A { parenleft } B { parenright } C { asteriskmath } D { plus }
+@Rowa A { comma } B { minus } C { period } D { slash }
+@Rowa A { zero } B { one } C { two } D { three }
+@Rowa A { four } B { five } C { six } D { seven }
+@Rowa A { eight } B { nine } C { colon } D { semicolon }
+@Rowa A { less } B { equal } C { greater } D { question }
+@Rowa A { congruent } B { Alpha } C { Beta } D { Chi }
+@Rowa A { Delta } B { Epsilon } C { Phi } D { Gamma }
+@Rowa A { Eta } B { Iota } C { theta1 } D { Kappa }
+@Rowa A { Lambda } B { Mu } C { Nu } D { Omicron }
+@Rowa A { Pi } B { Theta } C { Rho } D { Sigma }
+@Rowa A { Tau } B { Upsilon } C { sigma1 } D { Omega }
+@Rowa A { Xi } B { Psi } C { Zeta } D { bracketleft }
+@Rowa A { therefore } B { bracketright } C { perpendicular } D { underscore }
+@Rowa A { radicalex } B { alpha } C { beta } D { chi }
+@Rowa A { delta } B { epsilon } C { phi } D { gamma }
+@Rowa A { eta } B { iota } C { phi1 } D { kappa }
+@Rowa A { lambda } B { mu } C { nu } D { omicron }
+@Rowa A { pi } B { theta } C { rho } D { sigma }
+@Rowa A { tau } B { upsilon } C { omega1 } D { omega }
+@Rowa A { xi } B { psi } C { zeta } D { braceleft }
+@Rowa A { bar } B { braceright } C { similar } D { Upsilon1 }
+@Rowa A { minute } B { lessequal } C { fraction } D { infinity }
+@Rowa A { florin } B { club } C { diamond } D { heart }
+@Rowa A { spade } B { arrowboth } C { arrowleft } D { arrowup }
+@Rowa A { arrowright } B { arrowdown } C { degree } D { plusminus }
+@Rowa A { second } B { greaterequal } C { multiply } D { proportional }
+@Rowa A { partialdiff } B { bullet } C { divide } D { notequal }
+@Rowa A { equivalence } B { approxequal } C { ellipsis } D { arrowvertex }
+@Rowa A { arrowhorizex } B { carriagereturn } C { aleph } D { Ifraktur }
+@Rowa A { Rfraktur } B { weierstrass } C { circlemultiply } D { circleplus }
+@Rowa A { emptyset } B { intersection } C { union } D { propersuperset }
+@Rowa A { reflexsuperset } B { notsubset } C {propersubset} D {reflexsubset}
+@Rowa A { element } B { notelement } C { angle } D { gradient }
+@Rowa A { registerserif } B { copyrightserif } C {trademarkserif} D {product}
+@Rowa A { radical } B { dotmath } C { logicalnot } D { logicaland }
+@Rowa A { logicalor } B { arrowdblboth } C { arrowdblleft } D { arrowdblup }
+@Rowa A { arrowdblright } B { arrowdbldown } C { lozenge } D { angleleft }
+@Rowa A { registersans } B { copyrightsans } C {trademarksans} D {summation}
+@Rowa A { parenlefttp } B { parenleftex } C { parenleftbt } D {bracketlefttp}
+    vmargin { 0.5vx }
+@Rowa A { bracketleftex } B { bracketleftbt } C {bracelefttp} D {braceleftmid}
+    vmargin { 0.5vx }
+@Rowa A { braceleftbt } B { braceex } C { angleright } D { integral }
+    vmargin { 0.5vx }
+@Rowa A { integraltp } B { integralex } C { integralbt } D { parenrighttp }
+    vmargin { 0.5vx }
+@Rowa A {parenrightex} B {parenrightbt} C {bracketrighttp} D {bracketrightex}
+    vmargin { 0.5vx }
+@Rowa A { bracketrightbt } B {bracerighttp} C {bracerightmid} D {bracerightbt}
+    vmargin { 0.5vx }
+}
+There is only one Symbol font; it does not come in bold or italic faces
+like the other fonts.  Typing @Code "@B @Sym alpha" is therefore useless,
+and anyway there is no bold @Sym alpha character in any font distributed
+with Lout (except see Section {@NumberOf teq}).
+@PP
+Finally we have a few more characters that you get with the @Code "@Char"
+symbol, although they aren't ISO-LATIN-1 characters.
+@ID @OneRow -3p @Font @Tab
+    hmargin { 0.1c }
+    vmargin { 0.4vo }
+    @Fmta { @Col @CC @Char A ! @Col @Code { "@Char" A } ! @Col !
+            @Col @CC @Char B ! @Col @Code { "@Char" B } ! @Col !
+            @Col @CC @Char C ! @Col @Code { "@Char" C } ! @Col !
+            @Col @CC @Char D ! @Col @Code { "@Char" D } }
+    @Fmtb { @Col @CC @Char A ! @Col @Code { "@Char" A } ! @Col !
+            @Col ! @Col ! @Col ! @Col ! @Col  ! @Col ! @Col ! @Col  }
+{
+@Rowa A { quotesinglbase } B { quotedblbase } C { ellipsis } D { OE }
+@Rowa A { oe } B { quotedblleft } C { quotedblright } D { fi }
+@Rowa A { fl } B { endash } C { emdash } D { bullet }
+@Rowa A { dagger } B { daggerdbl } C { florin } D { fraction }
+}
+Most of these characters are also in the list of `characters important
+enough to deserve their own symbols' given above.
+@End @Section
diff --git a/doc/user/bas_conv b/doc/user/bas_conv
new file mode 100644
index 0000000..cd971b0
--- /dev/null
+++ b/doc/user/bas_conv
@@ -0,0 +1,75 @@
+@Section
+   @Title { Alternative conventions for white space }
+   @Tag { white }
+@Begin
+@PP
+As Section {@NumberOf spaces} explains, when two objects are separated
+by one or more white space characters (spaces, tabs, and newlines), this
+same amount of white space will separate the two objects in the output.
+@PP
+Two other conventions for interpreting these white spaces have been
+used in other document formatting systems.  Roughly, they are:
+@ID @Tab
+    @Fmta { @Col A ! @Col B }
+{
+@Rowa
+    A { troff }
+    B { Like Lout, except that at every point where a sentence ends at
+the end of an input line, add one extra space in the output. }
+@Rowa
+    A { @TeX }
+    B { Replace all sequences of two or more white spaces by one.  Then,
+at every point where a sentence ends, whether or not it is at the end
+of a line, add one extra space in the output. }
+}
+Lout offers these two alternative conventions by means of the
+initialspace. @Index { @Code "@InitialSpace" option }
+@Code "@InitialSpace" option.  This is similar to the
+@Code "@InitialFont" option described at the end of Section
+{@NumberOf fonts}, in that you can set it at the beginning of your
+document, like this:
+@ID @Code {
+"@SysInclude { doc }"
+"@Document"
+"    @InitialSpace { lout }"
+"//"
+"@Text @Begin"
+"..."
+"@End @Text"
+}
+or you can set it in the setup file.  The above example shows the
+default value, {@Code lout}, which produces Lout's usual spacing;
+lout.space @Index { @Code lout spacing }
+troff.space @Index { @Code troff spacing }
+tex.space @Index { @Code tex (@LaTeX) spacing }
+the alternative values are @Code "troff" and {@Code "tex"}.
+@PP
+How to tell whether a sentence has ended is a vexed question.  For
+the @Code "troff" method, Lout looks for a word at the end of a line
+ending in one of `.', `:', `?', or `!' optionally followed by either
+a right quote character or a right parenthesis.  Actually, this depends
+on the current language (Section {@NumberOf languages}); the rule just
+given is for English, and other languages may differ.
+@PP
+The @Code "tex" rule for where a sentence ends is slightly more
+complicated.  Lout looks for a word, not necessarily at the end
+of an input line, which ends as described for @Code "troff" but
+in addition has a lower-case letter preceding that.
+@PP
+In all cases you must use a paragraph symbol, such as @Code "@PP" or
+{@Code "@LP"}, to separate your paragraphs.  The common convention of
+other systems, that a blank line marks a paragraph, is never true of Lout.
+@PP
+Whatever rule is adopted, there are occasional exceptions where you
+will have to indicate explicitly whether you want an ordinary space
+or a between-sentences space.  For this there are two symbols,
+@Code "~" (ordinary space) and {@Code "~~"} (between-sentences
+space).  For example,
+@ID @Code "Dr.~Kingston"
+will produce an ordinary space between the two words, even with
+@Code "tex" which would otherwise consider that spot to be the end
+of a sentence.  Spaces adjacent to these two symbols have no effect on
+the result.  Please note however that @Code "~" produces an
+unbreakable space (that is, one that will never be replaced by the end of
+a line) in contrast to just leaving a space, which is breakable.
+@End @Section
diff --git a/doc/user/bas_date b/doc/user/bas_date
new file mode 100644
index 0000000..16ee433
--- /dev/null
+++ b/doc/user/bas_date
@@ -0,0 +1,84 @@
+@Section
+   @Title { The current date and time }
+   @Tag { date }
+@Begin
+@PP
+The @Code "@Date" and @Code "@Time" symbols produce the current date
+date. @Index @Code "@Date"
+time. @Index @Code "@Time"
+and time:
+@ID @Code "It is now @Time on @Date."
+produces something like
+@ID { It is now @Time on @Date. }
+The result depends on the current language.
+@PP
+Both symbols have a @Code "@Format" option that changes the format of
+the result:
+@ID @Code "@Date @Format { @DayNum\"/\"@MonthNum\"/\"@ShortYear }"
+The result is the @Code "@Format" option with the symbols replaced by
+the appropriate values:
+@ID { @Date @Format { @DayNum"/"@MonthNum"/"@ShortYear } }
+The @Code "/" characters have been enclosed in double quotes for the
+usual reason (Section {@NumberOf characters}).
+@PP
+Here is the full list of symbols that you can use within both
+@Code "@Format" options:
+@ID @OneRow @Tab
+    @Fmta { @Col @Code A ! @Col B }
+    vmargin { 0.5vx }
+{
+@Rowa
+    A { "@Year" }
+    B { The year, e.g. @Code "1994" }
+@Rowa
+    A { "@ShortYear" }
+    B { The last two digits of the year, e.g. @Code "94" }
+@Rowa
+    A { "@Month" }
+    B { The month, e.g. @Code "December" }
+@Rowa
+    A { "@ShortMonth" }
+    B { The month abbreviated, e.g. @Code "Dec" }
+@Rowa
+    A { "@MonthNum" }
+    B { The number of the month, between @Code "1" and @Code "12" }
+@Rowa
+    A { "@Day" }
+    B { The day of the week, e.g. @Code "Saturday" }
+@Rowa
+    A { "@ShortDay" }
+    B { The day abbreviated, e.g. @Code "Sat" }
+@Rowa
+    A { "@DayNum" }
+    B { The day of the month, between @Code "1" and @Code "31" }
+@Rowa
+    A { "@MeriDiem" }
+    B { @Code "a.m." or @Code "p.m." }
+@Rowa
+    A { "@ShortMeriDiem" }
+    B { @Code "am" or @Code "pm" }
+@Rowa
+    A { "@Hour" }
+    B { The hour, between @Code "00" and @Code "23" }
+@Rowa
+    A { "@ShortHour" }
+    B { The hour, between @Code "0" and @Code "23" }
+@Rowa
+    A { "@TwelveHour" }
+    B { The hour, between @Code "1" and @Code "12" }
+@Rowa
+    A { "@Minute" }
+    B { The minute, between @Code "00" and @Code "59" }
+@Rowa
+    A { "@Second" }
+    B { The second, almost always between @Code "00" and @Code "59" }
+}
+The default format for @Code "@Date" in English is
+@ID @Code "@Date @Format { @DayNum @Month, @Year }"
+and the default format for @Code "@Time" in English is
+@ID @Code "@Time @Format { @TwelveHour.@Minute @MeriDiem }"
+Both default formats depend on the current language, and
+so do {@Code "@Month"}, {@Code "@ShortMonth"},
+{@Code "@Day"}, and {@Code "@ShortDay"},{@Code "@MeriDiem" }
+and {@Code "@ShortMeriDiem" }.
+@End @Section
diff --git a/doc/user/bas_drop b/doc/user/bas_drop
new file mode 100644
index 0000000..0978123
--- /dev/null
+++ b/doc/user/bas_drop
@@ -0,0 +1,44 @@
+@Section
+   @Title { Drop capitals }
+   @Tag { dropcaps }
+@Begin
+@PP
+There are two symbols for producing drop capitals, {@Code "@DropCapTwo"}
+drop.cap.two.sym @Index @Code "@DropCapTwo"
+drop.cap.three.sym @Index @Code "@DropCapThree"
+and {@Code "@DropCapThree"}.  Place the capital to be dropped just
+before the symbol, and the rest of the paragraph after it:
+@ID @OneRow @Code {
+"I @DropCapTwo {"
+"t is a truth universally acknowledged, that a single man"
+"in possession of a good fortune, must be in want of a wife."
+"}"
+}
+produces the object
+@ID 3i @Wide {
+I @DropCapTwo {
+t is a truth universally acknowledged, that a single man
+in possession of a good fortune, must be in want of a wife.
+}
+}
+@Code "@DropCapThree" is the same except that the capital is larger
+and spreads over three lines.
+@PP
+Because Lout occasionally gets the height of the enlarged capital
+slightly wrong, there is a @Code "height" option which allows you
+to change the height if you need to:
+@ID @OneRow @Code {
+"H @DropCapTwo height { 1.5v }"
+"{"
+"   ..."
+"}"
+}
+This shows the default value for the height of the capital in
+{@Code "@DropCapTwo"}:  1.5 times the current inter-line
+spacing.  The default height in @Code "@DropCapThree" is {@Code "2.5v"}.
+@PP
+These symbols produce an object which may appear anywhere in the
+usual way.  A paragraph symbol will be needed after the paragraph.  The
+paragraph breaking style of the body of the paragraph will be
+{@Code "adjust nohyphen"}; this cannot be changed at present.
+@End @Section
diff --git a/doc/user/bas_empt b/doc/user/bas_empt
new file mode 100644
index 0000000..c9f615d
--- /dev/null
+++ b/doc/user/bas_empt
@@ -0,0 +1,26 @@
+@Section
+   @Title { The empty object }
+   @Tag { empty }
+@Begin
+@PP
+It is possible to produce examples in which an object is clearly
+empty. @Index { empty object }
+missing:
+@ID @Code "{ @I   }"
+The @Code "@I" symbol is supposed to italicize the following object,
+but in this example there isn't one.  A more plausible example is
+@ID @OneRow @Code {
+"@PP"
+"@PP"
+}
+There are supposed to be paragraph objects between paragraph symbols,
+but here there aren't.
+@PP
+Wherever an object is clearly missing, Lout inserts an @I { empty object },
+which is a rectangle of size zero by zero that prints as nothing.  Here
+are two other ways to get an empty object:
+@ID @Code "{}     \"\""
+Braces always enclose an object, so Lout is obliged to insert an empty
+object between them; the two double quotes make a word with no characters
+in it, which is taken to be an empty object.
+@End @Section
diff --git a/doc/user/bas_font b/doc/user/bas_font
new file mode 100644
index 0000000..65d711e
--- /dev/null
+++ b/doc/user/bas_font
@@ -0,0 +1,629 @@
+@Section
+   @Title { Fonts and font sizes }
+   @Tag { fonts }
+@Begin
+@PP
+A @I font is a collection of characters that may be printed.  For
+font. @Index { font }
+example, here is the Times Roman font:
+@ID @OneRow { Times Base } @Font 0.05c @Space {
+{ @Char space }
+{ @Char exclam }
+{ @Char quotedbl }
+{ @Char numbersign }
+{ @Char dollar }
+{ @Char percent }
+{ @Char ampersand }
+{ @Char quoteright }
+{ @Char parenleft }
+{ @Char parenright }
+{ @Char asterisk }
+{ @Char plus }
+{ @Char comma }
+{ @Char hyphen }
+{ @Char period }
+{ @Char slash }
+{ @Char zero }
+{ @Char one }
+{ @Char two }
+{ @Char three }
+{ @Char four }
+{ @Char five }
+{ @Char six }
+{ @Char seven }
+{ @Char eight }
+{ @Char nine }
+{ @Char colon }
+{ @Char semicolon }
+{ @Char less }
+{ @Char equal }
+{ @Char greater }
+{ @Char question }
+{ @Char at }
+{ @Char bracketleft }
+{ @Char backslash }
+{ @Char bracketright }
+{ @Char asciicircum }
+{ @Char underscore }
+{ @Char quoteleft }
+//1vx
+{ @Char A }
+{ @Char B }
+{ @Char C }
+{ @Char D }
+{ @Char E }
+{ @Char F }
+{ @Char G }
+{ @Char H }
+{ @Char I }
+{ @Char J }
+{ @Char K }
+{ @Char L }
+{ @Char M }
+{ @Char N }
+{ @Char O }
+{ @Char P }
+{ @Char Q }
+{ @Char R }
+{ @Char S }
+{ @Char T }
+{ @Char U }
+{ @Char V }
+{ @Char W }
+{ @Char X }
+{ @Char Y }
+{ @Char Z }
+//1vx
+{ @Char a }
+{ @Char b }
+{ @Char c }
+{ @Char d }
+{ @Char e }
+{ @Char f }
+{ @Char g }
+{ @Char h }
+{ @Char i }
+{ @Char j }
+{ @Char k }
+{ @Char l }
+{ @Char m }
+{ @Char n }
+{ @Char o }
+{ @Char p }
+{ @Char q }
+{ @Char r }
+{ @Char s }
+{ @Char t }
+{ @Char u }
+{ @Char v }
+{ @Char w }
+{ @Char x }
+{ @Char y }
+{ @Char z }
+//1vx
+{ @Char braceleft }
+{ @Char bar }
+{ @Char braceright }
+{ @Char asciitilde }
+{ @Char dotlessi }
+{ @Char grave }
+{ @Char acute }
+{ @Char circumflex }
+{ @Char tilde }
+{ @Char macron }
+{ @Char breve }
+{ @Char dotaccent }
+{ @Char dieresis }
+{ @Char ring }
+{ @Char cedilla }
+{ @Char hungarumlaut }
+{ @Char ogonek }
+{ @Char caron }
+{ @Char space }
+{ @Char exclamdown }
+{ @Char cent }
+{ @Char sterling }
+{ @Char currency }
+{ @Char yen }
+{ @Char brokenbar }
+{ @Char section }
+{ @Char dieresis }
+{ @Char copyright }
+{ @Char ordfeminine }
+{ @Char guillemotleft }
+{ @Char logicalnot }
+{ @Char hyphen }
+{ @Char registered }
+{ @Char macron }
+{ @Char degree }
+{ @Char plusminus }
+{ @Char twosuperior }
+{ @Char threesuperior }
+{ @Char acute }
+{ @Char mu }
+{ @Char paragraph }
+{ @Char periodcentered }
+{ @Char cedilla }
+{ @Char onesuperior }
+{ @Char ordmasculine }
+{ @Char guillemotright }
+{ @Char onequarter }
+{ @Char onehalf }
+{ @Char threequarters }
+{ @Char questiondown }
+//1vx
+{ @Char Agrave }
+{ @Char Aacute }
+{ @Char Acircumflex }
+{ @Char Atilde }
+{ @Char Adieresis }
+{ @Char Aring }
+{ @Char AE }
+{ @Char Ccedilla }
+{ @Char Egrave }
+{ @Char Eacute }
+{ @Char Ecircumflex }
+{ @Char Edieresis }
+{ @Char Igrave }
+{ @Char Iacute }
+{ @Char Icircumflex }
+{ @Char Idieresis }
+{ @Char Eth }
+{ @Char Ntilde }
+{ @Char Ograve }
+{ @Char Oacute }
+{ @Char Ocircumflex }
+{ @Char Otilde }
+{ @Char Odieresis }
+{ @Char multiply }
+{ @Char Oslash }
+{ @Char Ugrave }
+{ @Char Uacute }
+{ @Char Ucircumflex }
+{ @Char Udieresis }
+{ @Char Yacute }
+{ @Char Thorn }
+//1vx
+{ @Char germandbls }
+{ @Char agrave }
+{ @Char aacute }
+{ @Char acircumflex }
+{ @Char atilde }
+{ @Char adieresis }
+{ @Char aring }
+{ @Char ae }
+{ @Char ccedilla }
+{ @Char egrave }
+{ @Char eacute }
+{ @Char ecircumflex }
+{ @Char edieresis }
+{ @Char igrave }
+{ @Char iacute }
+{ @Char icircumflex }
+{ @Char idieresis }
+{ @Char eth }
+{ @Char ntilde }
+{ @Char ograve }
+{ @Char oacute }
+{ @Char ocircumflex }
+{ @Char otilde }
+{ @Char odieresis }
+{ @Char divide }
+{ @Char oslash }
+{ @Char ugrave }
+{ @Char uacute }
+{ @Char ucircumflex }
+{ @Char udieresis }
+{ @Char yacute }
+{ @Char thorn }
+{ @Char ydieresis }
+}
+and here is the Times Italic font:
+@ID @OneRow { Times Slope } @Font 0.05c @Space {
+{ @Char space }
+{ @Char exclam }
+{ @Char quotedbl }
+{ @Char numbersign }
+{ @Char dollar }
+{ @Char percent }
+{ @Char ampersand }
+{ @Char quoteright }
+{ @Char parenleft }
+{ @Char parenright }
+{ @Char asterisk }
+{ @Char plus }
+{ @Char comma }
+{ @Char hyphen }
+{ @Char period }
+{ @Char slash }
+{ @Char zero }
+{ @Char one }
+{ @Char two }
+{ @Char three }
+{ @Char four }
+{ @Char five }
+{ @Char six }
+{ @Char seven }
+{ @Char eight }
+{ @Char nine }
+{ @Char colon }
+{ @Char semicolon }
+{ @Char less }
+{ @Char equal }
+{ @Char greater }
+{ @Char question }
+{ @Char at }
+{ @Char bracketleft }
+{ @Char backslash }
+{ @Char bracketright }
+{ @Char asciicircum }
+{ @Char underscore }
+{ @Char quoteleft }
+//1vx
+{ @Char A }
+{ @Char B }
+{ @Char C }
+{ @Char D }
+{ @Char E }
+{ @Char F }
+{ @Char G }
+{ @Char H }
+{ @Char I }
+{ @Char J }
+{ @Char K }
+{ @Char L }
+{ @Char M }
+{ @Char N }
+{ @Char O }
+{ @Char P }
+{ @Char Q }
+{ @Char R }
+{ @Char S }
+{ @Char T }
+{ @Char U }
+{ @Char V }
+{ @Char W }
+{ @Char X }
+{ @Char Y }
+{ @Char Z }
+//1vx
+{ @Char a }
+{ @Char b }
+{ @Char c }
+{ @Char d }
+{ @Char e }
+{ @Char f }
+{ @Char g }
+{ @Char h }
+{ @Char i }
+{ @Char j }
+{ @Char k }
+{ @Char l }
+{ @Char m }
+{ @Char n }
+{ @Char o }
+{ @Char p }
+{ @Char q }
+{ @Char r }
+{ @Char s }
+{ @Char t }
+{ @Char u }
+{ @Char v }
+{ @Char w }
+{ @Char x }
+{ @Char y }
+{ @Char z }
+//1vx
+{ @Char braceleft }
+{ @Char bar }
+{ @Char braceright }
+{ @Char asciitilde }
+{ @Char dotlessi }
+{ @Char grave }
+{ @Char acute }
+{ @Char circumflex }
+{ @Char tilde }
+{ @Char macron }
+{ @Char breve }
+{ @Char dotaccent }
+{ @Char dieresis }
+{ @Char ring }
+{ @Char cedilla }
+{ @Char hungarumlaut }
+{ @Char ogonek }
+{ @Char caron }
+{ @Char space }
+{ @Char exclamdown }
+{ @Char cent }
+{ @Char sterling }
+{ @Char currency }
+{ @Char yen }
+{ @Char brokenbar }
+{ @Char section }
+{ @Char dieresis }
+{ @Char copyright }
+{ @Char ordfeminine }
+{ @Char guillemotleft }
+{ @Char logicalnot }
+{ @Char hyphen }
+{ @Char registered }
+{ @Char macron }
+{ @Char degree }
+{ @Char plusminus }
+{ @Char twosuperior }
+{ @Char threesuperior }
+{ @Char acute }
+{ @Char mu }
+{ @Char paragraph }
+{ @Char periodcentered }
+{ @Char cedilla }
+{ @Char onesuperior }
+{ @Char ordmasculine }
+{ @Char guillemotright }
+{ @Char onequarter }
+{ @Char onehalf }
+{ @Char threequarters }
+{ @Char questiondown }
+//1vx
+{ @Char Agrave }
+{ @Char Aacute }
+{ @Char Acircumflex }
+{ @Char Atilde }
+{ @Char Adieresis }
+{ @Char Aring }
+{ @Char AE }
+{ @Char Ccedilla }
+{ @Char Egrave }
+{ @Char Eacute }
+{ @Char Ecircumflex }
+{ @Char Edieresis }
+{ @Char Igrave }
+{ @Char Iacute }
+{ @Char Icircumflex }
+{ @Char Idieresis }
+{ @Char Eth }
+{ @Char Ntilde }
+{ @Char Ograve }
+{ @Char Oacute }
+{ @Char Ocircumflex }
+{ @Char Otilde }
+{ @Char Odieresis }
+{ @Char multiply }
+{ @Char Oslash }
+{ @Char Ugrave }
+{ @Char Uacute }
+{ @Char Ucircumflex }
+{ @Char Udieresis }
+{ @Char Yacute }
+{ @Char Thorn }
+//1vx
+{ @Char germandbls }
+{ @Char agrave }
+{ @Char aacute }
+{ @Char acircumflex }
+{ @Char atilde }
+{ @Char adieresis }
+{ @Char aring }
+{ @Char ae }
+{ @Char ccedilla }
+{ @Char egrave }
+{ @Char eacute }
+{ @Char ecircumflex }
+{ @Char edieresis }
+{ @Char igrave }
+{ @Char iacute }
+{ @Char icircumflex }
+{ @Char idieresis }
+{ @Char eth }
+{ @Char ntilde }
+{ @Char ograve }
+{ @Char oacute }
+{ @Char ocircumflex }
+{ @Char otilde }
+{ @Char odieresis }
+{ @Char divide }
+{ @Char oslash }
+{ @Char ugrave }
+{ @Char uacute }
+{ @Char ucircumflex }
+{ @Char udieresis }
+{ @Char yacute }
+{ @Char thorn }
+{ @Char ydieresis }
+}
+As their names imply, these two fonts belong to the @I { Times family },
+a collection of fonts designed to go well together.  Every font has a
+@I { family name }, such as Times, Helvetica, or Courier, and a
+family.name @Index { family name of font }
+face.name @Index { face name of font }
+@I { face name }, such as Roman or Italic.  To find out how to
+get the unusual characters, see Section {@NumberOf characters}.
+@PP
+Documents look best when they use just one font family, so the most
+common need is to change to a different face within the current
+family.  We have already seen {@Code "@I"}, which changes to the Italic
+face of the current family; there are six such symbols:
+b. @Index @Code "@B"
+i. @Index @Code "@I"
+bi. @Index @Code "@BI"
+ii. @Index @Code "@II"
+s. @Index @Code "@S"
+r. @Index @Code "@R"
+@ID @OneRow @Tab
+    @Fmta { @Col @Code A ! @Col B }
+{
+@Rowa
+    A { "@B { Hello World }" }
+    B {  @B { Hello World }  }
+@Rowa
+    A { "@I { Hello World }" }
+    B {  @I { Hello World }  }
+@Rowa
+    A { "@BI { Hello World }" }
+    B {  @BI { Hello World }  }
+@Rowa
+    A { "@II { Hello World }" }
+    B {  @II { Hello World }  }
+@Rowa
+    A { "@S { Hello World }" }
+    B {  @S { Hello World }  }
+@Rowa
+    A { "@R { Hello World }" }
+    B {  @R { Hello World }  }
+}
+The symbols' names stand for Bold, Italic, Bold-Italic, Italic-Italic
+(see below), Small capitals, and Roman.  It is conventional to use Bold
+for headings; Italic for emphasis, terms being defined, and subsidiary
+headings; and Roman for the rest.  Small capitals are not really a
+different font; they are
+small.caps @Index { small capitals }
+made on demand from the current font.  So you can write, for example,
+@ID @Code "@I @S { Hello World }"
+and get @I @S { Hello World }.
+@PP
+The @Code "@R" symbol is almost unnecessary, since the document as a
+whole is set in a Roman face; but it is occasionally useful:
+@ID @Code "@I { An Italic sentence with one @R Roman word }"
+produces
+@ID @I { An Italic sentence with one @R Roman word }
+This illustrates the general principle that the effect of a font symbol
+on the following object is subject to font symbols within that object.
+@PP
+When part of a title is to be set in italic font, neither @Code "@I"
+nor @Code "@BI" is suitable because the part should appear in bold
+italics in the title itself, but in ordinary italics in running headers
+and the table of contents.  The @Code "@II" symbol is the one for this
+situation:  it produces bold italics when the current font is bold,
+and ordinary italics otherwise.
+@PP
+Changing families is a little more complicated.  Here is the complete
+list of font families and their faces available with Basser Lout Version 3:
+@ID @OneRow @Tab
+    @Fmta { @Col @Code A ! @Col { ragged nohyphen } @Break @Code B }
+{
+@Rowa
+    A { AvantGarde }
+    B { Base Slope Bold BoldSlope BoldObl Book BookOblique
+CondBold CondBook CondDemi CondMedium Demi DemiOblique
+ExtraLight ExtraLightObl Medium MediumObl }
+@Rowa
+    A { Bookman }
+    B { Base Slope Bold BoldSlope BoldItalic Demi DemiItalic
+Light LightItalic Medium MediumItalic }
+@Rowa
+    A { Chancery }
+    B { Base Slope Bold BoldSlope
+Roman Bold Italic Light Demi LightItalic MediumItalic
+}
+@Rowa
+    A { Courier }
+    B { Base Slope Bold BoldSlope BoldOblique Oblique }
+@Rowa
+    A { Helvetica }
+    B { Base Slope Bold BoldSlope Black BlackOblique
+BoldOblique Compressed Cond CondBlack CondBlackObl
+CondBold CondBoldObl CondLight CondLightObl
+CondOblique ExtraCompressed
+Light LightOblique Narrow NarrowBold NarrowBoldObl
+NarrowObl Oblique UltraCompressed }
+@Rowa
+    A { Schoolbook }
+    B { Base Slope Bold BoldSlope BoldItalic Italic Roman }
+@Rowa
+    A { Palatino }
+    B { Base Slope Bold BoldSlope BoldItalic
+BoldItalicOsF BoldOsF Italic ItalicOsF Roman SC }
+@Rowa
+    A { Symbol }
+    B { Base Slope Bold BoldSlope }
+@Rowa
+    A { Times }
+    B { Base Slope Bold BoldSlope BoldItalic
+BoldItalicOsF BoldSC ExtraBold Italic ItalicOsF
+Roman RomanSC Semibold SemiboldItalic }
+@Rowa
+    A { Dingbats }
+    B { Base Slope Bold BoldSlope }
+}
+Lout understands all these fonts, but your printing device may not.  Times,
+Helvetica, Courier, and Symbol at least seem to be ubiquitous, although
+not in every face.  These fonts work only with languages that use the
+Latin1 character set; consult Section {@NumberOf languages} for more
+information about this.  It is not difficult for a Lout expert to extend this
+list @Cite { $kingston1995lout.expert }.
+@PP
+It is a convention in Lout that every font family should at least
+base. @Index { @Code Base font }
+slope. @Index { @Code Slope font }
+bold. @Index { @Code Bold font }
+boldslope. @Index { @Code BoldSlope font }
+contain faces called @Code { Base }, @Code { Slope }, @Code { Bold },
+and @Code { BoldSlope }, and these faces are what the @Code { "@R" },
+@Code { "@I" }, @Code { "@B" }, and @Code { "@BI" } symbols give you.  But
+this convention is something of a fiction for two reasons.  First,
+some font families don't have faces that could reasonably be described as
+bold or whatever.  In particular, the @Code Symbol family contains just
+one face, and all four conventional face names produce that face.  Second,
+the four conventional face names are not names that typographers actually
+use, @Code { Bold } excepted.  @Code { Slope } produces an italic face
+in some families and an oblique one in others.  As the table shows, the
+true names are available if you want to use them, but it is very convenient
+to have a @Code { Slope } face that is guaranteed to exist no matter which
+family is used.
+@PP
+The @Code "@Font" symbol changes the font of the following object.  For
+font.sym @Index @Code "@Font"
+example,
+@ID @Code "{ Helvetica Slope } @Font { Hello World }"
+produces
+@ID { Helvetica Slope } @Font { Hello World }
+When changing to a different family, a face name must follow the family
+name; but when changing face within a family, just the face name is
+sufficient.
+@PP
+To make the characters larger or smaller, you need to change the
+font.size @Index { font size }
+@I { font size }, which can also be done with the @Code "@Font"
+symbol.  Font sizes are traditionally measured in {@I points}:  there
+are 72 points to one inch, and the most common font sizes are 12 point
+and 10 point.  However, as Section {@NumberOf objects} explains in
+detail, any length including fractional lengths is acceptable:
+@ID @Code "24p @Font { Hello World }"
+changes to 24 point size, producing
+@ID 24p @Font { Hello World }
+It is also possible to specify a font size relative to the current
+size:  @Code "+2p" means two points larger, @Code "-2p" means two
+points smaller, and @Code "1.5f" means 1.5 times the current font
+size.
+@PP
+For the convenience of people who use fixed width fonts such as
+Courier, there is an @Code "@F" symbol which switches to a
+fixed width font family:
+@ID @Code "@F { Hello world }"
+produces
+@ID @F { Hello world }
+It is the same as writing @Code "{ Courier Base -1p } @Font ..."
+with the @Code "-1p" included to compensate for the relatively
+large appearance of the Courier font.
+@PP
+The document as a whole will be set in @Code { Times Base 12p }.  To
+change this you need to change the @Code "@InitialFont" option, for
+initialfont. @Index @Code "@InitialFont"
+example to
+@ID @Code "@InitialFont { Helvetica Base 10p }"
+to get Helvetica 10 point.  You must give all three parts in
+{@Code "@InitialFont"}:  family, face, size.  If you are using your own
+setup file, as explained in Section {@NumberOf setup}, you can find the
+@Code "@InitialFont" option there.  If not, you can set it at the
+beginning of your document as explained in Section {@NumberOf ordinary}.
+@PP
+There are two features that make fonts look better on the
+page.  @I Ligatures are pairs of letters run together; the most
+ligatures. @Index { ligatures }
+common ligatures are `fi' and `fl.'  @I Kerning is moving adjacent
+kerning. @Index { kerning }
+letters closer together, for example in `VA.'  Lout considers
+ligatures and kerning to be integral parts of each font; you can prevent
+them from happening only by enclosing one of the letters in a
+@Code "@OneCol" symbol, as in {@Code "@OneCol { V }A" }.
+@End @Section
diff --git a/doc/user/bas_head b/doc/user/bas_head
new file mode 100644
index 0000000..4410c08
--- /dev/null
+++ b/doc/user/bas_head
@@ -0,0 +1,32 @@
+@Section
+   @Title { Headings }
+   @Tag { headings }
+@Begin
+@PP
+The @Code "@Heading" symbol makes the following object into a
+heading. @Index @Code "@Heading"
+heading.  Actually, all it does is change the font, so if you want a
+centred heading you have to display it as well:
+@ID @OneRow @Code {
+"@Display @Heading { A Centred Heading }"
+"Following text"
+}
+If you want a left-justified heading, use @Code "@LeftDisplay" instead
+of @Code {"@Display"}.  Alternatively, you can use no display symbol at
+all, but then you will need paragraph symbols before and after:
+@ID @OneRow @Code {
+"@DP"
+"@Heading { A Left-Justified Heading }"
+"@PP"
+"Following text"
+}
+The font used is @Code Bold in the current family, although you can
+change this by changing the @Code "@HeadingFont" option in the setup
+headingfont. @Index @Code "@HeadingFont"
+file (Section {@NumberOf setup}).
+@PP
+The @Code "@Heading" symbol may be used with any type of document, but it
+is really intended only for simple ones.  In complex documents, large-scale
+structure symbols (Section {@NumberOf largescale}) are usually more
+appropriate.
+@End @Section
diff --git a/doc/user/bas_hyph b/doc/user/bas_hyph
new file mode 100644
index 0000000..6997f41
--- /dev/null
+++ b/doc/user/bas_hyph
@@ -0,0 +1,37 @@
+@Section
+   @Title { Hyphenation }
+   @Tag { hyph }
+@Begin
+@PP
+The @Code "@Break" symbol also controls hyphenation:  @Code "hyphen"
+hyphenation. @Index hyphenation
+@Code "@Break" turns it on, @Code "nohyphen" @Code "@Break" turns it
+off.  For example, ragged breaking is often done without hyphenation:
+@ID @OneRow @Code {
+"@IndentedDisplay { ragged nohyphen } @Break {"
+"This little paragraph will appear with"
+"ragged ends to its lines."
+"}"
+}
+Lout's method of choosing hyphenation points is copied from the @TeX
+tex.hyph @SubIndex { hyphenation }
+system, except that Lout will never place a hyphen within a sequence
+of characters that form a ligature (fl and
+ligatures.hyph @SubIndex { and hyphenation }
+fi are the most common ligatures).
+@PP
+Hyphenation usually works well by itself; you should never need to
+interfere with its ideas of what to do.  However, if you do want
+to tell Lout where you think a hyphen could be inserted, you can
+use the @Code "&-" symbol:
+@IndentedDisplay @Code {
+"after&-math"
+}
+If @Code "&-" occurs directly after a hyphen character, hyphenation
+will be permitted but no extra hyphen will be inserted.  To prevent
+hyphenation of a word, enclose the word in a @Code "@OneCol" symbol.
+@PP
+To turn hyphenation off throughout the document, you need to set the
+@Code "@InitialBreak" option to {@Code "nohyphen"}, as described at the
+end of Section {@NumberOf linespace}.
+@End @Section
diff --git a/doc/user/bas_lang b/doc/user/bas_lang
new file mode 100644
index 0000000..3b32a94
--- /dev/null
+++ b/doc/user/bas_lang
@@ -0,0 +1,85 @@
+@Section
+   @Title { Languages other than English }
+   @Tag { languages }
+@Begin
+@PP
+When part of a document is written in a language other than English,
+languages. @Index { languages other than English }
+Lout should be informed of this using the @Code "@Language" symbol:
+language. @Index @Code "@Language"
+@ID @OneRow @Code {
+"... the garter, he said:  French @Language { `Honi soit qui mal y"
+"pense' }, and this saying ..."
+}
+Changing language is quite analogous to changing font using the
+@Code "@Font" symbol.
+@PP
+Since accented characters (Section {@NumberOf characters}) are always
+available irrespective of the language, at first sight it might seem
+that there is no need to bother informing Lout what language you are
+writing in.  However, words are hyphenated differently depending on the
+hyphenation.languages @SubIndex { in languages other than English }
+language, and some symbols have different results in different
+languages.  For example,
+@ID @Code "Danish @Language @Date"
+produces
+@ID { Danish @Language @Date }
+date.languages @SubIndex { in languages other than English }
+time.languages @SubIndex { in languages other than English }
+lists.languages @SubIndex { in languages other than English }
+and the alphabetic list symbols of Section {@NumberOf lists} also
+vary with the current language.  So it's worth doing for the sake of
+knowing that non-English parts will appear as they should.
+@PP
+At the time of writing, the following languages were available:
+@ID @OneRow @Code {
+Czech Cesky Cestina
+Danish Dansk
+Dutch Nederlands
+English
+EnglishUK
+Finnish Suomi
+French Francais Fran{@Char ccedilla}ais
+German Deutsch
+Hungarian Magyar
+Italian Italiano
+Norwegian Norsk
+Polish Polski
+Russian
+Slovenian Slovenia Slovenija
+Spanish Espa{@Char ntilde}ol
+Swedish Svenska
+}
+As shown, most languages have alternative names, all equally acceptable
+to the @Code "@Language" symbol.  @Code "EnglishUK" differs from
+@Code "English" only by applying hyphenation rules said to be more
+appropriate for British English.  Hungarian does not yet allow
+hyphenation.
+@PP
+If your entire document is in a language other than English, you need
+to change the @Code "@InitialLanguage" option:
+initiallanguage. @Index @Code "@InitialLanguage"
+@ID @Code "@InitialLanguage { Deutsch }"
+If you are using your own setup file (Section {@NumberOf setup}), you
+can change it there.  If not, you can change it at the start of your
+document, as explained in Section {@NumberOf ordinary}.
+@PP
+Czech, Polish, and Slovenian use the ISO-LATIN-2 character set, and
+users of these languages have to place
+@ID @Code "@SysInclude { latin2 }"
+at the very start of their documents in order to get access to the
+ISO-LATIN-2 versions of the fonts.  These have family names such as
+TimesCE, CourierCE, HelveticaCE, and so on, to distinguish them
+from the same fonts encoded in ISO-LATIN-1.  The face names are
+unchanged.  Consult file @Code "latin2.fd" in the standard include
+directory for a complete list of these fonts.
+@PP
+Russian uses Cyrillic characters.  In principle, users of Russian
+have to place
+@ID @Code "@SysInclude { russian }"
+at the very start of their documents in order to get access to
+Cyrillic fonts.  However no such fonts are distributed
+with the current version of Lout, so this line does nothing at
+present.  Other left-to-right languages are easily added, so
+consult the author if your language is not listed.
+@End @Section
diff --git a/doc/user/bas_line b/doc/user/bas_line
new file mode 100644
index 0000000..3210cdc
--- /dev/null
+++ b/doc/user/bas_line
@@ -0,0 +1,43 @@
+@Section
+   @Title { Line spacing }
+   @Tag { linespace }
+@Begin
+@PP
+The @Code "@Break" symbol also controls the amount of space placed
+line.spacing @Index { line spacing }
+between the lines of paragraphs.  This distance is best given using the
+@Code "v" unit of measurement:  @Code "1v" is the current line
+separation (see Section {@NumberOf objects} for a description of
+lengths in general).  For example,
+@ID @Code "2vx @Break ..."
+produces double spacing in the paragraphs of the following object, and
+double.spacing @Index { double spacing }
+@ID @Code "0.9vx @Break ..."
+produces cramped spacing, which can be useful in large tables that don't
+quite fit on one page.  The @Code "x" following the @Code "v" is required,
+but its meaning is beyond our scope @Cite { $kingston1995lout.expert }.
+@PP
+To set the entire document in a different line spacing from the
+initialbreak @Index @Code "@InitialBreak"
+default, you need to change the @Code "@InitialBreak" option.  If you
+are using your own setup file (Section {@NumberOf setup}),
+change it there.  If not, you can change it at the beginning of your
+document, as described in Section {@NumberOf ordinary}.
+@PP
+The default value of the @Code "@InitialBreak" option produces the
+@Code "adjust" paragraph breaking style with a line spacing of 1.20
+times the current (that is, the initial) font size, and hyphenation
+on:
+@ID @Code "@InitialBreak { adjust 1.20fx hyphen }"
+To get double spacing, change it to
+@ID @Code "@InitialBreak { adjust 2.40fx hyphen }"
+To get ragged paragraphs with hyphenation off, change it to
+@ID @Code "@InitialBreak { ragged 1.20fx nohyphen }"
+and so on.  It is a good idea to define the initial line spacing using
+the @Code "f" unit, since then if you change the initial font size the
+line spacing will change with it.  However, any length (Section
+{@NumberOf objects}) with an @Code "x" appended will do:  @Code "14px"
+for 14 point, @Code "0.5cx" for 0.5 centimetres, etc.  Don't use the
+@Code "v" unit though, because it refers to some @I previous line
+spacing, whereas here we are defining the line spacing for the first time.
+@End @Section
diff --git a/doc/user/bas_objs b/doc/user/bas_objs
new file mode 100644
index 0000000..f6a2f78
--- /dev/null
+++ b/doc/user/bas_objs
@@ -0,0 +1,141 @@
+@Section
+   @Title { Objects, symbols, options, and lengths }
+   @Tag { objects }
+@Begin
+@PP
+Lout is not concerned with the exact shapes of individual characters,
+only with the rectangular areas they occupy:
+@ID {
+@Box margin { 0c } B &
+@Box margin { 0c } i &
+@Box margin { 0c } o &
+@Box margin { 0c } l &
+@Box margin { 0c } o &
+@Box margin { 0c } g &
+@Box margin { 0c } y
+}
+When letters join together into a word, the result is a larger rectangle
+enclosing them all:
+@ID @Box margin { 0c } Biology
+When words join into lines we get even larger rectangles:
+@ID @Box margin { 0c } { Biology is the study of living things. }
+and so on up through paragraphs and columns to the largest rectangles,
+which are pages.  We call any such rectangle, whether made up of one
+character, one word, one line, one paragraph, one page, or anything
+object. @Index { object }
+else, an @I { object }.
+@PP
+We also often say, for example, `the object
+{@Code "@I { Hello world }"},' referring to a piece of Lout's input as
+an object.  This makes sense because we are anticipating the result
+produced, in this case the object @I { Hello world }.  It's true that if
+a line break happens to fall between @I Hello and @I { world }, the
+result of @Code "@I { Hello world }" is not a single rectangle.  We
+answer this by thinking of objects as existing before paragraph breaking
+rearranges them.
+@PP
+Not everything is an object, however.  @Code "@I" alone is not an object,
+merely a symbol with the potential of producing an object when given an
+object to work on.  To understand this, ask yourself what rectangle
+@Code "@I" alone could possibly represent:  there is no such rectangle.
+@PP
+It helps to imagine the assembly of objects taking place before your
+eyes.  Look at @Code Hello and imagine the objects H, e, l, l, o being
+assembled into the larger object Hello; look at @Code "Hello world"
+and imagine Hello and world being assembled into Hello world.  When
+looking at
+@ID @Code "@I { Hello world }"
+you need to imagine the @Code "@I" symbol consuming the following object,
+Hello world, and replacing it with the object @I { Hello world }.  Here
+is another example:
+@ID @Code "@CurveBox { Hello world }"
+The @Code "@CurveBox" symbol (Section {@NumberOf boxes}) consumes
+Hello world and replaces it with the object
+@ID @CurveBox { Hello world }
+This brings us to a basic principle of Lout:  @I { Where you can put
+one object, you can put any object }.  A few examples will show the
+vast range of possibilities opened up by this:
+@ID @Code "@CurveBox { @I Hello world }"
+produces
+@ID @CurveBox { @I Hello world }
+It doesn't bother @Code "@CurveBox" if one of the words inside
+it is in italics.  Next:
+@ID @Code "@I @CurveBox { Hello world }"
+produces
+@ID @I @CurveBox { Hello world }
+The object following @Code "@I" cannot be just @Code {"@CurveBox"},
+since that is not an object by itself (it needs to be applied to some
+object first).  So the object following @Code "@I" is
+@Code {"@CurveBox { Hello world }"}, and it is this that is consumed by
+@Code "@I" and modified.  The @Code "@I" symbol is happy to hunt
+through the object looking for words to italicize.  We could go on
+indefinitely in this way, producing
+@ID @CurveBox { @CurveBox Hello @CurveBox world }
+for example by {@Code "@CurveBox { @CurveBox Hello @CurveBox world }"}.
+@PP
+Symbols like @Code "@CurveBox" often have @I { options }, which are
+option. @Index { option }
+subsidiary symbols that modify the result.  For example, @Code "@CurveBox"
+has @Code "margin" and @Code "paint" options:
+@ID @OneRow @Code {
+"@CurveBox"
+"    margin { 0.5c }"
+"    paint { lightgrey }"
+"{ Hello world }"
+}
+Options come immediately after the main symbol, before any following
+object.  Each consists of the option name followed by the value we want
+the option to have, always enclosed in braces.  Setting out options on
+separate lines as we have done above makes them easy to see but is not
+compulsory (end of line and space are the same to Lout).  The result,
+naturally enough, is a curved box with a 0.5 centimetre margin around
+its contents, painted light grey:
+@ID @CurveBox
+    margin { 0.5c }
+    paint { lightgrey }
+{ Hello world }
+Options are optional:  if you leave out an option, Lout supplies a
+sensible @I default value for it.  Options may be given in any
+order.  They are a very useful way of adding flexibility to symbols
+without cluttering things up when they aren't needed.  They also help
+with learning:  you can learn the basic symbol first and worry about
+the options later.
+@PP
+Whenever a length is required, as in the @Code margin option above, it
+length. @Index { length }
+centimetres. @Index { centimetres }
+inches. @Index { inches }
+point.unit @Index { point (unit of measurement) }
+em.unit @Index { em (unit of measurement) }
+f.unit @Index { @Code f unit of measurement }
+s.unit @Index { @Code s unit of measurement }
+v.unit @Index { @Code v unit of measurement }
+units.of @Index { units of measurement }
+may be given using any one of the following seven units of measurement:
+@ID @OneRow @Tab
+    @Fmta { @Col @Code A ! @Col B }
+    vmargin { 0.5vx }
+{
+@Rowa A { c } B { Centimetres }
+@Rowa A { i } B { Inches ({@Code "1i"} = {@Code "2.54c"}) }
+@Rowa A { p } B { Points ({@Code "72p"} = {@Code "1i"}) }
+@Rowa A { m } B { Ems ({@Code "12m"} = {@Code "1i"}) }
+@Rowa A { f } B { @Code "1f" is the current font size }
+@Rowa A { s } B { @Code "1s" is the current width of a space character }
+@Rowa A { v } B { @Code "1v" is the current inter-line spacing }
+}
+The first four all define absolute distances and are strictly
+interchangeable.  It is traditional to measure font sizes in points; typical
+sizes are @Code "12p" and {@Code "10p"}, but fractional sizes are allowed.
+@PP
+If you use the @Code "f" unit, the length will depend on the current
+font size.  This can be very useful.  For example, the default value of
+the @Code "margin" option of @Code "@CurveBox" is @Code "0.3f" (0.3
+times the current font size).  If you use a large font, for example in
+an overhead transparency, you get a correspondingly large margin without
+having to ask for it.
+@PP
+The @Code "s" and @Code "v" units are less useful.  The @Code "v" unit
+is used within paragraph symbols (Section {@NumberOf paragraphs}) to
+ensure that the space between paragraphs widens with the inter-line spacing.
+@End @Section
diff --git a/doc/user/bas_par1 b/doc/user/bas_par1
new file mode 100644
index 0000000..de3da37
--- /dev/null
+++ b/doc/user/bas_par1
@@ -0,0 +1,105 @@
+@Section
+   @Title { Starting a new line, paragraph, or page }
+   @Tag { paragraphs }
+@Begin
+@PP
+The usual way to start a new paragraph is with the @Code "@PP" `plain
+pp. @Index @Code "@PP"
+paragraphs. @Index { paragraph symbols }
+paragraph' symbol.  It produces a small vertical space and indents the
+first line of the new paragraph.  Some document formatting systems
+interpret a blank line as a request to start a new paragraph.  This is
+not the case with Lout:  a blank line is two line-endings, equivalent to
+two spaces.
+@PP
+The @Code "@LP" `left paragraph' symbol produces the same
+lp. @Index @Code "@LP"
+vertical space as {@Code "@PP"}, but omits the indent.  The @Code "@LLP"
+`left line paragraph' symbol starts a new paragraph using
+llp. @Index @Code "@LLP"
+the usual inter-line spacing and no indent, or in other words it starts a
+new line.  If you are using it to create single lines, you need the
+@Code "lines" paragraph breaking style instead (Section {@NumberOf paras}).
+@PP
+The @Code "@DP" `display paragraph' symbol produces a somewhat larger
+dp. @Index @Code "@DP"
+vertical space, equal to the amount used before and after displays
+(Section {@NumberOf displays}), with no indent.  To get even larger
+vertical spaces, use @Code "@DP" repeatedly.  Another symbol,
+{@Code "@LOP"}, leaves a paragraph break the size of the gap left
+lop. @Index @Code "@LOP"
+outside (that is, before and after) lists (Section {@NumberOf lists}).  This
+is usually equal to {@Code "@DP"}.
+@PP
+The {@Code "@NP"} `new page' symbol causes the following paragraph to
+page. @Index { page, skipping to next }
+new.page @Index { new page }
+np. @Index @Code "@NP"
+begin on a new page or column.  Of course, Lout starts a new page or
+column automatically when the old one is full, so @Code "@NP" is needed
+only rarely.
+@PP
+To make each section begin on a new page you must set the @Code "@SectionGap"
+sectiongap. @Index @Code "@SectionGap"
+setup file option (Section {@NumberOf largescale}).  To make one particular
+section start on a new page or column, place @Code "@NP" within the previous
+section, at the end.  Placing @Code "@NP" between sections will not work.
+@PP
+Occasionally Lout will start a new page or column directly after a heading,
+which looks very poor.  The obvious answer is to place an @Code "@NP"
+just before the heading, but when the document is later revised and the
+heading no longer falls near the page or column ending, this @Code "@NP"
+will have to be taken away again.
+A better answer is to precede the heading with a @Code "@CNP" `conditional
+cnp. @Index @Code "@CNP"
+new page' symbol, which checks whether enough space remains in the page or
+column for a heading and at least two lines of text.  If so, @Code "@CNP"
+does nothing; if not, @Code "@CNP" causes a new page or column to be begun,
+like {@Code "@NP"}.  The recommended arrangement is
+@ID @OneRow @Code {
+"end of previous part."
+"@DP"
+"@CNP"
+"@Heading { A Heading }"
+"@PP"
+"First paragraph of next part ..."
+}
+The @Code "@CNP" symbol should be preceded by either @Code "@DP" or
+@Code "@LP", preferably {@Code "@DP"}, and this determines the amount of
+space when the @Code "@NP" action does not occur.
+@PP
+The ultimate answer to the conditional new page problem is to recognise
+that the heading is the beginning of a new section of the document, and
+to use a large-scale structure symbol like @Code "@Section" (Section
+{@NumberOf largescale}).  Conditional new page is just one of many
+services provided automatically by these symbols.
+@PP
+Some people do not like to see the first line of a paragraph alone at
+the bottom of a page, or the last line of a paragraph alone at the
+top (these blemishes are sometimes called widows and orphans).  You
+can instruct Lout not to allow these; see the next section for details.
+@PP
+You can modify the effect of the paragraph symbols by changing options
+in the setup file.  For general information about setup files and their
+options, consult Section {@NumberOf setup}; here we just explain how
+the relevant options work.  The options and their default values are
+paragap @Index @Code "@ParaGap"
+paraindent @Index @Code "@ParaIndent"
+@ID @OneRow @Code {
+"@ParaGap { 1.30vx }"
+"@ParaIndent { 2.00f }"
+"@DisplayGap { 1.00v }"
+}
+The values are lengths (Section {@NumberOf objects}), except that
+for reasons beyond our scope @Code "@ParaGap" must be a length with
+an @Code "x" appended, as shown.  The @Code "@ParaGap" option determines
+how much vertical space will be
+inserted by @Code "@PP" and {@Code "@LP"}.  The default value,
+{@Code "1.30vx"}, is 30% more than the normal inter-line spacing;
+to get no extra spacing, change it to {@Code "1.00vx"}.  The
+@Code "@ParaIndent" option determines the width of the indent produced
+by {@Code "@PP"}, and its default value is twice the current font
+size.  The @Code "@DisplayGap" option determines the amount of vertical
+space inserted by {@Code "@DP"}, as well as the vertical space before
+and after displays.
+@End @Section
diff --git a/doc/user/bas_par2 b/doc/user/bas_par2
new file mode 100644
index 0000000..51f674c
--- /dev/null
+++ b/doc/user/bas_par2
@@ -0,0 +1,261 @@
+@Section
+   @Title { Paragraph breaking }
+   @Tag { paras }
+@Begin
+@PP
+@I { Paragraph breaking } is the process of
+paragraph.breaking @Index { paragraph breaking }
+inserting line breaks into praragraphs at places appropriate to the column
+width.  Lout works out suitable column widths and performs paragraph
+breaking automatically, finding an `optimal' break with the method
+used by the @TeX
+tex.paragraph @SubIndex { paragraph breaking }
+system.  It offers nine styles of paragraph breaking,
+which we will explore with the aid of this example:
+@ID @OneRow @Code {
+It is a truth universally
+acknowledged, that a single man
+in possession of a good fortune,
+must be in want of a wife.
+}
+Changing the paragraph breaking style is similar to changing the font,
+colour, or language, and is done using the @Code "@Break" symbol:
+break. @Index @Code "@Break"
+@ID @Code "ragged @Break ..."
+This example causes every paragraph in the following object to be
+broken using the @Code ragged style, of which more below.
+@PP
+The first two of the nine styles perform @I { line adjustment }, which
+line.adjustment @Index { line adjustment }
+means that they enlarge the spaces between the objects making up each
+line so as to fill the lines completely:
+@IndentedList
+@LI @Tab
+    @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B }
+{
+@Rowa
+    A { "adjust @Break ..." }
+    B { adjust @Break {
+It is a truth universally
+acknowledged, that a single man
+in possession of a good fortune,
+must be in want of a wife.
+}}
+}
+@LI @Tab
+    @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B }
+{
+@Rowa
+    A { "outdent @Break ..." }
+    B { outdent @Break {
+It is a truth universally
+acknowledged, that a single man
+in possession of a good fortune,
+must be in want of a wife.
+}}
+}
+@EndList
+The @Code adjust style is frequently used, so it has been chosen as the
+default style.  Outdenting adds a small space at the start of each line
+outdent. @Index { outdented paragraphs }
+except the first, and is much less common.
+@PP
+The next four styles do not adjust lines, leaving the paragraph
+ragged. @Index { @Code ragged paragraph breaking style }
+cragged. @Index { @Code cragged paragraph breaking style }
+rragged. @Index { @Code rragged paragraph breaking style }
+oragged. @Index { @Code oragged paragraph breaking style }
+{@I ragged}:
+@IndentedList
+@LI @Tab
+    @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B }
+{
+@Rowa
+    A { "ragged @Break ..." }
+    B { ragged @Break {
+It is a truth universally
+acknowledged, that a single man
+in possession of a good fortune,
+must be in want of a wife.
+}}
+}
+@LI @Tab
+    @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B }
+{
+@Rowa
+    A { "cragged @Break ..." }
+    B { cragged @Break {
+It is a truth universally
+acknowledged, that a single man
+in possession of a good fortune,
+must be in want of a wife.
+}}
+}
+@LI @Tab
+    @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B }
+{
+@Rowa
+    A { "rragged @Break ..." }
+    B { rragged @Break {
+It is a truth universally
+acknowledged, that a single man
+in possession of a good fortune,
+must be in want of a wife.
+}}
+}
+@LI @Tab
+    @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B }
+{
+@Rowa
+    A { "oragged @Break ..." }
+    B { oragged @Break {
+It is a truth universally
+acknowledged, that a single man
+in possession of a good fortune,
+must be in want of a wife.
+}}
+}
+@EndList
+The paragraph is broken in the same places as @Code adjust breaks it,
+but the resulting lines are left-justified, centred, or right-justified
+with respect to each other, rather than adjusted; @Code "oragged"
+is like @Code "outdent" except the resulting lines are not adjusted.
+@PP
+If you have a few words that must be kept together on one line, the
+preventing. @Index { preventing line breaks }
+keeping. @Index { keeping things on one line }
+recommended way is to separate them by an @Code "~" symbol:
+@ID @Code "According to Prof.~Jones, the effect of ..."
+It's best not to bother about this until you actually get a bad line
+break, since chances are good that the words will fall on one line anyway.
+@PP
+The last three styles differ from the first five in breaking the
+paragraph at the points where it is broken in the original input:
+lines. @Index { @Code lines paragraph breaking style }
+clines. @Index { @Code clines paragraph breaking style }
+rlines. @Index { @Code rlines paragraph breaking style }
+@IndentedList
+@LI @Tab
+    @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B }
+{
+@Rowa
+    A { "lines @Break ..." }
+    B { lines @Break {
+It is a truth universally
+acknowledged, that a single man
+in possession of a good fortune,
+must be in want of a wife.
+}}
+}
+@LI @Tab
+    @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B }
+{
+@Rowa
+    A { "clines @Break ..." }
+    B { clines @Break {
+It @PageMark clines is a truth universally
+acknowledged, that a single man
+in possession of a good fortune,
+must be in want of a wife.
+}}
+}
+@LI @Tab
+    @Fmta { @Col 6c @Wide @Code A ! @Col 7c @Wide B }
+{
+@Rowa
+    A { "rlines @Break ..." }
+    B { rlines @Break {
+It is a truth universally
+acknowledged, that a single man
+in possession of a good fortune,
+must be in want of a wife.
+}}
+}
+@EndList
+The lines are left-justified, centred, or right-justified with respect
+to each other in the same way as for the ragged styles.
+@PP
+When using the @Code lines style, there are some fine points concerning
+the proper use of white space.  Consider this example:
+@ID @OneRow @Code {
+"@IndentedDisplay lines @Break @I {"
+"Teach me to hear Mermaides singing,"
+"Or to keep off envies stinging,"
+"     And finde"
+"     What winde"
+"Serves to'advance an honest minde."
+"}"
+}
+The result is the indented display
+@IndentedDisplay lines @Break @I {
+Teach me to hear Mermaides singing,
+Or to keep off envies stinging,
+     And finde
+     What winde
+Serves to'advance an honest minde.
+}
+This style is the only one for which it is useful to indent individual
+lines in the input; as the result shows, such indents will be
+respected, as will blank lines.  However, Lout's rule that only white
+space separating objects affects the result (Section {@NumberOf spaces})
+still holds, which means that indenting the first line is not
+effective:
+@ID @OneRow @Code {
+"@IndentedDisplay lines @Break @I {"
+"     And finde"
+"     What winde"
+"Serves to'advance an honest minde."
+"}"
+}
+produces
+@IndentedDisplay lines @Break @I {
+     And finde
+     What winde
+Serves to'advance an honest minde.
+}
+This may seem awkward at first, but actually it is extremely convenient
+because you don't have to worry about whether the first line of the
+paragraph should appear on a new line as above, or immediately after
+the opening brace:  space at that point does not separate two objects,
+so it has no effect.  The indent can be obtained by
+starting the first line with an empty object (Section {@NumberOf empty}):
+@ID @OneRow @Code {
+"@IndentedDisplay lines @Break @I {"
+"{}     And finde"
+"     What winde"
+"Serves to'advance an honest minde."
+"}"
+}
+The result is
+@IndentedDisplay lines @Break @I {
+{}     And finde
+     What winde
+Serves to'advance an honest minde.
+}
+as desired.  To set the entire document in a paragraph breaking style other
+than {@Code "adjust"}, you need to change the @Code "@InitialBreak" option,
+as explained at the end of Section {@NumberOf linespace}.
+@PP
+Some people don't like to see the first line of a paragraph alone at the
+widows @Index { widow lines }
+orphans @Index { orphan lines }
+unbreakablefirst. @Index { @Code unbreakablefirst }
+unbreakablelast. @Index { @Code unbreakablelast }
+foot of a page or column (the rest appearing on the next page).  You can
+instruct Lout not to allow this with
+@ID @Code "unbreakablefirst @Break ..."
+meaning that the first line cannot be broken off from the rest of the
+paragraph.  Similarly,
+@ID @Code "unbreakablelast @Break ..."
+instructs Lout to prevent the last line of a paragraph from appearing
+alone at the top of a page or column.  These features would probably be
+invoked in the @Code "@InitialBreak" option, like this:
+@ID
+@Code "@InitialBreak { unbreakablefirst unbreakablelast hyphen adjust 1.2fx }"
+You can turn them off with @Code "breakablefirst @Break"
+and @Code "breakablelast @Break".  In both cases Lout makes it happen by
+breaking at the previous place, either between paragraphs or two lines from
+the end of a paragraph.  Alternatively, both features are compatible with
+Lout's @Code "@OptimizePages" option, which will optimize the overall page
+layout of the document subject to these requirements.
+@End @Section
diff --git a/doc/user/bas_spac b/doc/user/bas_spac
new file mode 100644
index 0000000..b7546c2
--- /dev/null
+++ b/doc/user/bas_spac
@@ -0,0 +1,103 @@
+@Section
+   @Title { Spaces and braces }
+   @Tag { spaces }
+@Begin
+@PP
+Every symbol in Lout either consists entirely of letters ({@Code "@"}
+symbols. @Index { symbols, makeup of }
+is considered to be a letter) or entirely of punctuation characters.  Here
+are some examples of each type:
+@ID @OneRow @Tab
+    @Fmta { @Col @I    @CC A ! @Col @I    @CC B }
+    @Fmtb { @Col @Code @CC A ! @Col @Code @CC B }
+{
+@Rowa A { From letters } B { From punctuation }
+@Rowb A { "@PP" } B { "{" }
+@Rowb A { "margin" } B { "}" }
+}
+Now if two symbols made from letters are run together like this:
+@ID {
+@Code "@CurveBox@I  Hello" &8ct @I (wrong!)
+}
+Lout will take this to mean one word or symbol called {@Code "@CurveBox@I"},
+which is wrong.  In the same way, a letter-type symbol cannot be run
+together with a word.  However, punctuation-type symbols can be run together
+with anything.  For example, in
+@ID @Code "@CurveBox{ Hello @I { world }}."
+Lout understands that @Code "@CurveBox" and @Code "{"
+# }
+are separate, and it also sorts out
+# {{
+@Code "}}." into two right brace symbols and a full stop.  It might
+seem strange to treat punctuation and letters so differently,
+but computer programming languages have done it like this for
+many years, and it works well.  This is the first use for
+spaces. @Index { spaces, significance of }
+spaces:  to separate letter-type symbols from each other and from words.
+@PP
+To see the second use for spaces, consider two words side by side:
+@ID @Code "Hello world"
+We want this to produce Hello world, so a space between two words in
+the input must mean a space between them in the result.  Apply the
+golden rule (where you can put one object, you can put any object) and
+you get this:  @I { a space between two objects in the input produces
+a space between them in the result }.  For example,
+@ID @Code "@CurveBox Hello @CurveBox world"
+produces
+@ID { @CurveBox Hello @CurveBox world }
+The space between the two objects @Code "@CurveBox Hello" and
+@Code "@CurveBox world" appears between them in the result; the other
+two spaces do not separate objects so do not appear in the result.
+@PP
+Two objects may be separated by a number of spaces other than one.  If
+they are separated by no spaces, they will appear immediately adjacent
+in the result; if separated by two spaces, they will appear two spaces
+apart; and so on.  In English it is correct to leave two spaces between
+the end of one sentence and the beginning of the next, for example.  See
+Section {@NumberOf white} for two alternative ways to interpret white
+space in Lout.
+@PP
+Occasionally the two uses for spaces conflict.  For example, to produce
+@ID { { @CurveBox Hello }{ @CurveBox world } }
+we need to have no spaces between the two objects, but then @Code "Hello"
+and the following @Code "@CurveBox" would be run together, which will
+not work.  The solution is to use braces:
+@ID @Code "{ @CurveBox Hello }{ @CurveBox world }"
+None of the six spaces in this example lie between two objects.
+@PP
+However, the main use of braces is to inform Lout that the object
+within them is to be kept together, so that any nearby symbols are to
+apply to all of it.  For example, leaving the braces out of
+@Code "@I { Hello world }" would mean that @Code "@I" applies only to
+{@Code "Hello"}.
+@PP
+When an object-consuming symbol like @Code "@I" is followed by an
+braces. @Index { braces, effect of }
+object enclosed in braces, that is the object consumed.  For example,
+@ID @Code "This is @I { absolutely necessary }, since otherwise ..."
+produces
+@ID { This is @I { absolutely necessary }, since otherwise ... }
+with the object @Code "absolutely necessary" italicized, but not the
+following comma.  If there are no braces, the object consumed is
+everything up to the next object-separating space:
+@ID @Code "This is @I necessary, since otherwise ..."
+produces
+@ID { This is @I necessary, since otherwise ... }
+with an undesirable italic comma.  In practice, this means you can
+avoid braces only when italicizing a single word with no punctuation
+attached.
+@PP
+One common pitfall is to use unnecessary braces, like this:
+@ID {
+@Code "@I { @CurveBox { Hello world } }" &8ct @I (bad!)
+}
+Another is to think that all spaces produce space in the result, and so
+write
+@ID {
+@Code "@I{@CurveBox{Hello world}}" &8ct @I (worse!)
+}
+Use braces only when necessary, and add extra spaces where they do not
+separate objects, and your documents will be far easier to read while
+you are working on them.  Don't be fooled by the argument that says it
+doesn't matter because it doesn't affect the final printed result.
+@End @Section
diff --git a/doc/user/bas_star b/doc/user/bas_star
new file mode 100644
index 0000000..ef65eb6
--- /dev/null
+++ b/doc/user/bas_star
@@ -0,0 +1,129 @@
+@Section
+   @Title { Getting started }
+   @Tag { start }
+@Begin
+@PP
+Suppose you want to produce the following little document:
+@CD @Box margin { 1.3c } 7.0c @Wide 9c @High {
+@Display @Heading { Introduction by W. J. Harvey }
+harvey.w.j @Index { Harvey, W. J. }
+For Virginia Woolf, @I Middlemarch was `the magnificent book
+which for all its imperfections is one of the few English novels
+written for grown-up people.'
+@PP
+She was, no doubt, thinking of George Eliot's unblinking but
+eliot.g @Index { Eliot, George }
+compassionate delineation of her characters, of the subtlety of
+psychological analysis and the maturity of moral comment which
+underlie this complex and varied novel of English provincial
+life in the early nineteenth century.
+}
+Unlike word processing and desktop publishing systems, with Lout you
+cannot see and edit your document on the screen in this finished
+form.  Instead, you edit an ordinary text file, in which your text is
+augmented with symbols that mark out the headings, paragraphs, and so
+on.  Although it would be nice to be able to see and edit the finished
+form, working with a text file and symbols does have some compensating
+advantages.
+@PP
+The first step in producing your introduction to @I Middlemarch is to
+use the text editor of your choice to construct this text file:
+@ID @OneRow @Code {
+"@SysInclude { doc }"
+"@Doc @Text @Begin"
+"@Display @Heading { Introduction by W. J. Harvey }"
+"For Virginia Woolf, @I Middlemarch was `the magnificent book which for all its"
+"imperfections is one of the few English novels written for grown-up people.'"
+"@PP"
+"She was, no doubt, thinking of George Eliot's unblinking but compassionate"
+"delineation of her characters, of the subtlety of psychological analysis and"
+"the maturity of moral comment which underlie this complex and varied novel"
+"of English provincial life in the early nineteenth century."
+"@End @Text"
+}
+Comparing this with the finished form, it's easy to guess that
+@Code "@I" is a symbol that causes the following thing to be printed
+in italics, and that @Code "@PP" starts a new paragraph.  The other
+symbols are not much harder.
+@PP
+@Code "@SysInclude { doc }" instructs Lout to read a @I { setup file }
+called {@Code "doc"}, in which the symbols are defined.  Setup files
+are the subject of Chapter {@NumberOf changes}, but you can go a long
+way without worrying about them.  @Code "@Doc @Text @Begin" and
+@Code "@End @Text" have no visible effect, but they must bracket the
+document as a whole.  Again, you don't have to know what they are for.
+@PP
+That explains everything except the part that produces the heading.  It's
+an interesting glimpse of the way that Lout's symbols cooperate with
+each other:
+@ID @Code "@Display @Heading { Introduction by W. J. Harvey }"
+The @Code "@Display" symbol does the centring and leaves space above
+and below, while @Code "@Heading" switches to a bold font.  The braces
+group the words of the heading together so that these symbols apply to
+all of it; without them they would apply to just the first word.  All
+this is explained in detail in Sections {@NumberOf objects}
+and {@NumberOf spaces}.
+@PP
+Once the file is ready, the next step is to get it processed by the
+Basser Lout interpreter.  If the file's name is {@Code "intro"},
+the command for this on the Unix
+@FootNote { Unix is a trademark. }
+operating system is
+@ID @Code "lout intro > intro.ps"
+The output is the PostScript
+@FootNote { PostScript is a trademark of Adobe Systems, Inc. }
+file {@Code "intro.ps"}, which is suitable for printing on many laser
+printers and other devices.  There are programs that show you the
+result on your screen as well, although you won't be able to edit it
+there.  You can also get plain text output (Section {@NumberOf plain})
+and PDF output.
+@PP
+There are a few points that often confuse people as they begin, so we'll
+treat them briefly now with pointers to later sections where they are
+done properly.
+@PP
+Some characters are symbols that produce special effects -- for
+example, @Code "{" and @Code "}" produce grouping -- and to turn off
+these effects the characters must be enclosed in double quotes:  @Code
+"\"{\"" produces "{".  The complete set of these special characters is
+@ID @Code "/    |    &    {    }    #    @    ^   ~   \\   \""
+Section {@NumberOf characters} treats unusual characters in full detail.
+@PP
+Symbols like @Code "@Doc" and @Code "@Text" must be separated from
+each other by one or more spaces, otherwise Lout will think they are part
+of one symbol.  See Section {@NumberOf spaces} for the details.
+@PP
+People familiar with other systems might expect that leaving a blank line would
+cause Lout to start a new paragraph; but this is not so, you must use a
+paragraph symbol.  Lout will ordinarily take notice of how many spaces you type
+between words (Section {@NumberOf spaces}), but it will mimic the spacing rules
+of two other systems, troff and @TeX, if you prefer (Section {@NumberOf white}).
+@PP
+When Lout runs, you might see some error messages beginning with
+error.messages @Index { error messages }
+`unresolved cross reference' -- not on file @Code "intro" above, but on
+more complicated ones (anything with a footnote, for example).  These
+just mean that you have to run the @Code "lout" command again to finish off
+the complicated things (Section {@NumberOf cross}), and they will gradually
+go away.  Of course, if you see error messages about missing braces, unknown
+symbols, and so on, you need to revise your file.  Lout will tell you the
+line number of the problem, and how far along the line it is.
+@PP
+@BI { WARNING: }  Lout allows documents to cause arbitrary system commands
+to be executed.  These typically do useful things such as format computer
+programs and uncompress graphics files, but it is possible for a
+malicious person to send you a document which includes a command to delete
+all your files, send abusive mail to the President of the United States in
+your name, etc.  You can protect yourself against this possibility by using
+the `safe execution' flag:
+@ID @Code "lout -S suspect.document > out.ps"
+Then no system commands will be executed; instead, Lout will print them so
+that you can confirm for yourself that they are safe before running again
+without the flag.  These system commands are Lout's only potentially unsafe
+features, but you also need to worry about whether the resulting PostScript
+file contains malicious code, since the document may direct Lout to include
+arbitrary PostScript code in the output.  The safe execution of PostScript
+programs is a matter for PostScript interpreters, not for Lout.  For example,
+the popular Ghostview program has a @Code "-safer" command line option,
+which is rumoured to disable unsafe PostScript features.
+@End @Section
diff --git a/doc/user/bas_supe b/doc/user/bas_supe
new file mode 100644
index 0000000..40faf92
--- /dev/null
+++ b/doc/user/bas_supe
@@ -0,0 +1,17 @@
+@Section
+   @Title { Superscripts and subscripts }
+   @Tag { super }
+@Begin
+@PP
+There are @Code "@Sup" and @Code "@Sub" symbols for producing
+superscripts and subscripts:
+@ID @Code "2 @Sup nd"
+produces
+@ID { 2 @Sup nd }
+and the @Code "@Sub" symbol works in a similar way.  These symbols
+are probably never required in English language text, since the
+only uses for them are in footnotes, which produce the superscript
+automatically, and equations, which have their own versions of these
+symbols.  Both symbols have a @Code "gap" option which determines the
+vertical spacing.
+@End @Section
diff --git a/doc/user/bas_unde b/doc/user/bas_unde
new file mode 100644
index 0000000..9f7ea94
--- /dev/null
+++ b/doc/user/bas_unde
@@ -0,0 +1,27 @@
+@Section
+   @Title { Underlining }
+   @Tag { underlining }
+@Begin
+@PP
+The @Code "@Underline" symbol underlines the following object:
+underline.sym @Index @Code "@Underline"
+@ID @OneRow @Code {
+"This little paragraph of text will have"
+"@Underline { three underlined words } in it."
+}
+produces
+@ID @OneRow 1.6i @Wide {
+This little paragraph of text will have
+@Underline { three underlined words } in it.
+}
+The underlining is continuous unless a line break intervenes.  You
+can't use this symbol to underline an arbitrary object:  it is carefully
+designed to produce high-quality underlining of single words and
+parts of paragraphs, and it works only for those objects.
+@PP
+Each font contains information about how words in that font should be
+underlined:  how far below the baseline the line should be drawn, and how
+thick.  The @Code "@Underline" symbol uses this information; the font
+it bases its underlining on is the font of the first object underlined
+if it is a word, or else the font of the enclosing paragraph.
+@End @Section
diff --git a/doc/user/bas_verb b/doc/user/bas_verb
new file mode 100644
index 0000000..6da835a
--- /dev/null
+++ b/doc/user/bas_verb
@@ -0,0 +1,49 @@
+@Section
+   @Title { Verbatim text }
+   @Tag { verbatim }
+@Begin
+@PP
+The @Code "@Verbatim" symbol
+@FootNote { Prior to Version 3.13 the @Code "@Verbatim" symbol was
+implemented in a way that restricted its availability to Unix
+systems only.  This restriction no longer applies. }
+prints the following object exactly as
+verbatim.sym @Index @Code "@Verbatim"
+it appears in the input file.  All special meanings for characters,
+symbols, etc. are turned off; there is one result line for
+each input line.  For example,
+@ID @Code @Verbatim {
+@IndentedDisplay @Verbatim {
+A line of "verbatim" text
+Another line, with a \ character
+}
+}
+has result
+@IndentedDisplay @Verbatim {
+A line of "verbatim" text
+Another line, with a \ character
+}
+Use @Code "@F @Verbatim { ... }" to get the result in a fixed-width font.
+@PP
+If the verbatim text contains @Code "{" or @Code "}" characters, then
+they should either be balanced or else you need to use the alternative
+form
+@ID @Code {
+"@Verbatim @Begin"
+"..."
+"@End @Verbatim"
+}
+so that there is no doubt about where the verbatim text ends.  Although
+we have said that there are no special meanings, there is one exception
+to this rule:  @Code "@Include" and @Code "@SysInclude" commands are
+recognized, allowing all or part of the verbatim text to come from some
+other file.
+@PP
+Occasionally the first line of some verbatim text begins with some
+spaces that have to be preserved.  This is a problem for @Code "@Verbatim"
+because it ignores all white spaces following the opening brace and
+all white spaces preceding the closing brace.  However, the alternative
+@Code "@RawVerbatim" symbol stops ignoring white spaces at the opening
+as soon as a newline character is reached; in other words, it will
+preserve all white spaces following the first newline.
+@End @Section
diff --git a/doc/user/bgr b/doc/user/bgr
new file mode 100644
index 0000000..9452ff0
--- /dev/null
+++ b/doc/user/bgr
@@ -0,0 +1,17 @@
+@Chapter
+    @Title { Basic Graphics }
+    @Tag { graphics }
+@Begin
+@LP
+This chapter introduces some basic graphics symbols for colour, rotation,
+scaling, and included illustrations.  These are all from the standard
+BasicLayout package, so no @Code "@SysInclude" line is needed to
+get them.
+@BeginSections
+@Include { bgr_colo }
+@Include { bgr_boxs }
+@Include { bgr_rota }
+@Include { bgr_scal }
+@Include { bgr_incl }
+@EndSections
+@End @Chapter
diff --git a/doc/user/bgr_boxs b/doc/user/bgr_boxs
new file mode 100644
index 0000000..39c6460
--- /dev/null
+++ b/doc/user/bgr_boxs
@@ -0,0 +1,121 @@
+@Section
+    @Title { Boxes and rules }
+    @Tag { boxes }
+@Begin
+@PP
+The @Code "@Box" symbol causes the following object to be enclosed in a
+box. @Index @Code "@Box"
+box:
+@ID @OneRow @Code {
+"@QuotedDisplay @Box {"
+"@CentredDisplay @Heading Cheating"
+"The Department uses assignments ... of that student alone."
+"}"
+}
+The result of this is
+@QuotedDisplay @Box {
+@CentredDisplay @Heading Cheating
+The Department uses assignments both as a teaching device and as a
+major component of its assessment of each student.  It therefore
+requires that all programs, exercises etc. handed in bearing an
+individual student's name be the work of that student alone.
+}
+showing that a box may enclose an arbitrarily complicated object.
+@PP
+The @Code "@Box" symbol has a @Code margin option which determines the
+margin between the box and what it encloses.  For example,
+@ID @OneRow @Code {
+"@Box"
+"    margin { 0.1c }"
+"{}"
+}
+requests a box with a 0.1 centimetre margin enclosing an empty object,
+so the result is a square whose width and height are 0.2 centimetres:
+@ID @Box margin { 0.1c } {}
+If the @Code "margin" option is omitted, it is assigned the default
+value {@Code "0.3f"}, which means 0.3 times the current font size.  It
+is very useful to tie the margin to the font size in this way, because
+large headings (in overhead transparencies, say) need large margins.
+@PP
+There is a @Code "linewidth" option which determines the width
+(thickness) of the line drawn around the boundary of the box:
+@ID @OneRow @Code {
+"@Box"
+"    linewidth { 0.1c }"
+"{ Hello world }"
+}
+produces
+@ID @Code {
+@Box
+    linewidth { 0.1c }
+{ Hello world }
+}
+Lout does not take the line width into account when working out how
+large everything is:  as far as Lout is concerned, the line always
+has width zero.  If you draw really thick lines you might need a larger
+margin and more space near the box.  The default value of @Code linewidth
+is empty, which means to use whatever width the PostScript interpreter
+in your output device thinks is a good default value.
+@PP
+There is also a @Code "paint" option which paints a background of the
+nominated colour:
+@ID @Code "@Box paint { grey } WARNING!"
+has result
+@ID @Box paint { grey } WARNING!
+This is quite different from {@Code "grey @Colour @Box WARNING!"},
+which produces
+@ID grey @Colour @Box WARNING!
+The @Code "paint" option may be given any colour from the list in
+Section {@NumberOf colour}; its default value is {@Code "none"}, which
+is a special value (not a colour) which means no painting.  White paint
+comes into its own inside painted boxes:
+@ID @Code "@Box paint { nochange } white @Colour { Hello world }"
+produces a box painted in whatever colour we happen to be using at
+the moment, with white text inside:
+@ID @Box paint { nochange } white @Colour { Hello world }
+This works because the box is painted before the object it encloses
+is drawn on the page.
+@PP
+There are @Code "@CurveBox" and @Code "@ShadowBox" symbols that
+curvebox. @Index @Code "@CurveBox"
+shadowbox. @Index @Code "@ShadowBox"
+produce other kinds of boxes:
+@CD @Tab
+    @Fmta { @Col A ! @Col ! @Col B }
+{
+@Rowa
+    A { @CurveBox { A curve box } }
+    B { @ShadowBox { A shadow box } }
+}
+These also have @Code "margin" and @Code "paint" options, and
+@Code "@ShadowBox" has a @Code "shadow" option which determines
+the thickness of the shadow (its default value is {@Code "0.2f"}).
+@PP
+Boxes are quite at home inside paragraphs, as @Box { a box },
+@CurveBox { a curve box }, and @ShadowBox { a shadow box }
+show.  Simply proceed as usual:
+@ID @Code "... paragraphs, as @Box { a box }, @CurveBox { a curve box }, ..."
+Boxes within paragraphs are never broken across two lines.
+@PP
+There are two symbols for producing horizontal rules.  @Code "@FullWidthRule"
+fullwidthrule. @Index @Code "@FullWidthRule"
+rules. @Index rules
+produces a rule which occupies the full page (or column) width:
+@DP @FullWidthRule @DP
+More precisely, the rule occupies as much horizontal space as it
+legally can.  @Code "@FullWidthRule" produces an object in the usual
+way, so you will need paragraph or display symbols to separate it from
+preceding and following things.
+@PP
+A variant called @Code "@LocalWidthRule" is more timid about zooming
+localwidthrule. @Index @Code "@LocalWidthRule"
+across the whole page:
+@ID @Code {
+"@OddPageTop { { My lovely document @LP @LocalWidthRule } @Right @PageNum }"
+}
+will draw a rule under just the three words.  Of course, underlining using
+the @Code "@Underline" symbol might be a better way to do this.  Both
+symbols have a @Code "linewidth" option which works like the one for
+boxes described above.  In particular, Lout leaves zero space for the
+line, no matter how wide you make it.
+@End @Section
diff --git a/doc/user/bgr_colo b/doc/user/bgr_colo
new file mode 100644
index 0000000..4a48fb9
--- /dev/null
+++ b/doc/user/bgr_colo
@@ -0,0 +1,48 @@
+@Section
+   @Title { Colour }
+   @Tag { colour }
+@Begin
+@PP
+Colour is obtained in much the same way that fonts and language changes
+colour. @Index @Code "@Colour"
+color. @Index @Code "@Color"
+are, using the @Code "@Colour" (or equivalently {@Code "@Color"}) symbol:
+@ID @Code "grey  @Colour  { Hello, world }"
+produces
+@ID grey @Colour { Hello, world }
+The @Code "@Colour" symbol will accept any of the following colours:
+@QD @HAdjust @Tab
+    vmargin { 0.7vx }
+    hmargin { 0.2c }
+    @Fmta { @Col A @Colour @FilledBox ! @Col @Code A ! @Col !
+            @Col B @Colour @FilledBox ! @Col @Code B ! @Col !
+            @Col C @Colour @FilledBox ! @Col @Code C        }
+    @Fmtb { @Col A @Colour @FilledBox ! @Col @Code A ! @Col !
+            @Col B @Colour @FilledBox ! @Col @Code B ! @Col !
+            @Col                      ! @Col                }
+{
+@Rowa A { darkred	} B { red		} C { lightred		}
+@Rowa A { darkgreen	} B { green		} C { lightgreen	}
+@Rowa A { darkblue	} B { blue		} C { lightblue		}
+@Rowa A { darkcyan	} B { cyan		} C { lightcyan		}
+@Rowa A { darkmagenta	} B { magenta		} C { lightmagenta	}
+@Rowa A { darkyellow	} B { yellow		} C { lightyellow	}
+@Rowa A { darkgrey	} B { grey		} C { lightgrey		}
+@Rowa A { darkgray	} B { gray		} C { lightgray		}
+@Rowb A { black    	} B { white		}
+}
+Monochrome output devices will render them as shades of grey.  Colouring
+something @Code white makes it invisible, which is sometimes useful.
+@PP
+In addition to the list of colours given above, there is a special
+colour called {@Code nochange} which produces the colour you already
+happen to be using.
+@PP
+Whether or not the colours produced by @Code "@Colour" actually
+correspond with the names depends on the output device; the same
+nominal colour can look quite different on screen and on paper.  The
+standard Lout @Code "@SetColour" symbol can provide many more colours
+setcolour. @Index @Code "@SetColour"
+@Cite { $kingston1995lout.expert}, although they must be specified
+using numbers rather than names.
+@End @Section
diff --git a/doc/user/bgr_incl b/doc/user/bgr_incl
new file mode 100644
index 0000000..57ac4a1
--- /dev/null
+++ b/doc/user/bgr_incl
@@ -0,0 +1,47 @@
+@Section
+   @Title { Including an illustration }
+   @Tag { include }
+@Begin
+@PP
+The @Code "@IncludeGraphic" symbol incorporates into a Lout document an
+include.graphic @Index @Code "@IncludeGraphic"
+include.illus @Index { including an illustration }
+illustration (that is, an encapsulated PostScript or EPS file)
+produced by other means.  For the opposite process, using Lout to produce
+an illustration for inclusion in some other document, see
+Section {@NumberOf illustrations}.
+@PP
+For example, suppose the encapsulated PostScript file @Code "su_crest.eps"
+contains the University of Sydney crest.  Then
+@ID @Code "@IncludeGraphic su_crest.eps"
+produces
+@ID @IncludeGraphic su_crest.eps
+In general, the result produced by @Code "@IncludeGraphic" is an object
+that may be scaled, rotated, made into a display or placed within a
+paragraph, just like any other object.  Accolades for this remarkable
+flexibility should go to the PostScript page description language,
+whose extraordinary power makes the provision of this feature in Lout
+almost trivial.
+@PP
+The @Code "@IncludeGraphic" command understands that files ending
+with any of the suffixes {@Code ".gz"}, {@Code "-gz"}, {@Code ".z"},
+{@Code "-z"}, {@Code "_z"}, and {@Code ".Z"} are compressed files,
+and it will uncompress such files using the @Code "gunzip" command
+before including them.  The uncompressed version is stored in a file
+called @Code "lout.eps" in the current directory, and removed after
+being copied into the output file.
+@PP
+If you place an included illustration in a line of text, or anywhere
+where you care about its alignment with things on either side of it,
+it will be positioned with its centre at the same height as the
+centre of the letter x.  If this is not where you want it, use the
+@Code "@VShift" symbol:
+vshift. @Index @Code "@VShift"
+@ID @Code "... +0.5f @VShift @IncludeGraphic ..."
+prints the illustration half of the current font size higher on the
+page than would otherwise have been the case, and
+@ID @Code "... -0.5f @VShift @IncludeGraphic ..."
+prints it half the current font size lower.  Any length (Section
+{@NumberOf objects}) is allowed, and the object following @Code "@VShift"
+may in fact be arbitrary as usual.
+@End @Section
diff --git a/doc/user/bgr_rota b/doc/user/bgr_rota
new file mode 100644
index 0000000..e4bcc72
--- /dev/null
+++ b/doc/user/bgr_rota
@@ -0,0 +1,35 @@
+@Section
+   @Title { Rotation }
+   @Tag { rotation }
+@Begin
+@PP
+The @Code "@Rotate" symbol rotates the following object by any positive
+rotate. @Index @Code "@Rotate"
+or negative angle, measured in degrees:
+@ID @Code "45d @Rotate @Box WARNING!"
+has result
+@ID { 45d @Rotate @Box WARNING! }
+As usual, the object to be rotated may be arbitrary.  However, it is
+difficult for Lout to choose appropriate column widths for paragraphs
+inside rotated objects, so if a rotated object contains paragraphs that
+should be broken it is best to define the object's width explicitly,
+using the @Code "@Wide" symbol:
+wide @RawIndex { @Code "@Wide" }
+wide.rotate @SubIndex { with @Code "@Rotate" }
+@ID @OneRow @Code {
+"-90d @Rotate 4.5c @Wide {"
+"Papal initiatives and influence from the crowning of"
+"Charlemagne to the First Crusade"
+"}"
+}
+The result here is
+@ID {
+-90d @Rotate 4.5c @Wide {
+Papal initiatives and influence from the crowning of
+Charlemagne to the First Crusade
+}
+}
+The @Code "@Wide" symbol fixes the width of the following object, in
+this example to the length 4.5 centimetres, which is all Lout needs to
+decide the column widths of any paragraphs within it.
+@End @Section
diff --git a/doc/user/bgr_scal b/doc/user/bgr_scal
new file mode 100644
index 0000000..ad73f4c
--- /dev/null
+++ b/doc/user/bgr_scal
@@ -0,0 +1,53 @@
+@Section
+   @Title { Scaling }
+   @Tag { scaling }
+@Begin
+@PP
+The @Code "@Scale" symbol performs a geometrical scaling of the
+scale. @Index @Code "@Scale"
+following object:
+@ID @Code {
+"0.5 @Scale @Box WARNING!"
+}
+produces
+@ID {
+0.5 @Scale @Box WARNING!
+}
+A scale factor of 0.5 means half the original size, 2.0 means double size,
+and so on.  No unit of measurement appears in the scale factor, because
+it makes no sense to have one.  As usual, the object to be scaled may be
+arbitrary.
+@PP
+It is also possible to supply two scale factors, in which case the
+first is applied horizontally and the second vertically:
+@ID @Code "{0.5 2.0} @Scale @Box WARNING!"
+has result
+@ID {0.5 2.0} @Scale @Box WARNING!
+Practical uses for this kind of scaling are rare.
+@PP
+If an empty object is given instead of a scale factor, like this:
+@ID @Code "{} @Scale @Box WARNING!"
+the @Code "@Scale" symbol will choose the largest scale factor that
+does not overrun the available horizontal space.  It is often possible
+to omit the {@Code "{}"}, since Lout inserts an empty object
+automatically whenever an object is clearly missing (see Section
+{@NumberOf objects}).  For example,
+@ID @Code "@QuotedDisplay @Scale @Box WARNING!"
+produces
+@QuotedDisplay @Scale @Box WARNING!
+@Code "@QuotedDisplay" and @Code "@LeftDisplay" go well with this form
+of {@Code "@Scale"}.  However, some care is needed because Lout foolishly
+takes no account of the available @I vertical space when choosing the
+scale factor.  The chosen scale factor could enlarge the vertical size so
+much that the object no longer fits on the page, with disastrous results.
+@PP
+By using a @Code "@Wide" symbol to restrict the available horizontal
+space, this form of scaling can also be used to scale to a nominated
+width.  For example,
+wide @RawIndex { @Code "@Wide" }
+wide.scale @SubIndex { with @Code "@Scale" }
+@ID @Code "5c @Wide @Scale @Box WARNING!"
+produces
+@ID { 5c @Wide @Scale @Box WARNING! }
+which is 5 centimetres wide.
+@End @Section
diff --git a/doc/user/cpp b/doc/user/cpp
new file mode 100644
index 0000000..9b413ed
--- /dev/null
+++ b/doc/user/cpp
@@ -0,0 +1,27 @@
+@Chapter
+  @Title { C and C++ Programs }
+  @Tag { cprint }
+@Begin
+@LP
+This chapter describes how to typeset C and C++ program text using the
+cp. @Index @Code "@CP"
+c. @Index { C++ }
+@Code "@CP" symbol in conjunction with the @Code c2lout filter.  The
+@Code "@CP" symbol looks after printing keywords in bold, variables
+in italic, and so on, depending on a style you choose.  It does not lay
+out programs in the sense of choosing indenting, it preserves the layout
+you give to the program.  From now on, `C' means `C or C++' wherever
+it occurs.
+@PP
+It is possible to simply print out one or more C files; we call this
+@I { stand-alone mode }.  Alternatively, the C program text may be printed
+as part of a larger Lout document; we call this @I { embedded mode }.
+@BeginSections
+@Include { cpp_lone }
+@Include { cpp_embe }
+@Include { cpp_chan }
+@Include { cpp_comm }
+@Include { cpp_tabs }
+@Include { cpp_eiff }
+@EndSections
+@End @Chapter
diff --git a/doc/user/cpp_chan b/doc/user/cpp_chan
new file mode 100644
index 0000000..ddedd51
--- /dev/null
+++ b/doc/user/cpp_chan
@@ -0,0 +1,83 @@
+@Section
+   @Title { Changing the default values }
+   @Tag { cpsetup }
+@Begin
+@PP
+We have just seen that the @Code "@CP" symbol has many options for
+changing the appearance of the C text.  However, most people would
+not want to have a different style for every C text in their document;
+they want to define the style once at the start, and have all their
+C texts come out in that style without laboriously setting options
+on every @Code "@CP" symbol.  This is done by copying the setup file
+and changing it.
+@PP
+For general information about how to make your own setup file, consult
+Section {@NumberOf setup}.  The options that determine the default
+values are in the @Code "@CPSetup" @Code "@Use" clause near the end of
+cprint. @Index @Code "@CPSetup"
+the @Code "cpsetup." setup file:
+@ID @Code @Tab
+   vmargin { 0.5vx }
+   @Fmta { @Col A ! @Col B ! @Col C}
+   @Fmtb { @Col { "    #" A } ! @Col { "{" B } ! @Col "}" }
+{
+@Rowa A { "@Use {  @CPSetup" }
+@Rowb A { "style" } B { fixed         }
+
+@Rowa 
+@Rowb A { "fixedfont" }			B { Courier  }
+@Rowb A { "fixedstrings" }		B { Base  }
+@Rowb A { "fixedidentifiers" }		B { Base  }
+@Rowb A { "fixedcomments" }		B { Base  }
+@Rowb A { "fixedkeywords" }		B { Base  }
+@Rowb A { "fixednumbers" }		B { Base  }
+@Rowb A { "fixedoperators" }		B { Base  }
+@Rowb A { "fixedsize" }			B { -1.0p         }
+@Rowb A { "fixedline" }			B { 1.0vx         }
+@Rowb A { "fixedtabin" }		B { 8		  }
+@Rowb A { "fixedtabout" }		B { 8s		  }
+
+@Rowa 
+@Rowb A { "varyingfont" }		B {               }
+@Rowb A { "varyingstrings" }		B { Slope         }
+@Rowb A { "varyingidentifiers" }	B { Slope         }
+@Rowb A { "varyingcomments" }		B { Base          }
+@Rowb A { "varyingkeywords" }		B { Bold          }
+@Rowb A { "varyingnumbers" }		B { Base          }
+@Rowb A { "varyingoperators" }		B { Base          }
+@Rowb A { "varyingsize" }		B { 1.0f          }
+@Rowb A { "varyingline" }		B { 1.0vx         }
+@Rowb A { "varyingtabin" }		B { 8		  }
+@Rowb A { "varyingtabout" }		B { 3f		  }
+
+@Rowa 
+@Rowb A { "symbolfont" }		B {               }
+@Rowb A { "symbolstrings" }		B { Slope         }
+@Rowb A { "symbolidentifiers" }		B { Slope         }
+@Rowb A { "symbolcomments" }		B { Base          }
+@Rowb A { "symbolkeywords" }		B { Bold          }
+@Rowb A { "symbolnumbers" }		B { Base          }
+@Rowb A { "symboloperators" }		B { Base          }
+@Rowb A { "symbolsize" }		B { 1.0f          }
+@Rowb A { "symbolline" }		B { 1.0vx         }
+@Rowb A { "symboltabin" }		B { 8		  }
+@Rowb A { "symboltabout" }		B { 3f		  }
+
+@Rowa A { "}" }
+}
+These show the default font families, font faces, font sizes, line
+spacings, and tab settings in force for the three styles, and also that
+the default style is {@Code "fixed"}.  Notice that the font family name
+for @Code "fixed" style is {@Code "Courier"}, but for the other styles is
+empty.  This causes the @Code "fixed" style to always switch to Courier,
+and the other styles to use the same font family as in the surrounding
+document.
+@PP
+To change a default value, delete the preceding @Code "#" and change the
+part between braces.  For example, suppose you are happy with @Code "fixed"
+except that you want bold keywords.  Then one line needs to be changed, to
+@ID @Code "fixedkeywords { Bold }"
+Or suppose you like @Code "varying" as it stands, but would like it to be
+the default style rather than {@Code "fixed"}.  Again, only one line needs
+to be changed, to {@Code "style { varying }"}.
+@End @Section
diff --git a/doc/user/cpp_comm b/doc/user/cpp_comm
new file mode 100644
index 0000000..f877c06
--- /dev/null
+++ b/doc/user/cpp_comm
@@ -0,0 +1,20 @@
+@Section
+   @Title { Lout inside C comments }
+   @Tag { cpcomm }
+@Begin
+@PP
+It is possible to embed Lout text inside C and C++ comments, by
+starting off the comment with an @Code "@" character.  The entire
+comment after the @Code "@" character should be Lout text.  For
+example, to force Lout to start a new page at some point within a C
+program, place
+@ID @Code "/*@ @NP */"
+at that point.  Or you could make a heading like this:
+@ID @Code "/*@ @Display @Heading { treeprint() } */"
+Other possible uses for this feature include index entries and margin
+notes.  Incredible as it may seem, you can even write
+@ID @Code "/*@ @CD @Heading { Function @CP { treeprint() } } */"
+with a @Code "@CP" symbol and some C code inside the Lout code
+inside the C code.  You probably can't go further, however, since
+that would require a C comment inside a C comment.
+@End @Section
diff --git a/doc/user/cpp_eiff b/doc/user/cpp_eiff
new file mode 100644
index 0000000..d0ec6df
--- /dev/null
+++ b/doc/user/cpp_eiff
@@ -0,0 +1,42 @@
+@Section
+   @Title { Eiffel program printing }
+   @Tag { eiffel }
+@Begin
+@PP
+There is an @Code "@Eiffel" symbol for typesetting Eiffel programs
+in conjuction with a filter called {@Code "eif2lout"}.  Apart from
+the change of language, everything is identical to C printing.  The
+file and symbol names are different, of course:
+@ID @OneRow @Tab
+    vmargin { 0.5vx }
+    @Fmta { @Col A ! @Col B }
+{
+@Rowa
+    A { @Code cprint }
+    B { @Code eiffel }
+@Rowa
+    A { @Code c2lout }
+    B { @Code eif2lout }
+@Rowa
+    A { @Code "@CP" }
+    B { @Code "@Eiffel" }
+@Rowa
+    A { @Code "@CPSetup" }
+    B { @Code "@EiffelSetup" }
+}
+but everything works in an exactly analogous way:  you place
+@ID @Code "@SysInclude { eiffel }"
+at the top of your document, enclose Eiffel program texts in
+@Code "@Eiffel { ... }", embed Lout into Eiffel using comments
+beginning with {@Code "--@"}, and so on.  The default style has been
+changed to {@Code varying}, so as to conform to the style guidelines
+in the standard Eiffel reference @Cite { $meyer1992eiffel }.  Some care
+has gone into making this conformance strict; in particular, if you
+enclose identifiers within comments in ` and ', as the style guidelines
+say you should, they will come out in italics; in fact, arbitrary text
+between ` and ' within comments will be set as Eiffel code.
+@PP
+The files needed for Eiffel printing are distributed separately from
+Basser Lout.  You can get them from the author's @Code ftp directory
+(see the preface of this guide).
+@End @Section
diff --git a/doc/user/cpp_embe b/doc/user/cpp_embe
new file mode 100644
index 0000000..8ca2dfc
--- /dev/null
+++ b/doc/user/cpp_embe
@@ -0,0 +1,152 @@
+@Section
+   @Title { Embedded mode }
+   @Tag { embedded }
+@Begin
+@PP
+When the C program texts are to be embedded in a larger Lout document,
+the procedure is somewhat different.  You need to include the
+@Code "cprint" setup file, like this:
+@ID @OneRow @Code {
+"@SysInclude { cprint }"
+"@SysInclude { doc }"
+"@Doc @Text @Begin"
+"..."
+"@End @Text"
+}
+This file includes everything needed to set up for C program formatting.
+@PP
+The C parts of the document are enclosed in @Code "@CP { ... }" like this:
+@ID @OneRow @Code {
+"@IndentedDisplay @CP {"
+"#include <stdio.h>"
+""
+"treeprint(p)        /* print tree p recursively */"
+"struct tnode *p;"
+"{"
+"        if (p != NULL) {"
+"                treeprint(p->left);"
+"                printf(\"%4d %s\\n\", p->count, p->word);"
+"                treeprint(p->right);"
+"        }"
+"}"
+"}"
+}
+Although C programs violate the rules of legal Lout input in many ways,
+these rules are suspended by the @Code "@CP" symbol, allowing the C
+text to be incorporated with absolutely no modifications.  The result is
+@ID @OneRow @CP {
+#include <stdio.h>
+
+treeprint(p)        /* print tree p recursively */
+struct tnode *p;
+{
+        if (p != NULL) {
+                treeprint(p->left);
+                printf("%4d %s\n", p->count, p->word);
+                treeprint(p->right);
+        }
+}
+}
+We have chosen to use the @Code "@IndentedDisplay" symbol from Section
+{@NumberOf displays} to obtain an indented display, but in fact
+@Code "@CP" may appear anywhere at all.  When including a C text within
+a paragraph, use @Code "@OneCol @CP { ... }" to prevent it being broken
+across two lines, if desired.
+@PP
+In cases where the C text has unbalanced braces, it is necessary to
+use the alternative form @Code "@CP @Begin ... @End @CP" so that
+Lout does not confuse C braces with Lout braces.
+@PP
+The @Code "@CP" symbol has a @Code "style" option for changing the
+printing style.  The default value of @Code "style" is {@Code "fixed"},
+which produces the style shown above.  To obtain a varying-width font
+style, use @Code "style { varying }" like this:
+@ID @OneRow @Code {
+"@CP"
+"    style { varying }"
+"{"
+"#include <stdio.h>"
+""
+"treeprint(p)        /* print tree p recursively */"
+"struct tnode *p;"
+"{"
+"        if (p != NULL) {"
+"                treeprint(p->left);"
+"                printf(\"%4d %s\\n\", p->count, p->word);"
+"                treeprint(p->right);"
+"        }"
+"}"
+"}"
+}
+The result in this case will be
+@ID @OneRow @CP style { varying }
+{
+#include <stdio.h>
+
+treeprint(p)        /* print tree p recursively */
+struct tnode *p;
+{
+        if (p != NULL) {
+                treeprint(p->left);
+                printf("%4d %s\n", p->count, p->word);
+                treeprint(p->right);
+        }
+}
+}
+There is also a third style called @Code "style { symbol }" which is
+similar to @Code "varying" except that it uses characters from the
+Adobe Symbol font to produce a more mathematical-looking result:
+@ID @OneRow @CP style { symbol }
+{
+#include <stdio.h>
+
+treeprint(p)        /* print tree p recursively */
+struct tnode *p;
+{
+        if (p != NULL) {
+                treeprint(p->left);
+                printf("%4d %s\n", p->count, p->word);
+                treeprint(p->right);
+        }
+}
+}
+The @Code "@CP" symbol has additional options which allow a finer
+control over the style.  Here they all are, with their default values:
+@ID @OneRow @Code {
+"@CP"
+"    style { fixed }"
+"    font { Courier }"
+"    strings { Base }"
+"    identifiers { Base }"
+"    comments { Base }"
+"    keywords { Base }"
+"    numbers { Base }"
+"    operators { Base }"
+"    size { -1.0p }"
+"    line { 1.0vx }"
+"    tabin { 8 }"
+"    tabout { 8s }"
+"{"
+"    ..."
+"}"
+}
+We are already familiar with {@Code "style"}.  After that comes
+{@Code "font"}, which determines the font family to use, followed
+by six options giving the particular faces within that family in which to
+print C strings, identifiers, comments, keywords, numbers, and
+operators.  {@Code "Base"} means the basic face; other commonly available
+choices are {@Code "Slope"} and {@Code "Bold"}.  These options may all be
+set to different faces if desired.  The default values shown are correct
+for @Code "style { fixed }" only; the other styles have other defaults
+(Section {@NumberOf cpsetup}).
+@PP
+The @Code "size" option is the font size to use, and @Code "line" is the
+inter-line spacing.  The default values specify that @Code "size" is
+to be one point smaller than in the surrounding document; this was done
+to compensate for Courier's relatively large appearance compared
+to other fonts of the same nominal size.  Again, these defaults are
+different for different values of {@Code "style"}.
+@PP
+The @Code "tabin" and @Code "tabout" options are the subject of
+Section {@NumberOf tabs}.
+@End @Section
diff --git a/doc/user/cpp_lone b/doc/user/cpp_lone
new file mode 100644
index 0000000..8d8e367
--- /dev/null
+++ b/doc/user/cpp_lone
@@ -0,0 +1,36 @@
+@Section
+   @Title { Stand-alone mode }
+   @Tag { alone }
+@Begin
+@PP
+Printing of C files in stand-alone mode is accomplished by the following
+c2lout @Index { @Code "c2lout" filter }
+Unix pipeline:
+@ID @Code "c2lout  options  C-files  |  lout  -s  >  out.ps"
+As usual with Lout, the output will be a PostScript file.  Each input
+file will begin on a new page of the output, starting with its name
+in bold type.  The options provide control over the final appearance,
+as follows:
+@WideTaggedList
+@TI { {@Code-p}{@I style} } {
+Select a printing style.  Your choices are {@Code -pfixed},
+{@Code -pvarying}, and {@Code -psymbol}, with the default being
+{@Code -pfixed}.  Consult Section {@NumberOf embedded} for examples
+of these styles.
+}
+@TI { @Code -n } {
+Do not print file names.
+}
+@TI { {@Code -f}{@I font} } {
+Select a Lout font family.  The default is @Code "-fCourier" for
+{@Code -pfixed}, and @Code "-fTimes" for @Code -pvarying and {@Code -psymbol}.
+}
+@TI { {@Code -v}{@I vsize} } {
+Select an inter-line spacing size in Lout units.  The default is
+@Code -v1.1fx meaning 1.1 times the font size measured from baseline
+to baseline.
+}
+@EndList
+There are also {@Code -t} and {@Code -T} options for dealing with tab
+characters (Section {@NumberOf tabs}).
+@End @Section
diff --git a/doc/user/cpp_tabs b/doc/user/cpp_tabs
new file mode 100644
index 0000000..1157a51
--- /dev/null
+++ b/doc/user/cpp_tabs
@@ -0,0 +1,62 @@
+@Section
+   @Title { Tab characters }
+   @Tag { tabs }
+@Begin
+@PP
+Tab characters provide a convenient way to indent and align parts of C
+tab.c @Index { tab characters in C programs }
+programs.  With care, this alignment can be preserved in the final
+print even with varying-width fonts.
+@PP
+The distance between two tab stops in the input file is by default taken
+to be 8 characters, which is standard for Unix.  This can be changed with
+the @Code "tabin" option.  For example,
+@ID @Code "@CP tabin { 4 }"
+informs Lout that tab stops occur every 4 characters in the input file.
+@PP
+The distance between two tab stops in the output file (on the printed
+page) is quite a different thing, and it is determined by the value of
+the @Code "tabout" option, which must be a Lout length.  For example,
+@ID @Code "@CP tabout { 0.5i }"
+requests that tab stops be placed at half-inch intervals.  In other
+words, a distance of one tab stop in the input will be equivalent to a
+distance of half an inch in the output.  For example,
+@ID @Code "@CP style { varying } tabout { 3f }"
+might produce the following, where tab characters in the input file
+have been used for indenting and also to align the comments:
+@ID @OneRow @CP style { varying } tabout { 3f } {
+struct tnode {			/* the basic node */
+	char *word;		/* points to the text */
+	int count;		/* number of occurrences */
+	struct tnode *left;	/* left child */
+	struct tnode *right;	/* right child */
+};
+}
+The value {@Code "3f"} means three times the current font size, and
+it is the default value of @Code "tabout" for the @Code { varying }
+and @Code { symbol } styles (Section {@NumberOf cpsetup}).  In a
+12 point font this is 36 points, or half an inch.
+@PP
+If @Code "tabout" is made too small, there is a danger that the
+alignment might fail.  For example,
+@ID @Code "@CP style { varying } tabout { 0.2i }"
+produces
+@ID @OneRow @CP style { varying } tabout { 0.2i } {
+struct tnode {			/* the basic node */
+	char *word;		/* points to the text */
+	int count;		/* number of occurrences */
+	struct tnode *left;	/* left child */
+	struct tnode *right;	/* right child */
+};
+}
+given the same C text as the previous example.  The problem here is that
+we are asking for @CP { /* } to appear four tab stops or 0.8 inches
+from the left edge, and yet the material to its left on the line is
+wider than this.  This causes @CP { /* } to be shifted further to the
+right than expected, and the alignment is lost.  The only solution is
+to increase {@Code "tabout"}.
+@PP
+In stand-alone mode there are @Code "-t" and @Code "-T" options
+equivalent to @Code "tabin" and @Code "tabout" respectively.  For
+example, @Code "-T0.5i" produces a half-inch tab width.
+@End @Section
diff --git a/doc/user/dia b/doc/user/dia
new file mode 100644
index 0000000..4029cec
--- /dev/null
+++ b/doc/user/dia
@@ -0,0 +1,46 @@
+@Chapter
+   @Title { Diagrams }
+   @Tag { diagrams }
+@Begin
+@LP
+This chapter describes how to use the @@Diag symbol
+diag. @Index { @@Diag }
+@FootNote {
+Prior to Version 3.09 of Lout, this chapter described a symbol called
+fig. @Index @Code "@Fig"
+{@Code "@Fig"} which was similar to but more primitive than
+{@Code "@Diag"}.  For backward compatibility the @Code "@Fig" symbol
+is still available and still works exactly as described in the old
+documentation, but there is no reason to use it in new documents.
+}
+to make diagrams like this one:
+diag. @Index @Code "@Diag"
+@CD @Diag
+    margin { 0.2c }
+{
+-2p @Font
+{ A:: @Ellipse { 25, 39 }
+/0.3c |0.2c B:: @Ellipse { 43 } |0.1c |0.8c E:: @Box outlinestyle {noline} {Problem node}
+/0.3c C:: @Ellipse { 40, 41 } | | D:: @Ellipse paint { lightgrey } {44, 45, 46}
+}
+// @Link from { A } to { B }
+// @Link from { B } to { C }
+// @Link from { B } to { D }
+// @Arrow from { E } to { D }
+}
+@@Diag offers nodes and links, arrows, labels, positioning using coordinates,
+and tree diagrams.
+@BeginSections
+@Include { dia_intr }
+@Include { dia_node }
+@Include { dia_link }
+@Include { dia_tags }
+@Include { dia_labe }
+@Include { dia_posi }
+@Include { dia_tree }
+@Include { dia_erro }
+@Include { dia_defi }
+@Include { dia_geom }
+@Include { dia_summ }
+@EndSections
+@End @Chapter
diff --git a/doc/user/dia_cons b/doc/user/dia_cons
new file mode 100644
index 0000000..569b756
--- /dev/null
+++ b/doc/user/dia_cons
@@ -0,0 +1,7 @@
+@Section
+    @Tag { dia_cons }
+    @Title { Consistency within and between diagrams }
+@Begin
+@PP
+@I { still to do }
+@End @Section
diff --git a/doc/user/dia_defi b/doc/user/dia_defi
new file mode 100644
index 0000000..ed27887
--- /dev/null
+++ b/doc/user/dia_defi
@@ -0,0 +1,361 @@
+@Section
+    @Tag { dia_defi }
+    @Title { Expert usage:  defining new shapes }
+@Begin
+@PP
+@@Diag permits you to create your own node outlines and link paths, by
+giving non-standard values to the @Code outline and @Code path
+options.  This section shows how to do this for very simple shapes
+only; the following section introduces the large repertoire of geometrical
+symbols that @@Diag offers for helping you create complex shapes.
+@PP
+As explained earlier, a node outline is drawn over its {@I base}, which
+is a rectangle containing the following object plus margins.  The base
+defines a coordinate system with the point (0, 0) at the bottom left
+corner, and @Eq { (xsize, ysize) } at the top right:
+@CD @OneRow @Diag {
+@Box
+    nodelabelmargin { 0.3f }
+    blabel { @Eq { ysize } }
+    blabelprox { E }
+    clabel { @Eq { 0 } }
+    clabelprox { E }
+    dlabel { @Eq { xsize } }
+    dlabelprox { N }
+    alabel { @Eq { 0 } }
+    alabelpos { SW }
+    alabelprox { N }
+    paint { lightgrey }
+    outlinestyle { noline }
+    margin { 0c }
+{ 3c @Wide 2c @High }
+//0.5c
+}
+The value of the @Code outline option is a sequence of points defined in
+this coordinate system:
+@ID {
+@Code {
+"@Node"
+"    outline {"
+"        0 0"
+"        xsize 0"
+"        0 ysize"
+"        0 0"
+"    }"
+}
+||7ct
+@Diag {
+@Box
+    margin { 0c }
+    outlinestyle { noline }
+    paint { lightgrey }
+@Node
+    outline {
+        0 0
+        xsize 0
+        0 ysize
+        0 0
+    }
+    margin { 0c }
+{ 3c @Wide 2c @High }
+}
+}
+As shown, the resulting outline is created by joining each point to the
+next with a straight line.  It is conventional to proceed anticlockwise
+around the outline, but you may start anywhere.
+@PP
+The {@Code paint}, {@Code outlinestyle}, {@Code outlinedashlength},
+and {@Code outlinewidth} options of @Code "@Node" work for user-defined
+outlines exactly as they do for the standard ones:
+@ID {
+@Code {
+"@Node"
+"    outline {"
+"        0 0"
+"        xsize 0"
+"        0 ysize"
+"        0 0"
+"    }"
+"    paint { lightgrey }"
+"    outlinestyle { solid dashed }"
+}
+||7ct
+@Diag {
+@Node
+    outline {
+        0 0
+        xsize 0
+        0 ysize
+        0 0
+    }
+    paint { lightgrey }
+    outlinestyle { solid dashed }
+    margin { 0c }
+{ 3c @Wide 2c @High }
+}
+}
+Each line in the outline is one segment for {@Code outlinestyle}.
+@PP
+If two points in an outline are separated by {@Code "[]"}, no line is
+drawn between them, and the outline is treated as two separate,
+disconnected regions when painting.
+@PP
+Two points may also be separated by {@Code "["}{@I point}{@Code "]"},
+where @I point stands for any point.  This causes the two points to be
+joined by an arc whose centre is at the given point:
+@ID {
+@Code {
+"@Node"
+"    outline {"
+"        0 0"
+"        ysize 0"
+"        [ 0 0 ]"
+"        0 ysize"
+"        0 0"
+"    }"
+}
+||7ct
+@Diag {
+@Box
+    margin { 0c }
+    outlinestyle { noline }
+    paint { lightgrey }
+@Node
+    outline {
+        0 0
+        ysize 0
+        [ 0 0 ]
+        0 ysize
+        0 0
+    }
+    margin { 0c }
+{ 3c @Wide 2c @High }
+}
+}
+The arc will be circular if possible, otherwise it will be part of
+elliptical. @Index { elliptical arcs }
+an ellipse whose axes are oriented horizontally and vertically.  The
+arc goes anticlockwise; to get a clockwise arc, use
+{@Code "["}{@I point}{@Code " clockwise]"}.
+@PP
+Two points may be separated by
+@Eq { [x sub 1 ``` y sub 1 ```  x sub 2 ``` y sub 2 & ] }, which requests
+that a Bezier curve be drawn between them with control points
+bezier.curve @Index { Bezier curve }
+@Eq { (x sub 1 & , y sub 1 & ) } and
+@Eq { (x sub 2 & , y sub 2 & ) }:
+@CD @Diag {
+@Node
+    outline {
+        A:: { xsize*0.2 ysize*0.5 }
+        B:: { xsize*0.4 ysize*0.9 }
+        C:: { xsize*0.9 ysize*0.4 }
+        D:: { xsize*0.3 ysize*0.1 }
+        A B C D A
+    }
+    alabelpos { A }
+    blabelpos { B }
+    clabelpos { C }
+    dlabelpos { D }
+    alabelprox { SE }
+    blabelprox { SW }
+    clabelprox { SW }
+    dlabelprox { NW }
+    outlinestyle { cdashed cdashed cdashed noline }
+    alabel { @Eq { ( x sub 0 , y sub 0 ) } }
+    blabel { @Eq { ( x sub 1 , y sub 1 ) } }
+    clabel { @Eq { ( x sub 2 , y sub 2 ) } }
+    dlabel { @Eq { ( x sub 3 , y sub 3 ) } }
+{ 6c @Wide 2c @High }
+//
+@Link
+    path { A [B C] D }
+}
+The curve is attracted toward the control points, without reaching
+them; it is tangent to the straight line from the start point to the
+first control point, and from the second control point to the finishing
+point, and it lies wholly inside the quadrilateral formed by the four
+points.  Owing to the author's laziness, dashes and dots do not fit as
+neatly onto Bezier curves as they do onto lines and arcs.
+@PP
+Tags (Section {@NumberOf dia_tags}) may be assigned to points within
+the outline option, like this:
+@ID {
+@Code {
+"@Node"
+"    outline {"
+"        LR:: { xsize 0 }"
+"        UL:: { 0 ysize }"
+"        0 0  LR  UL  0 0"
+"    }"
+}
+||7ct
+@Diag {
+//0.5f
+@ShowTags @Node
+    outline {
+        LR:: { xsize 0 }
+        UL:: { 0 ysize }
+        0 0  LR  UL  0 0
+    }
+    { 2c @High 3c @Wide }
+}
+}
+The tagged point does not have to lie on the outline, and it
+is not automatically added to the outline.  Once defined, a
+tag stands for a point in the usual way; it may be used later in the
+outline, as was done above, relabelled, and so on, exactly like the tags
+of the standard nodes.
+@PP
+Once a point has been tagged, a @I direction may be associated
+with it, to inform @@Diag which way the outline or
+link path is going at that point.  The standard outlines have directions:
+@ID {
+@Code {
+"@Ellipse { 3c @Wide 1c @High }"
+}
+||7ct
+@Diag {
+//0.5f
+@ShowTags @ShowDirections @Ellipse { 3c @Wide 1c @High }
+}
+}
+@Code CTR has no direction.  If available, direction information
+is used when placing labels, in the proximity step (by {@Code above}, for
+example) and in the angle step if the label is aligned, perpendicular,
+parallel, or antiparallel.  A direction is given using the
+@Code ":<" symbol within an outline:
+@ID {
+@Code {
+"@Node"
+"    outline {"
+"        LR:: { xsize 0 }"
+"        LR:< 0d"
+"        UL:: { 0 ysize }"
+"        UL:< 270d"
+"        0 0 LR UL 0 0"
+"    }"
+}
+||7ct
+@Diag {
+//0.5f
+@ShowTags @ShowDirections @Node
+    outline {
+        LR:: { xsize 0 }
+        LR:< 0d
+        UL:: { 0 ysize }
+        UL:< 270d
+        0 0 LR UL 0 0
+    }
+    { 2c @High 3c @Wide }
+}
+}
+It is often helpful when creating outlines to check where the tagged
+points and directions really are, by printing them out as is done
+above.  For this there is a @Code "@ShowTags" symbol whose result is
+the following (arbitrary) object with its tagged points visible, and
+a @Code "@ShowDirections" symbol which works similarly and shows the
+directions.  The diagram above was printed using
+{@Code "@ShowTags @ShowDirections @Node ..."}.  There is also a
+@Code "@ShowPoints" symbol which is like @Code "@ShowTags" except
+that it omits the tags, just placing circles on the points.
+@PP
+Link paths are similar to node outlines, created
+using the @Code path option of @Code "@Link" instead of the
+@Code outline option of {@Code "@Node"}.  The major difference is that
+links have no base, so @Code xsize and @Code ysize cannot be
+used.  Indeed, even @Code "0 0" does not have any useful
+meaning inside a link path.
+@PP
+Within a link path, the symbols @Code from and @Code to denote the
+values of the link's @Code from and @Code to options, and these
+form the basis of constructing the link path:
+@ID {
+@Code {
+"@Link"
+"    path {"
+"        FROM:: from"
+"        TO:: to"
+"        FROM TO"
+"    }"
+}
+||7ct
+{
+//1.0c
+@VContract @Diag {
+3c @Wide 1c @High
+//
+@ShowTags @Link
+    path {
+        FROM:: from
+        TO:: to
+        FROM TO
+    }
+    from { 0,1 }
+    to { 1,0 }
+}
+}
+}
+This simple example creates two tagged points and joins them with
+a straight line.  If you want a link that can carry arrowheads, it is
+best to ensure that it creates @Code FROM and @Code TO tags, with
+directions pointing along the link from @Code FROM to @Code TO at
+both points, since then the default values of the various arrow
+options will do the rest.  Similarly, if you want labels you need to
+define {@Code LFROM}, {@Code LMID}, and {@Code LTO} labels, ideally
+also with directions.
+@PP
+Once the outline or path is complete, unless it is really a one-off
+production the best thing to do with it is to add it to your
+extend. @Index { @Code extend keyword }
+@Code "mydefs" file in the following form:
+@ID @OneRow @Code {
+"extend @DiagSetup @Diag"
+"macro @MyNode {"
+"    @Node"
+"        outline {"
+"            LR:: { xsize 0 }"
+"            LR:< 0d"
+"            UL:: { 0 ysize }"
+"            UL:< 270d"
+"            0 0 LR UL 0 0"
+"        }"
+"}"
+}
+This says that we are `extending' the @@Diag symbol by adding a new
+symbol, {@Code "@MyNode"}, which stands for what follows it between
+braces.  @Code "@MyNode" will then behave exactly like @Code "@Circle"
+and the other standard node symbols.  The same pattern works for links:
+@ID @OneRow @Code {
+"extend @DiagSetup @Diag"
+"macro @MyLink {"
+"    @Link"
+"        path {"
+"            FROM:: from"
+"            TO:: to"
+"            FROM TO"
+"        }"
+"}"
+}
+If it is worth the effort to construct a new outline or link path, it
+is worth packaging it like this and thinking up a good name for it,
+for then it will be available, easily, forever.
+@PP
+This same approach is also useful to define common combinations of
+options, even when there is no new outline or path:
+@ID @OneRow @Code {
+"extend @DiagSetup @Diag"
+"macro @BigOctagon {"
+"    @Polygon"
+"        sides { 8 }"
+"        hsize { 5c }"
+"        vsize { 5c }"
+"        font { Bold }"
+"}"
+}
+Such definitions are very useful if the combinations occur
+frequently.  Any options not mentioned have their usual default values,
+and may be set in the usual way:
+@ID @Code "@BigOctagon outlinestyle { dashed } ..."
+Attempts to reset an already set option will elicit a warning message.
+@End @Section
diff --git a/doc/user/dia_erro b/doc/user/dia_erro
new file mode 100644
index 0000000..2ad02d5
--- /dev/null
+++ b/doc/user/dia_erro
@@ -0,0 +1,45 @@
+@Section
+    @Tag { dia_erro }
+    @Title { Errors }
+@Begin
+@PP
+Lout normally produces an output file that will print without mishap on
+any PostScript device.  However, some of the options of {@Code "@Diag"}'s
+symbols are passed through Lout to the output file without checking,
+including anything containing @Code "@Diag" lengths, angles, points, and
+tags.  Any errors in these options will not be detected until the file
+is printed.
+@PP
+The most likely errors are {@I syntax @I errors}, as in
+@Code "outline { 0 0 [ 0 xsize }" for example, in which a @Code "]" is
+missing; @I { type errors }, as in @Code "SE:: 45d" where the
+following object should have been a point; and @I { undefined errors },
+arising from labels misspelt or used before being defined.  Less commonly,
+the options may all be correct but the figure is too large in some way:  too
+many labels, too deeply nested, and so on.
+@PP
+When an error is detected, @@Diag arranges for the offending page to
+be printed up to the point where the error occurred, with a message nearby
+describing the error.  Printing of the document is then aborted.  It is
+often quite easy to find the problem, because it lies in whatever should
+have been printed next.
+@PP
+If you see {@Code VMerror} in an error message, it means that the printer
+vmerror. @Index { @Code VMerror PostScript error }
+is running out of memory.  In that case, one thing you can try is
+@ID @Code {
+"@Diag"
+"    save { yes }"
+"..."
+}
+This causes the memory used by @@Diag to be reclaimed as soon
+as the diagram is printed, rather than at the end of the current page
+as is usual.  However, if the diagram is nested inside some other
+major Lout package, such as {@Code "@Graph"}, use of this option may
+cause other PostScript errors.
+@PP
+If you see @Code "dictfull" in an error message, it means that you are
+dictfull. @Index { @Code dictfull PostScript error }
+using an old version of PostScript.  Increasing the @Code "maxlabels"
+option of @@Diag (Section {@NumberOf dia_summ}) might fix the problem.
+@End @Section
diff --git a/doc/user/dia_geom b/doc/user/dia_geom
new file mode 100644
index 0000000..bfc9c02
--- /dev/null
+++ b/doc/user/dia_geom
@@ -0,0 +1,208 @@
+@Section
+    @Tag { dia_geom }
+    @Title { Expert usage:  numbers, lengths, angles, and points }
+@Begin
+@PP
+@@Diag has many options whose values contain lengths, angles, and
+points.  Options such as @Code margin and {@Code vsize}, which affect the
+size or appearance of the base of a node, may contain only the kinds of
+lengths described in Section {@NumberOf objects}; but in all other cases
+arbitrarily complex algebraic expressions may be used to specify the
+values.
+@PP
+The usual mathematical operations may be applied to numbers, angles, and
+lengths:
+@ID @Code "2.0f + 3.0f * sin { 30d }"
+is a valid length.  Since this is just ordinary algebra on real numbers,
+the unsurprising details are deferred to the summary
+(Section {@NumberOf dia_summ}).  Grouping is always done with braces,
+never parentheses.
+@PP
+More interesting are the geometrical symbols that @@Diag provides.  The
+most fundamental is not a symbol at all:  two lengths side by side define
+a point.  For example,
+@ID @Code "xsize  ysize * 0.5"
+within an outline is the point at the far right of the base, halfway
+up.
+@PP
+There are @Code "++" and @Code "--" symbols for vector addition and
+subtraction of two points, and @Code "**" for multiplication by a
+scalar.  For example,
+@ID @Code "A@CTR ++ { 1.0f 0 }"
+is the point @Code 1f to the right of {@Code "A@CTR"}.  It is a good idea
+to distinguish between @I { absolute points }, like {@Code "A@CTR"}
+and @Code "0.5,1", which denote fixed positions on the page, and
+@I { relative points }, like {@Code "1.0f 0"}, which serve as offsets
+from absolute points.  The difference of two absolute points is a relative
+point; adding two absolute points gives an unpredictable result because
+it depends on the origin of the coordinate system.  However, the expression
+@ID @Code "P1 ** x ++ P2 ** {1 - x}"
+is safe for any two absolute points {@Code P1} and {@Code P2} and any
+number {@Code x}; it produces a point on the line through the two
+points.
+@PP
+These remarks on safety do not apply within the @Code outline option of
+{@Code "@Node"}, because there the coordinate system is clearly
+specified.  Vector operations, with the aid of a few well-chosen tags,
+can greatly simplify the production of outlines:
+@ID {
+@Code {
+"@Node"
+"   outline {"
+"      SB:: {0 ysize} ** 0.4"
+"      ST:: {0 ysize} ** 0.6"
+"      HB:: {xsize 0} ** 0.7"
+"      SB"
+"      SB ++ HB"
+"      HB"
+"      xsize  ysize * 0.5"
+"      HB ++ {0 ysize}"
+"      HB ++ ST"
+"      ST"
+"      SB"
+"   }"
+"   paint { grey }"
+"{ 6c @Wide 2c @High }"
+}
+||7ct
+@Diag {
+@ShowTags @Node
+   outline {
+      SB:: {0 ysize} ** 0.4
+      ST:: {0 ysize} ** 0.6
+      HB:: {xsize 0} ** 0.7
+      SB
+      SB ++ HB
+      HB
+      xsize  ysize * 0.5
+      HB ++ {0 ysize}
+      HB ++ ST
+      ST
+      SB
+   }
+   paint { grey }
+{ 6c @Wide 2c @High }
+}
+}
+But absolute sums like @Code "SB ++ HB" are not safe
+in link paths and stray options like {@Code "alabelpos"}.
+@PP
+Sometimes it is useful to define tags
+which are not wanted afterwards and are better forgotten.  For
+this there is the @Code ":=" symbol, which works in much the same
+way as @Code "::" except that the tag is forgotten after the outline
+or path option ends.  The value assigned does not have to be a point, it
+can be a length or angle, or even a sequence of values.  It is
+permissible to change the value assigned to a tag by reassigning.
+@PP
+Two very useful symbols, {@Code angleto} and {@Code atangle}, bring
+angleto. @Index { @Code angleto symbol in @Code "@Diag" }
+atangle. @Index { @Code atangle symbol in @Code "@Diag" }
+angles into the algebra.  The {@Code angleto} symbol finds the angle
+from one point to another.  For example,
+@ID @Code "SB angleto ST"
+in the outline above would produce {@Code 90d}.  The @Code atangle symbol
+finds the point at a given length and angle from the origin.  For example,
+@ID @Code "1.4142f atangle 45d"
+is the point {@Code "1f 1f"}, and
+@ID @Code "B@NE  ++ 2f atangle 115d"
+is the point @Code 2f from {@Code "B@NE"} to its northwest.
+@PP
+There is a @Code prev symbol, used only within {@Code outline} and
+prev. @Index { @Code prev symbol in @Code "@Diag" }
+{@Code path}, which returns the previous point on the outline or
+path, ignoring points within {@Code "[]"}.  It makes relative movements
+very easy:
+@ID {
+@Code {
+"   outline {"
+"      0 0"
+"      { 2c atangle 30d }"
+"      prev ++ { 2c atangle 90d }"
+"      prev ++ { 2c atangle 150d }"
+"      prev ++ { 2c atangle 210d }"
+"      prev ++ { 2c atangle 270d }"
+"      0 0"
+"   }"
+}
+||7ct
+@Diag { ||2.5c
+@Node
+   outline {
+      0 0
+      { 2c atangle 30d }
+      prev ++ { 2c atangle 90d }
+      prev ++ { 2c atangle 150d }
+      prev ++ { 2c atangle 210d }
+      prev ++ { 2c atangle 270d }
+      0 0
+   }
+{ 4c @Wide 4c @High }
+}
+}
+This example is rather naughty because the outline does not grow and
+shrink with the base as it should.  Such outlines, while tempting, are
+always regretted later.
+@PP
+There are {@Code xcoord} and {@Code ycoord} symbols for finding the
+xcoord. @Index { @Code xcoord symbol in @Code "@Diag" }
+ycoord. @Index { @Code ycoord symbol in @Code "@Diag" }
+@I x and @I y coordinates of a point:
+@ID @Code {
+"{xcoord P1} min {xcoord P2}"   "{ycoord P1} max {ycoord P2}"
+}
+is the point at the top left-hand corner of the smallest rectangle
+containing points {@Code P1} and {@Code P2}.  And there is a
+@Code distance symbol which produces the (non-negative) distance between
+two points:
+@ID @Code "CTR  ++  { CTR distance NW } atangle { CTR angleto NW }"
+equals {@Code NW}.
+@PP
+The rest of this section is concerned with how the `special virtue'
+of the @Code from and @Code to options, their ability to accept a node
+tag as well as a point, is implemented behind the scenes.  A good
+user-defined link should also have this virtue, because it is extremely
+useful.
+@PP
+The solution is based on a symbol called {@Code boundaryatangle},
+whose preceding object should be either a point or else the tag
+of a node with one of the standard shapes, and whose following object
+is an angle:
+@ID @Code {
+"{ xsize ysize*0.5 } boundaryatangle 45d"
+"A boundaryatangle 45d"
+}
+In the first case the result is the point, regardless of the
+angle.  In the second case, the result is the point on the boundary of
+the node whose tag is given, at the given angle from the centre.
+@PP
+There is a second symbol with a similar adaptive ability, called
+{@Code "??"}, which is defined to be @Code "@" whenever that would
+make sense, and otherwise to produce the preceding object for its
+result.  For example, @Code "A??CTR" will equal @Code "A@CTR" if there
+is such a thing; but
+@ID @Code "{ xsize ysize*0.5 }??CTR"
+will have result {@Code "{ xsize ysize*0.5 }"} since replacing
+@Code "??" by @Code "@" does not produce anything sensible.
+@PP
+Now suppose we want a link path that connects @Code "from" and
+@Code "to" by a straight line, where @Code "from" and @Code "to" may be
+either node tags or points.  In either case a suitable direction for the
+line to take is
+@ID @Code "from??CTR angleto to??CTR"
+and so the desired path is
+@ID @Code {
+"path {"
+"    FROM:: from boundaryatangle { from??CTR angleto to??CTR }"
+"    TO:: to boundaryatangle { to??CTR angleto from??CTR }"
+"    FROM"
+"    TO"
+"}"
+}
+The first line defines point @Code FROM to be on the boundary of
+@Code from at the appropriate angle, if @Code "from" is a node tag;
+otherwise @Code "FROM" is just the point {@Code from}.  The second
+line defines point @Code TO similarly, and then the last two lines
+join these two points.  The @Code line standard link type is exactly
+this plus a few additional tags and directions.
+@End @Section
diff --git a/doc/user/dia_intr b/doc/user/dia_intr
new file mode 100644
index 0000000..52a9d49
--- /dev/null
+++ b/doc/user/dia_intr
@@ -0,0 +1,108 @@
+@Section
+    @Tag { dia_intr }
+    @Title { Introduction }
+@Begin
+@PP
+To use the @@Diag symbol you first need to include its setup file.  For
+example, suppose you have an ordinary document with tables:
+@ID @OneRow @Code {
+"@SysInclude { tbl }"
+"@SysInclude { doc }"
+"@Doc @Text @Begin"
+"..."
+"@End @Text"
+}
+Change this to
+@ID @OneRow @Code {
+"@SysInclude { tbl }"
+"@SysInclude { diag }"
+"@SysInclude { doc }"
+"@Doc @Text @Begin"
+"..."
+"@End @Text"
+}
+This provides everything you need for making diagrams.
+@PP
+The result of the @@Diag symbol is an object in the usual way.  A diagram
+is commonly made into a centred display, like this:
+@ID @OneRow @Code {
+"@CentredDisplay @Diag {"
+"    ..."
+"}"
+}
+or into a floating figure, like this:
+@ID @OneRow @Code {
+"@Figure"
+"    @Caption { ... }"
+"@Diag {"
+"    ..."
+"}"
+}
+but it could be an entry in a table, a word in a paragraph, or anything
+else.
+@PP
+Most uses of @@Diag contain a @I { nodes part } and a @I { links part }:
+@ID @OneRow lines @Break {
+@Code "@Diag {"
+    @I { nodes part }
+    @Code "//"
+    @I { links part }
+@Code "}"
+}
+This reflects @@Diag's view of the world as consisting of {@I nodes}
+(circles, squares, and so on), which have to be put in their right
+places and then joined with @I links (lines, arrows).  The technical
+meaning of the {@Code "//"} symbol does not concern us here; it
+simply serves to divide the two parts.
+@PP
+For example, here is a nodes part containing two nodes separated by
+a @Code "@DP" symbol that (as usual) leaves some vertical space
+between them:
+@ID @OneRow @Tab
+  @Fmta { @Col 7c @Wide A ! @Col B }
+{
+@Rowa
+    A { @Code {
+"@Ellipse { Hello, world }"
+"@DP"
+"@Square @I x"
+} }
+    B { @Diag {
+@Ellipse { Hello, world }
+@DP
+@Square @I x 
+} }
+}
+Node symbols like @Code "@Ellipse" and @Code "@Square" follow a familiar
+pattern:  they consume the following object, which may be arbitrary, draw
+a shape around it, and give back the resulting object.  To insert links, the
+nodes must first be given names, called {@I tags}, using the @Code "::" symbol:
+@ID @OneRow @Code {
+"A:: @Ellipse { Hello, world }"
+"@DP"
+"B:: @Square @I x"
+}
+Then a link from @Code A to @Code B may be added to the links part:
+@ID @OneRow @Tab
+  @Fmta { @Col 7c @Wide A ! @Col B }
+{
+@Rowa
+    A { @Code {
+"@Diag {"
+"    A:: @Ellipse { Hello, world }"
+"    @DP"
+"    B:: @Square @I x"
+"    //"
+"    @Link from { A } to { B }"
+"}"
+} }
+    B { @Diag {
+A:: @Ellipse { Hello, world }
+@DP
+B:: @Square @I x 
+//
+@Link from { A } to { B }
+} }
+}
+Subsequent examples will often omit the enclosing {@Code "@Diag { }"}.
+@End @Section
diff --git a/doc/user/dia_labe b/doc/user/dia_labe
new file mode 100644
index 0000000..c449367
--- /dev/null
+++ b/doc/user/dia_labe
@@ -0,0 +1,433 @@
+@Section
+    @Tag { dia_labe }
+    @Title { Labels }
+@Begin
+@PP
+Diagrams often contain small @I labels adjacent to their nodes and links:
+@CD @Diag
+    nodelabelformat { @I @Body }
+{
+@Tab
+    @Fmta { @Col A ! @Col ! @Col ! @Col B ! @Col ! @Col ! @Col C }
+{
+@Rowa
+    B { B:: @Circle alabel { b } }
+@Rowa
+    A { A:: @Circle alabel { a } }
+@Rowa
+    C { C:: @Circle dlabel { c } }
+}
+//
+@Arrow from { A } to { B } ylabel { 10 }
+@Arrow from { A } to { C } ylabel { 15 }
+@Arrow from { B } to { C } ylabel { 20 }
+}
+Each node may have up to four labels, called {@Code alabel}, {@Code blabel},
+label.  @Index { label options in @Code "@Diag" }
+alabel. @Index { @Code alabel option in @Code "@Diag" }
+blabel. @Index { @Code blabel option in @Code "@Diag" }
+clabel. @Index { @Code clabel option in @Code "@Diag" }
+dlabel. @Index { @Code dlabel option in @Code "@Diag" }
+{@Code clabel}, and {@Code dlabel}:
+@ID {
+@Code {
+"@Ellipse"
+"    alabel { a }"
+"    blabel { b }"
+"    clabel { c }"
+"    dlabel { d }"
+"{ Hello, world }"
+}
+||7ct
+@VContract @Diag {
+@Ellipse
+    alabel { a }
+    blabel { b }
+    clabel { c }
+    dlabel { d }
+{ Hello, world }
+}
+}
+Links also have labels, five in fact:
+@ID {
+@Code {
+"@Link"
+"    fromlabel { f }"
+"    xlabel { x }"
+"    ylabel { y }"
+"    zlabel { z }"
+"    tolabel { t }"
+}
+||7ct
+@VContract @Diag {
+3c @Wide 1c @High
+//
+@Link
+    from { 0 0 }
+    to { 1,1 }
+    fromlabel { f }
+    xlabel { x }
+    ylabel { y }
+    zlabel { z }
+    tolabel { t }
+}
+}
+The {@Code fromlabel} and {@Code tolabel} options are positioned directly
+over the endpoints of the link, and {@Code fromlabel} is by default printed
+at a funny angle, because these labels are the means of attaching
+arrowheads to links:
+@ID {
+@Code {
+"@Link"
+"    tolabel { @SolidArrowHead }"
+}
+||7ct
+@VContract @Diag {
+3c @Wide 1c @High
+//
+@Link
+    from { 0 0 }
+    to { 1,1 }
+    tolabel { @SolidArrowHead }
+}
+}
+@Code "@SolidArrowHead" is a symbol available for use anywhere whose value
+is an object in the shape of a small solid arrowhead.  The arrowhead
+options of Section {@NumberOf dia_link} work by setting {@Code fromlabel}
+and {@Code tolabel} in exactly this way.  Usually it is best to forget
+about {@Code fromlabel} and {@Code tolabel}, and think of links as having
+three labels:  {@Code xlabel} near the start, {@Code ylabel} in the
+middle, and {@Code zlabel} near the end.
+@PP
+Adding a label will not change the size of the diagram or the position
+of any node, link, or other label.  Although a label may be an arbitrary
+object, it is treated as having zero size and will overstrike anything
+that happens to be where it wants to go.
+@PP
+There are options for controlling the appearance and position of
+labels.  These are described below mainly for {@Code alabel}, but there
+are corresponding options for all nine labels.
+@PP
+The {@Code alabelfont} and {@Code alabelbreak} options determine the
+font and paragraph breaking style of the label:
+@ID {
+@Code {
+"@Ellipse"
+"    alabel { a }"
+"    alabelfont { -2p }"
+"    alabelbreak { ragged nohyphen }"
+"{ Hello, world }"
+}
+||7ct
+@VContract @Diag {
+@Ellipse
+    alabel { a }
+    alabelfont { -2p }
+    alabelbreak { ragged nohyphen }
+{ Hello, world }
+}
+}
+This example shows the default values of these two options; @Code "-2p"
+explains why the labels in earlier examples were printed in a smaller
+font size.  There is also an {@Code alabelformat} option which allows
+for more radical changes in appearance:
+@ID {
+@Code {
+"@Ellipse"
+"    alabel { a }"
+"    alabelformat { @Box @I @Body }"
+"{ Hello, world }"
+}
+||7ct
+@Diag {
+//0.5c
+@Ellipse
+    alabel { a }
+    alabelformat { @Box @I @Body }
+{ Hello, world }
+}
+}
+The value attached to the ellipse will be the value of {@Code alabelformat},
+with any @Code "@Body" symbol within it replaced by the value of the
+{@Code alabel} option.  This example produces boxed italic labels.
+@PP
+Nodes also have {@Code nodelabelfont}, {@Code nodelabelbreak}, and
+{@Code nodelabelformat} options which work in the same way but affect all
+of the node labels, not just one:
+@ID {
+@Code {
+"@Ellipse"
+"    nodelabelformat"
+"        { @Box @I @Body }"
+"    alabel { a }"
+"    blabel { b }"
+"{ Hello, world }"
+}
+||7ct
+@Diag {
+//0.5c
+@Ellipse
+    nodelabelformat { @Box @I @Body }
+    alabel { a }
+    blabel { b }
+{ Hello, world }
+}
+}
+Links similarly have {@Code linklabelfont}, {@Code linklabelbreak}, and
+{@Code linklabelformat} options which affect all the link labels
+(except {@Code fromlabel} and {@Code tolabel}, since that would produce
+results that people do not expect.)  The @Code "@Diag" symbol also has
+these options, in the usual way, and they are extremely useful there:
+@ID {
+@Code {
+"@Diag"
+"    nodelabelfont { Slope -2p }"
+"    linklabelformat { \"/\"@Body\"/\" }"
+"    hsize { 1.8c }"
+"{"
+"    A:: @Ellipse alabel { a } { OK }"
+"    @DP"
+"    @DP"
+"    B:: @Ellipse alabel { b } { FAULT }"
+"    //"
+"    @Arrow from { A } to { B } ylabel { sig }"
+"}"
+}
+||7ct
+@VContract @Diag
+    nodelabelfont { Slope -2p }
+    linklabelformat { "/"@Body"/" }
+    hsize { 1.8c }
+{
+    A:: @Ellipse alabel { a } { OK }
+    @DP
+    @DP
+    B:: @Ellipse alabel { b } { FAULT }
+    //
+    @Arrow  from { A } to { B } ylabel { sig }
+}
+}
+These settings specify that every node label will be set in italics,
+two points smaller than the surrounding text, and that every link label
+will appear between two @Code "/" characters, also two points smaller
+because the default value of @Code "linklabelfont" still applies.  Of
+course, it remains open to any node or link to override these settings
+by supplying its own label options.
+@PP
+The remaining five label options, {@Code alabelpos}, {@Code alabelangle},
+{@Code alabelprox}, {@Code alabelmargin}, {@Code alabelctr}, and
+{@Code alabeladjust},
+affect the position of the label.  Don't be daunted by the number of
+options.  As previous examples have shown, they all have sensible
+default values and thus need to be set only rarely.
+@PP
+Each label inhabits its own characteristic region of the node or
+link:  {@Code alabel} in the north-east corner of the node,
+{@Code ylabel} halfway along the link, and so on.  This general
+location of the label is defined by the {@Code alabelpos} option.  Here
+are the default values for all nine labels:
+@IL
+@LI {
+@Code {
+"@Node"
+"    alabelpos { NE }"
+"    blabelpos { NW }"
+"    clabelpos { SW }"
+"    dlabelpos { SE }"
+}
+||7ct
+@VContract @Diag {
+//0.5f
+@ShowTags @Ellipse { 3c @Wide 2c @High }
+}
+}
+@LI {
+@Code {
+"@Link"
+"    fromlabelpos { FROM }"
+"    xlabelpos { LFROM }"
+"    ylabelpos { LMID }"
+"    zlabelpos { LTO }"
+"    tolabelpos { TO }"
+}
+||7ct
+@VContract @Diag {
+//1.0f
+2c @Wide 2.2c @High
+//
+@ShowTags @Link
+    from { 0,0.7 }
+    to { 1,0 }
+    # tolabel { @SolidArrowHead }
+}
+}
+@EL
+Thus, by changing @Code clabelpos to @Code S you can move the position
+of the @Code clabel label to beneath the node.  You can do this for every
+node by setting this option in the @Code "@Diag" symbol, as was done for
+the formatting options above.
+@PP
+In a similar vein, there is an @Code { xindent } option which controls how
+far from the start of the link the @Code "LFROM" tag, and hence the
+{@Code xlabel}, will appear.  A similar option, @Code { zindent }, determines
+how far from the end of the link the @Code "LTO" tag and hence the
+{@Code zlabel} will appear:
+@ID {
+@Code {
+"@Link"
+"    xindent { 1f }"
+"    zindent { 2f }"
+}
+||7ct
+@VContract @Diag {
+//1f
+2c @Wide 1.2c @High
+//
+@ShowTags @Link
+    xindent { 1f }
+    zindent { 2f }
+    from { 0,0.7 }
+    to { 1,0 }
+}
+}
+Both options have default value {@Code 0.8f}.
+@PP
+The @Code alabelangle option determines the angle at which the label is
+printed:
+@ID @Tab
+    @Fmta { @Col @Code A ! @Col B }
+{
+@Rowa
+    A { "alabelangle { horizontal }" }
+    B { Horizontal (the default) }
+@Rowa
+    A { "alabelangle { aligned }" }
+    B { Aligned with the node outline or link path }
+@Rowa
+    A { "alabelangle { perpendicular }" }
+    B { Perpendicular to the outline or link path }
+}
+The @Code "alabelprox" option determines where in the proximity of
+@Code alabelpos the label is printed:
+@ID @Tab
+    @Fmta { @Col @Code A ! @Col B }
+{
+@Rowa
+    A { "alabelprox { above }" }
+    B { Above the node outline or link path (the default for link labels) }
+@Rowa
+    A { "alabelprox { below }" }
+    B { Below the node outline or link path }
+@Rowa
+    A { "alabelprox { left }" }
+    B { To the left of the node outline or link path }
+@Rowa
+    A { "alabelprox { right }" }
+    B { To the right of the node outline or link path }
+@Rowa
+    A { "alabelprox { inside }" }
+    B { Inside the node outline or on the left of the link path
+going from @Code from to @Code to }
+@Rowa
+    A { "alabelprox { outside }" }
+    B { Outside the node outline or on the right of the link path
+going from @Code from to @Code to (the default for node labels) }
+}
+The {@Code alabelmargin} option adds a margin around all four sides of
+the label, thereby moving it away from {@Code alabelpos} irrespective of
+which direction it happens to lie in:
+@ID {
+@Code {
+"@Ellipse"
+"    alabel { a }"
+"    alabelmargin { 0f }"
+"{ Hello, world }"
+}
+||7ct
+@VContract @Diag {
+@Ellipse
+    alabel { a }
+    alabelmargin { 0f }
+{ Hello, world }
+}
+}
+The default value is {@Code 0.2f}, and so there is scope for some
+reduction as well as increase.
+@PP
+@@Diag takes careful account of the @Code alabelangle option, the
+@Code alabelprox option, the direction that the node outline or link
+path is heading, and which label it is, and places the label in a way
+that looks good nearly always.  When it doesn't, the remainder of this
+section should help.
+@PP
+The @Code alabelangle option may be given an arbitrary angle, and then
+the label will be printed at that angle.  There are also the special
+values @Code parallel and {@Code antiparallel}, which give the direction
+that the node outline or link path is going at that point and its
+opposite.  These are the default values for @Code tolabelangle and
+@Code fromlabelangle respectively, which explains why arrowheads point the
+right way.  The @Code aligned value above is one of these two angles,
+the one closest to {@Code 0d}.
+@PP
+The @Code alabelprox option may be {@Code N},
+{@Code S}, {@Code E}, {@Code W}, {@Code NE}, {@Code SE}, {@Code NW},
+{@Code SW}, or {@Code CTR}:
+@CD @Diag {
+//1f
+@ShowTags @Box margin { 0.5c } { 24p @Font grey @Colour @I label }
+}
+meaning that the indicated point of the label will coincide with
+{@Code alabelpos}.  These points lie on the outside of the margins
+added by {@Code alabelmargin}.
+@PP
+The six values of @Code alabelprox given earlier (@Code { above },
+@Code { below }, etc.) all produce one of {@Code N}, {@Code S} etc. for
+their ultimate result; which one they produce depends on the direction
+the outline or link is going at that point.  For example, @Code { above }
+produces @Code { SE } when the outline or link is going from northeast
+to southwest or vice versa, @Code { SW } when the outline or link is
+going from northwest to southeast and vice versa, and @Code { S } when
+it happens to be exactly horizontal.  There is also a dependence
+on which label it is:  for example, if it is @Code "xlabel" and the
+direction happens to be vertical, the result is {@Code "NW"}.
+@PP
+The preceding discussion is all under the assumption that the
+@Code "alabelctr" option is {@Code no}.  When it is {@Code "yes"},
+a small adjustment is made to the position of the label.  The selected
+corner or side midpoint of the label will no longer coincide with
+{@Code alabelpos}, although it will still lie on the straight line passing
+through {@Code alabelpos} at the angle of {@Code alabelpos}.  The corner
+or side midpoint slides up or down this line to the point which
+minimises the distance from {@Code alabelpos} to the centre of the
+label.  Only @Code ylabelctr has @Code "yes" for its default value; the
+@Code y label often looks better centred when this adjustment is made,
+particularly on lines with shallow but non-zero slope:
+@CD @Tab
+    @Fmta { @Col @CC A ! @Col ! @Col @CC B }
+{
+@Rowa
+    A { @Code "ylabelctr { no }" }
+    B { @Code "ylabelctr { yes }" }
+@Rowa
+@Rowa
+@Rowa
+    A { @Diag ylabelctr { no } {
+        A:: @Square //0.5c &3c B:: @Square
+        //
+        @Link from { A } to { B } ylabel { @I { ylabel } }
+      } }
+    B { @Diag ylabelctr { yes } {
+        A:: @Square //0.5c &3c B:: @Square
+        //
+        @Link from { A } to { B } ylabel { @I { ylabel } }
+      } }
+}
+since it is then the centre of the label which is centred on the link,
+rather than one of its corners.
+@PP
+Finally, when all else fails there is an {@Code alabeladjust} option
+which translates the label by an arbitrary amount:
+@ID @Code "alabeladjust { -0.5c 1.5c }"
+causes the label to appear 0.5 centimetres to the left of and 1.5 centimetres
+above the point where it otherwise would have done.
+@End @Section
diff --git a/doc/user/dia_link b/doc/user/dia_link
new file mode 100644
index 0000000..b71f9d5
--- /dev/null
+++ b/doc/user/dia_link
@@ -0,0 +1,261 @@
+@Section
+    @Tag { dia_link }
+    @Title { Links }
+@Begin
+@PP
+@Code "@Diag" has one basic symbol for creating links, called
+link. @Index { @Code "@Link" symbol from @Code "@Diag" }
+{@Code "@Link"}.  It draws a link between two points or nodes
+given by {@Code from} and {@Code to} options, along a path
+given by a {@Code path} option:
+@ID @Code {
+"@Link"
+"    path { ... }"
+"    from { ... }"
+"    to { ... }"
+}
+Unlike {@Code "@Node"}, {@Code "@Link"} has no following object.
+@PP
+The @Code "path" option may be used to produce a link of any shape, as
+Section {@NumberOf dia_defi} explains.  There are also values
+that produce standard paths.  These are listed in full in the summary
+(Section {@NumberOf dia_summ}); here is a sample:
+@ID @Tab
+    @Fmta { @Col @Code { path "{" A "}" } ! @Col ! @Col B }
+{
+
+@Rowa
+    A { line }
+    B {
+@Diag {
+A:: @Circle //1c ||2c B:: @Circle
+// @Link from { A } to { B } path { line } arrow { yes }
+}
+}
+
+@Rowa
+    A { acurve }
+    B {
+@Diag {
+A:: @Circle //1c ||2c B:: @Circle
+// @Link from { A } to { B } path { acurve } arrow { yes }
+}
+}
+
+@Rowa
+    A { ccurve }
+    B {
+@Diag {
+A:: @Circle //1c ||2c B:: @Circle
+// @Link from { A } to { B } path { ccurve } arrow { yes }
+}
+}
+
+@Rowa
+    A { rvlcurve }
+    B {
+@Diag {
+A:: @Circle //1c ||2c B:: @Circle
+// @Link from { A } to { B } path { rvlcurve } arrow { yes }
+}
+}
+
+}
+The name of the last one is a reminder that it goes right, then vertically,
+then left, with curved corners.  The @Code acurve and @Code ccurve values
+produce circular arcs, anticlockwise and clockwise respectively, lying on
+the circle passing through the endpoints, or through the centres of the
+endpoints when they are tags denoting nodes.  There is also @Code "curve"
+which is an abbreviation for {@Code "acurve"}.  All these standard paths
+are defined in a way that makes sense no matter where the two nodes are
+relative to each other, except that no promise of a sensible result is
+made for two nodes very close together.
+@PP
+@Code "@Link" has two options, @Code bias and {@Code radius}, that may be
+used to fine-tune the path.  The @Code "bias" option determines the
+maximum distance that a curve is permitted to stray:
+@CD @Tab
+    @Fmta { @Col A ! @Col ! @Col B }
+{
+
+@Rowa
+
+    A { @Diag vstrut { no } margin { 0.5c } {
+A:: @Circle //1.5c ||2c B:: @Circle
+//
+LA:: @Line pathstyle { cdashed } from { A } to { B }
+LB:: @Curve from { A } to { B }
+@Line arrow { both } from { LA@LMID } to { LB@LMID }
+    ylabel { @I bias } # ylabeladjust { 0.15c 0 }
+} }
+
+    B { @Diag vstrut { no } margin { 0.5c } {
+A:: @Circle //1.5c ||2c B:: @Circle
+//
+LA:: @RVLCurve from { A } to { B }
+LB:: @Line pathstyle { cdashed } from { B@E } to { B@E ++ {0 2.5c} }
+@Line arrow { both } from { LB@LMID } to { LA@LMID }
+     ylabel { @I bias } ylabeladjust { 0 0.05c }
+} }
+
+}
+The @Code radius option does @I not apply to @Code acurve and
+{@Code ccurve}; rather, it determines the radius of the arcs at
+the corners of @Code rvlcurve and its kin.  A very large radius will be
+reduced to the largest reasonable value, which provides a way to get
+a semicircle at the right in an {@Code rvlcurve}.
+@PP
+Lout has no idea where the path is wandering, and cannot take it into
+account when placing a diagram on the page:
+@ID {
+@Code {
+"@Link"
+"    path { ccurve }"
+"    bias { 2c }"
+}
+||7ct
+@Diag vstrut { no } {
+A:: @Circle &3c B:: @Circle
+//
+@Link path { ccurve } bias { 2c } from { A } to { B }
+}
+}
+In such cases you have to arrange for the extra space yourself, by adding
+an extra paragraph symbol, blank row or column in a table, or whatever.
+@PP
+As with the options of {@Code "@Node"}, the options of {@Code "@Link"}
+may all be given to {@Code "@Diag"} as well, where they apply to every
+link in the diagram, unless overridden in the usual way.  They also appear
+in the setup file, where they apply to every link in every diagram of the
+document, unless overridden.
+@PP
+There are {@Code pathstyle}, {@Code pathdashlength} and {@Code pathwidth}
+options which affect the appearance of the path in the same way as the
+{@Code outlinestyle}, {@Code outlinedashlength} and {@Code outlinewidth}
+options of {@Code "@Node"} affect the outline.  When {@Code pathstyle}
+contains just one value (as opposed to a sequence of values) @Code "@Diag"
+tries to divide the path into fewer segments than it would otherwise, to
+make dashed and dotted paths look as good as possible.  There is also
+a {@Code pathgap} option which affects only @Code doubleline paths; it
+determines the gap between the centres of the two lines.
+@PP
+The @Code "@Link" symbol has an @Code arrow option, which adds an
+arrow. @Index { arrows }
+arrowhead to the end of the link:
+@ID {
+@Code {
+"@Link"
+"    arrow { yes }"
+}
+||7ct
+@Diag {
+1c @High 3c @Wide
+//
+@Link
+    from { 0,0 }
+    to { 1,1 }
+    arrow { yes }
+}
+}
+Its value may be {@Code no} (the default), {@Code yes}, {@Code forward}
+(which is the same as {@Code yes}), {@Code back}, or {@Code both}:
+@ID {
+@Code {
+"@Link"
+"    arrow { both }"
+}
+||7ct
+@Diag {
+1c @High 3c @Wide
+//
+@Link
+    from { 0,0 }
+    to { 1,1 }
+    arrow { both }
+}
+}
+@Code "@Link" has three options for controlling the appearance of
+arrowheads:  {@Code arrowstyle}, {@Code arrowwidth}, and
+{@Code arrowlength}.  Although every link symbol has these options, for
+consistency it is almost always better to set the corresponding options
+to the @Code "@Diag" symbol, which applies them to every arrow in the
+diagram:
+@ID @Code {
+"@Diag"
+"    arrowstyle { solid }"
+"    arrowwidth { 0.3f }"
+"    arrowlength { 0.5f }"
+"{"
+"    ..."
+"}"
+}
+This shows the default values:  a solid arrowhead like the ones above,
+@Code "0.3f" wide (across) and @Code "0.5f" long.  The @Code "arrowwidth"
+and @Code "arrowlength" options may be any length; it may be necessary to
+decrease @Code "arrowwidth" when many arrows enter one node.  The full list
+of possible values for @Code "arrowstyle" is
+@ID @Tab
+    @Fmta { @Col @Code { "arrowstyle {" A "}" } ! @Col B  }
+    vmargin { 1.0vx }
+{
+@Rowa
+    A { solid }
+    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
+	// @Link from { A } to { B } arrow { yes } arrowstyle { solid } } }
+@Rowa
+    A { halfopen }
+    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
+	// @Link from { A } to { B } arrow { yes } arrowstyle { halfopen } } }
+@Rowa
+    A { open }
+    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
+	// @Link from { A } to { B } arrow { yes } arrowstyle { open } } }
+@Rowa
+    A { curvedsolid }
+    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
+	// @Link from { A } to { B } arrow { yes } arrowstyle { curvedsolid } } }
+@Rowa
+    A { curvedhalfopen }
+    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
+	// @Link from { A } to { B } arrow { yes } arrowstyle { curvedhalfopen } } }
+@Rowa
+    A { curvedopen }
+    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
+	// @Link from { A } to { B } arrow { yes } arrowstyle { curvedopen } } }
+@Rowa
+    A { circle }
+    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
+	// @Link from { A } to { B } arrow { yes } arrowstyle { circle } } }
+@Rowa
+    A { box }
+    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
+	// @Link from { A } to { B } arrow { yes } arrowstyle { box } } }
+}
+The reader is invited to admire the beautifully sharp points on these
+arrowheads.
+@FootNote {
+The outlines of all nodes and arrowheads are drawn on the inside of the
+geometrical curve defining them, not centred over the curve as is common in
+PostScript documents.  Hence, the arrowheads and node outlines intersect at
+a true geometrical point; they do not overlap by one line width.  Furthermore,
+the standard link paths terminate at the base of the arrowhead, not at
+the point; the arrowhead itself is responsible for continuing the link
+path, at the appropriate width (although never dashed or dotted), from its
+base to its point, and hence can and does ensure that the link path does
+not overstrike and thicken the point of the arrow.
+}
+@PP
+It is possible to place an arbitrary object at the beginning or
+end of a link, using the @Code "fromlabel" and @Code "tolabel" options
+of Section {@NumberOf dia_labe}.
+@PP
+To save time in common cases, @Code "@Diag" provides link symbols,
+each of which is just @Code "@Link" with one of the standard paths
+already set:  {@Code "@Line"}, {@Code "@Curve"}, {@Code "@CCurve"},
+{@Code "@RVLCurve"}, and so on.  There are also symbols in which
+the @Code "arrow" option is set to @Code yes in addition:  {@Code "@Arrow"},
+{@Code "@CurveArrow"}, {@Code "@CCurveArrow"}, {@Code "@RVLCurveArrow"},
+and so on.  See the summary (Section {@NumberOf dia_summ}) for the
+full list of these symbols.  You will still need the @Code "arrow" option
+to get backward arrows and double-ended arrows.
+@End @Section
diff --git a/doc/user/dia_node b/doc/user/dia_node
new file mode 100644
index 0000000..b72c6e2
--- /dev/null
+++ b/doc/user/dia_node
@@ -0,0 +1,512 @@
+@Section
+    @Tag { dia_node }
+    @Title { Nodes }
+@Begin
+@PP
+@Code "@Diag" has one basic symbol for creating nodes.  It is called
+node. @Index { @Code "@Node" }
+{@Code "@Node"}, and it takes the following object and encloses it in an
+outline whose shape is determined by the {@Code "outline"} option:
+@ID {
+@Code {
+"@Node"
+"    outline { curvebox }"
+"{ Hello, world }"
+}
+||7ct
+@Diag {
+@Node
+    outline { curvebox }
+{ Hello, world }
+}
+}
+As Section {@NumberOf dia_defi} explains, the @Code outline option may be
+used to produce an outline of any shape.  There are also nine values that
+produce standard shapes:  {@Code box}, {@Code curvebox}, {@Code shadowbox},
+{@Code square}, {@Code diamond}, {@Code polygon}, {@Code isosceles},
+{@Code ellipse}, and {@Code circle}.
+@PP
+The shape of the outline is determined by the @Code outline option, but
+its size and position depend on the size and position of its
+{@I base}:  the following object with a small margin around it.  For
+example, this is how a circle is positioned over its base (shown in
+grey):
+@ID @OneRow {
+@Code {
+"@Node"
+"    outline { circle }"
+"{ Hello, world }"
+}
+||7ct
+@Diag {
+@Box paint { lightgrey } outlinestyle { noline } margin { 0c }
+@Node
+    outline { circle }
+{ Hello, world }
+}
+}
+Lout works only with the base, having no idea where the outline is, which
+explains why this circle is too high for the space allowed
+it.  Section {@NumberOf dia_summ} shows how each of the standard
+outlines is positioned over its base.
+@PP
+The @Code "@Node" symbol has many options, but all of them without
+exception share the following very useful property:  they may be given
+to the @Code "@Diag" symbol as well, where they apply to every node in
+the diagram:
+@ID @OneRow {
+@Code {
+"@Diag"
+"    outline { circle }"
+"{"
+"    @Node @I a"
+"    @DP"
+"    @Node @I b"
+"}"
+}
+||7ct
+@Diag
+    outline { circle }
+{
+    @Node @I a
+    @DP
+    @Node @I b
+}
+}
+These options also appear in the setup file ({@Code diag});
+if set there, they apply to every node in every diagram of the
+document.  As the number of nodes increases, it becomes very tedious and
+error-prone to duplicate options at all the nodes.  Giving each option
+just once, at the @Code "@Diag" symbol or in the setup file, saves time
+and makes it easy to change all the nodes into squares or any other shape
+later on.  Any setup file option may be overridden in a diagram by
+giving the option to its @Code "@Diag" symbol; any @Code "@Diag" option
+or setup file option may be overridden at any node by giving the option
+again there.
+@PP
+To save time in simple cases, @Code "@Diag" provides nine other
+node symbols called
+{@Code "@Box"},
+box.fig @Index { @Code "@Box" in @Code "@Diag" }
+{@Code "@CurveBox"},
+curvebox.fig @Index { @Code "@CurveBox" in @Code "@Diag" }
+{@Code "@ShadowBox"},
+shadowbox.fig @Index { @Code "@ShadowBox" in @Code "@Diag" }
+{@Code "@Square"},
+square. @Index @Code "@Square"
+{@Code "@Diamond"},
+diamond. @Index @Code "@Diamond"
+{@Code "@Polygon"},
+{@Code "@Isosceles"},
+isosceles. @Index @Code "@Isosceles"
+{@Code "@Ellipse"},
+ellipse. @Index @Code "@Ellipse"
+and {@Code "@Circle"}.  These are just abbreviations for @Code "@Node"
+with the appropriate value of {@Code outline}, nothing more.  They take
+the same options as {@Code "@Node"} (except that @Code outline is
+already fixed), and everything works in the same way.
+@PP
+There is a @Code shadow option which determines the depth of the shadow
+in shadow boxes:
+@ID {
+@Code {
+"@Node"
+"    outline { shadowbox }"
+"    shadow { 0.4f }"
+"{ WARNING }"
+}
+||7ct
+@Diag {
+@Node
+    outline { shadowbox }
+    shadow { 0.4f }
+{ WARNING }
+}
+}
+This example shows the default value, 0.4 times the current font
+size.  For polygons there is a @Code sides option for specifying the number
+polygon. @Index @Code "@Polygon"
+of sides, and an @Code angle option for rotating the outline:
+@IL
+@LI {
+@Code {
+"@Polygon"
+"   sides { 5 }"
+}
+||7ct
+@Diag {
+@Polygon
+   sides { 5 }
+{ 1c @High 1c @Wide }
+}
+}
+
+@LI {
+@Code {
+"@Polygon"
+"   sides { 5 }"
+"   angle { 0d }"
+}
+||7ct
+@Diag {
+@Polygon
+   sides { 5 }
+   angle { 0d }
+{ 1c @High 1c @Wide }
+}
+}
+@EL
+Setting @Code angle to @Code 0d causes the first vertex to be placed
+directly underneath the centre, and as the angle increases, the
+position of the first vertex rotates anticlockwise.  The defaults are
+3 sides and the angle that gives the polygon a
+horizontal base (i.e. 180 degrees divided by the number of sides).  Thus
+the two cases with symmetry about a vertical axis are obtained by the
+default angle and @Code "0d" respectively, which is convenient.  The
+{@Code "shadow"}, {@Code "sides"}, and {@Code "angle"} options may be
+given to any node, and also to {@Code "@Diag"} and in the setup file,
+where they apply to every node as usual.  However, they only affect the
+appearance of shadow boxes and polygons, respectively.
+@PP
+The {@Code outlinestyle}, {@Code outlinedashlength}, and {@Code outlinewidth}
+options apply to any node and affect the appearance of the outline:
+@ID @OneRow {
+@Code {
+"@CurveBox"
+"   outlinestyle { solid }"
+"   outlinedashlength { 0.2f }"
+"   outlinewidth { thin }"
+"{ Hello, world }"
+}
+||7ct
+@Diag {
+@CurveBox
+   outlinestyle { solid }
+   outlinedashlength { 0.2f }
+   outlinewidth { thin }
+{ Hello, world }
+}
+}
+This example shows the default values of these options.  The
+{@Code outlinestyle} option may be {@Code solid}, {@Code dashed},
+dashed. @Index { dashed lines }
+dotted. @Index { dotted lines }
+{@Code cdashed}, {@Code dotted}, or {@Code noline}:
+@ID @OneRow {
+@Code {
+"@CurveBox"
+"   outlinestyle { cdashed }"
+"{ Hello, world }"
+}
+||7ct
+@Diag {
+@CurveBox
+   outlinestyle { cdashed }
+{ Hello, world }
+}
+}
+The @Code dashed option makes all dashes the same length, whereas
+@Code cdashed halves the length of the first and last dash on each segment,
+which usually looks better.  The length of dashes is {@Code outlinedashlength},
+and the distance between dashes or dots is at most {@Code outlinedashlength},
+reduced to make the dashes or dots fit evenly.  The @Code outlinewidth
+option determines the width of the line, dashes, or dots, and may be
+{@Code thin}, {@Code medium}, {@Code thick}, or any length.  The values
+used for {@Code thin}, {@Code medium}, and {@Code thick} are
+{@Code 0.04f}, {@Code 0.08f}, and {@Code 0.12f}.
+@PP
+The {@Code outlinestyle} option may contain a sequence of the values
+mentioned above, meaning that they are to be applied in turn to each
+segment of the outline:
+@ID @OneRow {
+@Code {
+"@CurveBox"
+"   outlinestyle { solid cdashed }"
+"{ Hello, world }"
+}
+||7ct
+@Diag {
+@CurveBox
+   outlinestyle { solid cdashed }
+{ Hello, world }
+}
+}
+If there are more segments than values, {@Code outlinestyle} cycles back
+to the first value again; this is why a single value is applied to all
+segments.  Section {@NumberOf dia_summ} shows how each of the
+standard shapes is divided into segments.
+@PP
+Nodes may be painted any of the colours listed in Section
+{@NumberOf colour}, using the @Code "paint" option:
+@ID @OneRow {
+@Code {
+"@Box"
+"   paint { grey }"
+"@Diamond"
+"   outlinestyle { noline }"
+"   paint { white }"
+"{ Hello, world }"
+}
+||7ct
+@Diag {
+@Box
+   paint { grey }
+@Diamond
+   outlinestyle { noline }
+   paint { white }
+{ Hello, world }
+}
+}
+In this example the object following @Code "@Box" is a diamond containing
+{@Code "Hello, world"}.  The default value of @Code "paint" is
+{@Code nopaint}, a special value (not a colour) meaning don't use any paint.
+@PP
+When painting it is important to know what order things are done in, because
+anything put down earlier will disappear under the paint.  This is why
+@Code nopaint and @Code white are different.  Painting is done first, then
+boundaries, and finally the following object.
+@PP
+Each node symbol has 
+@Code "font" and @Code "break" options which may be used to
+set the font and paragraph breaking style of the following object:
+@ID @OneRow {
+@Code {
+"@Box"
+"    font { Helvetica Base }"
+"    break { clines }"
+"{"
+"WARNING"
+"DANGEROUS"
+"PENGUINS"
+"}"
+}
+||7ct
+@Diag {
+@Box
+    font { Helvetica Base }
+    break { clines }
+{
+WARNING
+DANGEROUS
+PENGUINS
+}
+}
+}
+Both options have empty default values, which leave the font and break
+style unchanged.  There is also a @Code "format" option for making more
+radical changes to the appearance of the following object:
+@ID @OneRow {
+@Code {
+"@Box"
+"    format {"
+"        {0.8 1.5} @Scale @S @Body"
+"    }"
+"{"
+"Dangerous Penguins"
+"}"
+}
+||7ct
+@Diag {
+@Box
+    format { { 0.8 1.5 } @Scale @S @Body }
+{
+Dangerous Penguins
+}
+}
+}
+The result is the @Code "format" option with any @Code "@Body" symbol
+within it replaced by the following object.  These are very useful when
+attached to the @Code "@Diag" symbol:
+@ID @OneRow @Code {
+"@Diag"
+"    font { Helvetica Base }"
+"    break { clines }"
+"    format { { 0.8 1.5 } @Scale @S @Body }"
+"{"
+"    ..."
+"}"
+}
+since then they apply to every node, as usual, thereby eliminating
+a lot of tedious, error-prone duplication of formatting information
+at each node.
+@PP
+The @Code margin option determines the size of the margin added to
+the following object:
+@ID @OneRow {
+@Code {
+"@Box"
+"    margin { 0c }"
+"{ Hello, world }"
+}
+||7ct
+@Diag {
+@Box
+    margin { 0c }
+{ Hello, world }
+}
+}
+These margins are included in the node's base (described above), so a
+larger margin enlarges the base and hence the outline as well.  The
+default value of @Code margin is {@Code 0.6f} (six-tenths of the current
+font size), and so the margin will automatically increase when the font size
+does, for example in overhead transparencies.
+@PP
+The @Code margin option adds the same margin to all four sides.  For
+finer control, the @Code hmargin option determines the horizontal (left
+and right) margins only, overriding {@Code margin}.  Similarly, the
+@Code vmargin option determines the vertical (top and foot) margins.  There
+are also {@Code leftmargin}, {@Code rightmargin},
+{@Code topmargin}, and {@Code footmargin} options which override
+{@Code margin}, {@Code hmargin}, and {@Code vmargin}.
+@PP
+When nodes appear side by side, the {@Code valign} option is
+useful for controlling their vertical position with respect to each
+other.  For example,
+@ID @OneRow {
+@Code {
+"@Diag"
+"    valign { foot }"
+"{"
+"@Box font { 24p } Big"
+"@Box font { 8p } Small"
+"}"
+}
+||7ct
+@Diag
+    valign { foot }
+{
+@Box font { 24p } Big
+@Box font { 8p } Small
+}
+}
+causes the feet of the boxes to be aligned.  In this example it is
+applied to all nodes at once, but of course it can be applied
+to individual nodes as well.  The value of {@Code valign} can be a
+length, which means that the point of alignment is
+to be that far down from the top of the base (including margins); or
+it may be {@Code top}, {@Code ctr}, or {@Code foot}, meaning alignment
+through the top, centre (the default value), or foot.
+@PP
+The {@Code vsize} option specifies a particular
+height for a node (not including margins):
+@ID @OneRow {
+@Code {
+"@Diag"
+"    vsize { 2f }"
+"{"
+"@Box font { 24p } Big"
+"@Box font { 8p } Small"
+"}"
+}
+||7ct
+@Diag
+    vsize { 2f }
+{
+@Box font { 24p } Big
+@Box font { 8p } Small
+}
+}
+The font size used when calculating @Code vsize is not affected by
+the value of any @Code font option.  If the following object is too
+tall for the chosen height, Lout will print a warning message (`forced
+to enlarge {@Code "@High"}', probably) and enlarge the base.
+@PP
+There is a @Code vindent option which is effective only when @Code vsize
+is used.  It controls where in the vertical space the following object
+is to appear:
+@ID @OneRow {
+@Code {
+"@Diag"
+"    vsize { 3f }"
+"{"
+"@Box vindent { top } Top"
+"@Box Centre"
+"@Box vindent { foot } Foot"
+"}"
+}
+||7ct
+@Diag
+    vsize { 3f }
+    vindent { ctr }
+{
+@Box vindent { top } Top
+@Box Centre
+@Box vindent { foot } Foot
+}
+}
+The value may be {@Code top} for at the top, {@Code ctr} (the default
+value) for in the centre, {@Code foot} for at the foot, or a length,
+meaning that distance down from the top.  These values are the same as
+for the @Code valign option.
+@PP
+Small discrepancies in the size of nodes can be very annoying,
+particularly when the nodes appear side by side:
+@ID @OneRow {
+@Code {
+"@Diag"
+"{"
+"@Box Hole @Box in"
+"@Box my @Box pocket"
+"}"
+}
+||7ct
+@Diag
+{
+@Box Hole @Box in
+@Box my @Box pocket
+}
+}
+These are caused by the slightly different heights of the objects within
+the nodes.  Selecting a fixed vertical size for all nodes goes some way
+towards solving this problem:
+@ID @OneRow {
+@Code {
+"@Diag"
+"    vsize { 1f }"
+"{"
+"@Box Hole @Box in"
+"@Box my @Box pocket"
+"}"
+}
+||7ct
+@Diag
+    vsize { 1f }
+{
+@Box Hole @Box in
+@Box my @Box pocket
+}
+}
+The size @Code "1f" is a good choice because most fonts are designed to
+be @Code "1f" high from the top of the tallest character to the foot of the
+deepest.  However, there is still a problem with the baselines of the words
+being misaligned.  A better solution is to insert a @I { vertical strut }
+into each node:  an invisible object with zero width and height equal to
+{@Code 1f}.  This is done using the @Code vstrut option:
+@ID @OneRow {
+@Code {
+"@Diag"
+"    vstrut { yes }"
+"{"
+"@Box Hole @Box in"
+"@Box my @Box pocket"
+"}"
+}
+||7ct
+@Diag
+    vstrut { yes }
+{
+@Box Hole @Box in
+@Box my @Box pocket
+}
+}
+The @Code vstrut option may be {@Code yes}, {@Code no} (the default value), or
+a length, meaning to insert a strut of this height.  So @Code "vstrut { yes }"
+is equivalent to {@Code "vstrut { 1.0f }"}.
+@PP
+There are {@Code halign}, {@Code hsize}, {@Code hindent}, and {@Code hstrut}
+options which work horizontally exactly as {@Code valign}, {@Code vsize},
+{@Code vindent}, and {@Code vstrut} work vertically, except that they
+use {@Code left} and {@Code right} where the vertical ones use
+{@Code top} and {@Code foot}.  The best way to fix horizontal size
+discrepancies is with {@Code hsize}, not {@Code hstrut}.
+@End @Section
diff --git a/doc/user/dia_posi b/doc/user/dia_posi
new file mode 100644
index 0000000..727d3be
--- /dev/null
+++ b/doc/user/dia_posi
@@ -0,0 +1,224 @@
+@Section
+    @Tag { dia_posi }
+    @Title { Positioning }
+@Begin
+@PP
+Once the nodes of the diagram are in place, @@Diag can be trusted to look
+after the rest:  links to standard outlines will terminate neatly on their
+boundaries, labels will not overstrike links no matter what direction they
+are heading, and so on.  The great weakness of @@Diag is in positioning
+the nodes.  This is partly because `what pleases the eye' is the
+positioning rule in many diagrams, and an interactive system is really
+needed in such cases; and partly because, even when the rule is more formal
+(for example, when the nodes are to be laid out in a grid), @@Diag does not
+have symbols to produce it anyway.
+@PP
+Previous examples have used @Code "@DP" for getting nodes one under
+another, and white space between nodes for getting them side by side, but
+this is very primitive.  This section suggests three better ways:  using
+{@Code "@Tbl"}, using {@Code "@Graph"}, and using coordinates; and the
+following section adds a fourth, using @@Diag's tree-drawing symbols.  It's
+a bit of a jumble.
+@PP
+The {@Code "@Tbl"} symbol (Chapter {@NumberOf tables}) is a good choice when
+the nodes have any kind of grid-like arrangement:
+@ID @OneRow {
+@Code {
+"@Diag {"
+"@Tbl"
+"    aformat { @Cell A | @Cell B | @Cell C }"
+"    marginhorizontal { 0.5c }"
+"    marginvertical { 0.25c }"
+"{"
+"@Rowa"
+"    B { A:: @Square }"
+"@Rowa"
+"    A { B:: @Square }"
+"    C { C:: @Square }"
+"@Rowa"
+"    B { D:: @Square }"
+"}"
+"//"
+"@Arrow from { A } to { B }"
+"@Arrow from { A } to { C }"
+"@Arrow from { B } to { D }"
+"@Arrow from { C } to { D }"
+"@Arrow from { A } to { D }"
+"}"
+}
+||9ct
+@Diag {
+@Tbl
+    aformat { @Cell A | @Cell B | @Cell C }
+    marginhorizontal { 0.5c }
+    marginvertical { 0.25c }
+{
+@Rowa
+    B { A:: @Square }
+@Rowa
+    A { B:: @Square }
+    C { C:: @Square }
+@Rowa
+    B { D:: @Square }
+}
+//
+@Arrow from { A } to { B }
+@Arrow from { A } to { C }
+@Arrow from { B } to { D }
+@Arrow from { C } to { D }
+@Arrow from { A } to { D }
+}
+}
+The table occupies the nodes part.  Tags may have the same name
+as columns; the two can never conflict.
+@PP
+Similarly, the @Code "@Graph" symbol from Chapter {@NumberOf graphs}
+has an @Code "objects" option which can place arbitrary objects,
+including labelled nodes, anywhere on a graph:
+@ID @OneRow {
+@Code {
+"@Diag {"
+"@Graph"
+"    xmin { 0 }"
+"    xmax { 100 }"
+"    ymin { 0 }"
+"    ymax { 100 }"
+"    objects {"
+"        @CTR at { 20 30 } { A:: @Square }"
+"        @CTR at { 60 70 } { B:: @Square }"
+"    }"
+"{}"
+"//"
+"@Link from { A } to { B }"
+"}"
+}
+||8.5ct
+@Diag {
+@Graph
+    xmin { 0 }
+    xmax { 100 }
+    ymin { 0 }
+    ymax { 100 }
+    objects {
+        @CTR at { 20 30 } { A:: @Square }
+        @CTR at { 60 70 } { B:: @Square }
+    }
+{}
+//
+@Link from { A } to { B }
+}
+}
+Once again the @Code "@Graph" symbol occupies the nodes part.  You can
+get rid of the axes by setting the @Code "style" option of @Code "@Graph"
+to {@Code none}, and then it won't look like a graph at all.
+@PP
+@@Diag has a system of node positioning based on coordinates which is
+somewhat similar to the @Code "@Graph" one.  It is often the easiest way
+to scatter nodes about a diagram at random.  The first step is to create
+a nodes part that is just an empty space of whatever size you want the
+final diagram to be:
+@ID @OneRow @Code {
+"@Diag {"
+"    4c @High 6c @Wide"
+"    //"
+"    ..."
+"}"
+}
+As shown, this is done with the @Code "@Wide" and @Code "@High" symbols
+from basic Lout; the above diagram will be four centimetres high by
+six centimetres wide.
+@PP
+@@Diag has a @Code "," symbol that allows you to specify a point by
+its coordinates in the diagram's base.  For example,
+@Code "0,0" denotes the bottom left-hand corner of the base,
+@Code "1,0" denotes the bottom right-hand corner, and
+@Code "0.5,0.5" denotes the centre of the base.  Coordinates should
+usually be between 0 and 1, since otherwise they denote points
+outside the base (which is allowed but seldom useful).
+@PP
+Every node symbol has a @Code "translate" option which allows you
+to move the node about on the diagram's base (or off it if you use
+coordinates less than 0 or greater than 1).  If you use this option,
+the node effectively has zero size and overstrikes anything else
+in the area you put it (like labels do).  It is best to put these
+nodes in the links part:
+@ID @OneRow {
+@Code {
+"@Diag {"
+"@Box margin { 0c } 4c @Wide 5c @High"
+"//"
+"A:: @Square"
+"      translate { CTR to 0.5, 0.67 }"
+"    { @I A }"
+"B:: @Circle"
+"      translate { CTR to 0.8, 0.25 }"
+"    { @I B }"
+"}"
+}
+||9ct
+@Diag {
+@Box margin { 0c } 4c @Wide 5c @High
+//
+A:: @Square
+      translate { CTR to 0.5, 0.67 }
+    { @I A }
+B:: @Circle
+      translate { CTR to 0.8, 0.25 }
+    { @I B }
+}
+}
+A box with margin zero has been drawn around the empty space to
+show its extent.  The value of @Code "translate" should always
+be {@I point} @Code to {@I point}; the first point lies within
+the node, the second lies within the nodes part, and the translation
+makes these two points coincide.
+@PP
+You are free to have nodes in the nodes part as well, or any object
+at all.  Here is an example which shows what a little ingenuity
+can accomplish:
+@ID @OneRow {
+@Code {
+"@Diag {"
+"@Polygon"
+"    sides { 5 }"
+"    outlinestyle { noline }"
+"    hsize { 4c }"
+"    vsize { 4c }"
+"//"
+"A:: @Circle translate { N to P1 } {}"
+"B:: @Circle translate { N to P2 } {}"
+"C:: @Circle translate { N to P3 } {}"
+"D:: @Circle translate { N to P4 } {}"
+"E:: @Circle translate { N to P5 } {}"
+"@Link arrow { both } from { A } to { B }"
+"@Link arrow { both } from { B } to { C }"
+"@Link arrow { both } from { C } to { D }"
+"@Link arrow { both } from { D } to { E }"
+"@Link arrow { both } from { E } to { A }"
+"}"
+}
+||9ct
+@Diag {
+@Polygon
+    sides { 5 }
+    outlinestyle { noline }
+    hsize { 4c }
+    vsize { 4c }
+//
+A:: @Circle translate { N to P1 } {}
+B:: @Circle translate { N to P2 } {}
+C:: @Circle translate { N to P3 } {}
+D:: @Circle translate { N to P4 } {}
+E:: @Circle translate { N to P5 } {}
+@Link arrow { both } from { A } to { B }
+@Link arrow { both } from { B } to { C }
+@Link arrow { both } from { C } to { D }
+@Link arrow { both } from { D } to { E }
+@Link arrow { both } from { E } to { A }
+}
+}
+This uses the tags of a phantom polygon to position the
+real nodes.  It would be a rare interactive system that could
+position nodes with this precision; @@Diag shines whenever there
+is a formal positioning rule to follow.
+@End @Section
diff --git a/doc/user/dia_summ b/doc/user/dia_summ
new file mode 100644
index 0000000..b9dc9e9
--- /dev/null
+++ b/doc/user/dia_summ
@@ -0,0 +1,1680 @@
+@Section
+    @Tag { dia_summ }
+    @Title { Summary }
+@Begin
+@PP
+Here is the complete list of standard node outlines that may be given
+to the @Code "@Node" symbol.  Each shows the outline name, any extra
+options relevant to this outline, base (shown as a grey
+box), segments (shown using {@Code "outlinestyle { solid dashed }"}),
+tags, and directions (shown as a thick arrowhead wherever defined):
+@IndentedList gap { 3v }
+
+@LI {
+@Code {
+"@Node"
+"    outline { box }"
+}
+||7ct
+@Diag {
+//0.5f
+@Box paint { lightgrey } outlinestyle { noline } margin { 0c }
+@ShowTags @ShowDirections @Node
+    outline { box }
+    outlinestyle { solid dashed }
+    outlinewidth { 0.03f }
+    vsize { 1.0c } hsize { 2.0c }
+}
+}
+
+@LI {
+@Code {
+"@Node"
+"    outline { curvebox }"
+}
+||7ct
+@Diag {
+@Box paint { lightgrey } outlinestyle { noline } margin { 0c }
+@ShowTags @ShowDirections @Node
+    outline { curvebox }
+    outlinestyle { solid dashed }
+    outlinewidth { 0.03f }
+    vsize { 1.0c } hsize { 2.0c }
+}
+}
+
+@LI {
+@Code {
+"@Node"
+"    outline { shadowbox }"
+"    shadow { 0.4f }"
+}
+||7ct
+@Diag {
+@Box paint { lightgrey } outlinestyle { noline } margin { 0c }
+@ShowTags @ShowDirections @Node
+    outline { shadowbox }
+    outlinestyle { solid dashed }
+    outlinewidth { 0.03f }
+    vsize { 1.0c } hsize { 2.0c }
+}
+}
+
+@LI {
+@Code {
+"@Node"
+"    outline { square }"
+}
+||7ct
+@Diag {
+//1.5f
+@Box paint { lightgrey } outlinestyle { noline } margin { 0c }
+@ShowTags @ShowDirections @Node
+    outline { square }
+    outlinestyle { solid dashed }
+    outlinewidth { 0.03f }
+    vsize { 1.0c } hsize { 2.0c }
+}
+}
+
+@LI {
+@Code {
+"@Node"
+"    outline { diamond }"
+}
+||7ct
+@Diag {
+@Box paint { lightgrey } outlinestyle { noline } margin { 0c }
+@ShowTags @ShowDirections @Node
+    outline { diamond }
+    outlinestyle { solid dashed }
+    outlinewidth { 0.03f }
+    vsize { 1.0c } hsize { 2.0c }
+}
+}
+
+@LI {
+@Code {
+"@Node"
+"    outline { polygon }"
+"    sides { 3 }"
+"    angle { 180d / sides }"
+}
+||7ct
+@Diag {
+//0.5f
+@Box paint { lightgrey } outlinestyle { noline } margin { 0c }
+@ShowTags @ShowDirections @Node
+    outline { polygon }
+    outlinestyle { solid dashed }
+    outlinewidth { 0.03f }
+    vsize { 1.0c } hsize { 2.0c }
+&0.5c ... &0.5c
+@Box paint { lightgrey } outlinestyle { noline } margin { 0c }
+@ShowTags @ShowDirections @Node
+    outline { polygon }
+    sides { 10 }
+    outlinestyle { solid dashed }
+    outlinewidth { 0.03f }
+    vsize { 1.0c } hsize { 2.0c }
+&0.5c ...
+}
+}
+
+@LI {
+@Code {
+"@Node"
+"    outline { isosceles }"
+}
+||7ct
+@Diag {
+@Box paint { lightgrey } outlinestyle { noline } margin { 0c }
+@ShowTags @ShowDirections @Node
+    outline { isosceles }
+    outlinestyle { solid dashed }
+    outlinewidth { 0.03f }
+    vsize { 1.0c } hsize { 2.0c }
+}
+}
+
+@LI {
+@Code {
+"@Node"
+"    outline { ellipse }"
+}
+||7ct
+@Diag {
+@Box paint { lightgrey } outlinestyle { noline } margin { 0c }
+@ShowTags @ShowDirections @Node
+    outline { ellipse }
+    outlinestyle { solid dashed }
+    outlinewidth { 0.03f }
+    vsize { 1.0c } hsize { 2.0c }
+}
+}
+
+@LI {
+@Code {
+"@Node"
+"    outline { circle }"
+}
+||7ct
+@Diag {
+@Box paint { lightgrey } outlinestyle { noline } margin { 0c }
+@ShowTags @ShowDirections @Node
+    outline { circle }
+    outlinestyle { solid dashed }
+    outlinewidth { 0.03f }
+    vsize { 1.0c } hsize { 2.0c }
+}
+}
+
+@EndList
+@DP
+Here are the abbreviations for the standard shapes:
+@ID @Tab
+    vmargin { 0.5vx }
+    @Fmta { @Col @Code { outline "{" A "}" } ! @Col @Code { "@"B } }
+{
+@Rowa
+    A { box }
+    B { Box }
+@Rowa
+    A { curvebox }
+    B { CurveBox }
+@Rowa
+    A { shadowbox }
+    B { ShadowBox }
+@Rowa
+    A { square }
+    B { Square }
+@Rowa
+    A { diamond }
+    B { Diamond }
+@Rowa
+    A { polygon }
+    B { Polygon }
+@Rowa
+    A { isosceles }
+    B { Isosceles }
+@Rowa
+    A { ellipse }
+    B { Ellipse }
+@Rowa
+    A { circle }
+    B { Circle }
+}
+Here are all the options to the @Code "@Node" symbol, their default
+values, and their ranges of allowed values.  Definitions of {@I number},
+{@I length}, {@I angle}, and {@I point} appear later in this summary.  The
+options related to {@Code alabel}, {@Code blabel}, {@Code clabel}, and
+{@Code dlabel} have mostly been omitted since they are the same as
+the {@Code nodelabel} options except for {@Code nodelabelpos}.
+@DP
+1fx @Break @Tab
+  hmargin { 1s }
+  # vmargin { 0.6vx }
+  @Fmth { @Col @Code A ! @Col @Code " " ! @Col @Code B ! @Col @Code " " !
+	  @Col 1.0c @Wide ! @Col C }
+  @Fmta { @Col @Code A ! @Col @Code "{" ! @Col @Code B ! @Col @Code "}" !
+	  @Col 1.0c @Wide ! @Col C }
+{
+@FirstRowh
+  A { "@Node" }
+@Rowa
+  A { "   outline" }
+  B { box }
+  C { {@Code box}, {@Code curvebox}, {@Code shadowbox}, {@Code square},
+{@Code diamond}, {@Code polygon}, {@Code ellipse}, {@Code circle}, or
+any outline }
+@Rowa
+  A { "   margin"    }
+  B { 0.6f }
+  C { any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   shadow"    }
+  B { 0.4f }
+  C { any @I length }
+@Rowa
+  A { "   sides"    }
+  B { 3 }
+  C { any @I number (it will be rounded to the nearest integer) }
+@Rowa
+  A { "   angle"    }
+  B { 180d "/" sides }
+  C { any @I angle }
+@Rowa
+  A { "   translate"    }
+  B { }
+  C { empty, or @I point @Code to @I point }
+@Rowa
+  A { "   outlinestyle" }
+  B { solid }
+  C { {@Code solid}, {@Code dashed}, {@Code cdashed}, {@Code dotted},
+{@Code noline}, or any sequence of one or more of these values }
+@Rowa
+  A { "   outlinedashlength"}
+  B { 0.2f }
+  C { any @I length }
+@Rowa
+  A { "   outlinewidth" }
+  B { thin }
+  C { {@Code thin}, {@Code medium}, {@Code thick}, or any @I length }
+@Rowa
+  A { "   paint"     }
+  B { nopaint }
+  C { @Code nopaint or any colour from Section {@NumberOf colour} }
+@Rowa
+  A { "   font"     }
+  B { }
+  C { any value suitable for the @Code "@Font" symbol }
+@Rowa
+  A { "   break"     }
+  B { }
+  C { any value suitable for the @Code "@Break" symbol }
+@Rowa
+  A { "   format"     }
+  B { "@Body" }
+  C { any object, usually containing {@Code "@Body"} }
+@Rowa
+  A { "   valign"}
+  B { ctr }
+  C { {@Code "top"}, {@Code "ctr"}, {@Code "foot"}, or any length
+from Section {@NumberOf objects} }
+@Rowa
+  A { "   vsize"}
+  B { }
+  C { empty, or any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   vindent"}
+  B { ctr }
+  C { {@Code "top"}, {@Code "ctr"}, {@Code "mctr"}, {@Code "foot"}, or any
+length from Section {@NumberOf objects} }
+@Rowa
+  A { "   vstrut"}
+  B { no }
+  C { {@Code no}, {@Code yes}, or any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   vmargin"    }
+  B { margin }
+  C { any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   topmargin"    }
+  B { vmargin }
+  C { any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   footmargin"    }
+  B { vmargin }
+  C { any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   halign"}
+  B { ctr }
+  C { {@Code "left"}, {@Code "ctr"}, {@Code "right"}, or any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   hsize"}
+  B { }
+  C { empty, or any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   hindent"}
+  B { ctr }
+  C { {@Code "left"}, {@Code "ctr"}, {@Code "mctr"}, {@Code "right"}, or any
+length from Section {@NumberOf objects} }
+@Rowa
+  A { "   hmargin"    }
+  B { margin }
+  C { any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   leftmargin"    }
+  B { hmargin }
+  C { any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   rightmargin"    }
+  B { hmargin }
+  C { any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   hstrut"}
+  B { no }
+  C { {@Code no}, {@Code yes}, or any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   nodelabel"}
+  B {  }
+  C { any object }
+@Rowa
+  A { "   nodelabelmargin"}
+  B { 0.2f }
+  C { any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   nodelabelfont"}
+  B { -2p }
+  C { any value suitable for the @Code "@Font" symbol }
+@Rowa
+  A { "   nodelabelbreak"}
+  B { ragged nohyphen }
+  C { any value suitable for the @Code "@Break" symbol }
+@Rowa
+  A { "   nodelabelformat"}
+  B { "@Body" }
+  C { any object, usually containing @Code "@Body" }
+@Rowa
+  A { "   nodelabelpos"}
+  B { }
+  C { any @I point }
+@Rowa
+  A { "   nodelabelangle"}
+  B { horizontal }
+  C { {@Code horizontal}, {@Code aligned}, or {@Code perpendicular};
+{@Code parallel}, {@Code antiparallel}, or any @I angle }
+@Rowa
+  A { "   nodelabelprox"}
+  B { outside }
+  C { {@Code above}, {@Code below}, {@Code left}, {@Code right},
+{@Code inside}, or {@Code outside}; {@Code CTR}, {@Code N}, {@Code S},
+{@Code E}, {@Code W}, {@Code NE}, {@Code NW}, {@Code SW}, or {@Code SE}
+}
+@Rowa
+  A { "   nodelabelctr"}
+  B { no }
+  C { @Code yes or @Code no }
+@Rowa
+  A { "   nodelabeladjust"}
+  B { 0 0 }
+  C { any @I point }
+@Rowa
+  A { "   alabelpos"}
+  B { NE }
+  C { any @I point }
+@Rowa
+  A { "   blabelpos"}
+  B { NW }
+  C { any @I point }
+@Rowa
+  A { "   clabelpos"}
+  B { SW }
+  C { any @I point }
+@Rowa
+  A { "   dlabelpos"}
+  B { SE }
+  C { any @I point }
+}
+@DP
+Here is the complete list of standard link paths that may be given
+to the @Code "@Link" symbol.  Each entry shows the link path name,
+any extra options relevant to this path, segments (shown using
+{@Code "outlinestyle { solid dashed }"}, and tags.  All tags
+have directions pointing along the link from @Code FROM to
+{@Code TO}; these have been omitted for clarity.  The @Code frompt
+and @Code topt options of @Code bezier are compulsory and denote the
+two control points (Section {@NumberOf dia_defi}).
+@IndentedList gap { 2v }
+
+@LI {
+@Code {
+"@Link"
+"    path { line }"
+}
+||6ct
+@Diag {
+//0.5f
+A:: @Circle /0.8c |1.5c B:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { line } from { A } to { B }
+}
+&2.5c
+#@Diag {
+#|1.5c B:: @Circle /0.8c A:: @Circle 
+#//
+#@ShowTags @Link
+#    pathstyle { solid dashed }
+#    path { line } from { A } to { B }
+#}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { doubleline }"
+}
+||6ct
+@Diag {
+//0.5f
+A:: @Circle /0.8c |1.5c B:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { doubleline } from { A } to { B }
+}
+&2.5c
+#@Diag {
+#|1.5c B:: @Circle /0.8c A:: @Circle 
+#//
+#@ShowTags @Link
+#    pathstyle { solid dashed }
+#    path { line } from { A } to { B }
+#}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { curve }"
+"    bias { 2.0f }"
+}
+||6ct
+@Diag {
+A:: @Circle /0.8c |1.5c B:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { curve } from { A } to { B }
+}
+&2.5c
+@Diag {
+|1.5c B:: @Circle /0.8c A:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { curve } from { A } to { B }
+}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { ccurve }"
+"    bias { 2.0f }"
+}
+||6ct
+@Diag {
+//0.5f
+A:: @Circle /0.8c |1.5c B:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { ccurve } from { A } to { B }
+}
+&2.5c
+@Diag {
+//0.5f
+|1.5c B:: @Circle /0.8c A:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { ccurve } from { A } to { B }
+}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { bezier }"
+"    frompt { A@CTR ++ { 3f 0 } }"
+"    topt { B@CTR ++ { 3f 0 } }"
+}
+||6ct
+@Diag {
+//0.5f
+A:: @Circle /0.8c |1.5c B:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { bezier } from { A } to { B }
+    frompt { A@CTR ++ { 3f 0 } }
+    topt { B@CTR ++ { 3f 0 } }
+}
+&2.5c
+@Diag {
+//0.5f
+|1.5c B:: @Circle /0.8c A:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { bezier } from { A } to { B }
+    frompt { A@CTR ++ { 3f 0 } }
+    topt { B@CTR ++ { 3f 0 } }
+}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { vhline }"
+}
+||6ct
+@Diag {
+//0.5f
+A:: @Circle /0.8c |1.5c B:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { vhline } from { A } to { B }
+}
+&2.5c
+@Diag {
+//0.5f
+|1.5c B:: @Circle /0.8c A:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { vhline } from { A } to { B }
+}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { hvline }"
+}
+||6ct
+@Diag {
+//0.5f
+A:: @Circle /0.8c |1.5c B:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { hvline } from { A } to { B }
+}
+&2.5c
+@Diag {
+//0.5f
+|1.5c B:: @Circle /0.8c A:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { hvline } from { A } to { B }
+}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { vhcurve }"
+"    radius { 1.0f }"
+}
+||6ct
+@Diag {
+//0.5f
+A:: @Circle /0.8c |1.5c B:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { vhcurve } from { A } to { B }
+}
+&2.5c
+@Diag {
+//0.5f
+|1.5c B:: @Circle /0.8c A:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { vhcurve } from { A } to { B }
+}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { hvcurve }"
+"    radius { 1.0f }"
+}
+||6ct
+@Diag {
+//0.5f
+A:: @Circle /0.8c |1.5c B:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { hvcurve } from { A } to { B }
+}
+&2.5c
+@Diag {
+//0.5f
+|1.5c B:: @Circle /0.8c A:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { hvcurve } from { A } to { B }
+}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { lvrline }"
+"    bias { 2.0f }"
+}
+||6ct
+@Diag {
+//0.5f
+A:: @Circle /0.8c |1.5c B:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { lvrline } from { A } to { B }
+}
+&2.5c
+@Diag {
+//0.5f
+|1.5c B:: @Circle /0.8c A:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { lvrline } from { A } to { B }
+}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { rvlline }"
+"    bias { 2.0f }"
+}
+||6ct
+@Diag {
+//0.5f
+A:: @Circle /0.8c |1.5c B:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { rvlline } from { A } to { B }
+}
+&2.5c
+@Diag {
+//0.5f
+|1.5c B:: @Circle /0.8c A:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { rvlline } from { A } to { B }
+}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { lvrcurve }"
+"    bias { 2.0f }"
+"    radius { 1.0f }"
+}
+||6ct
+@Diag {
+//0.5f
+A:: @Circle /0.8c |1.5c B:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { lvrcurve } from { A } to { B }
+}
+&2.5c
+@Diag {
+//0.5f
+|1.5c B:: @Circle /0.8c A:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { lvrcurve } from { A } to { B }
+}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { rvlcurve }"
+"    bias { 2.0f }"
+"    radius { 1.0f }"
+}
+||6ct
+@Diag {
+//0.5f
+A:: @Circle /0.8c |1.5c B:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { rvlcurve } from { A } to { B }
+}
+&2.5c
+@Diag {
+//0.5f
+|1.5c B:: @Circle /0.8c A:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { rvlcurve } from { A } to { B }
+}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { dwrapline }"
+"    tbias { 2.0f }"
+"    bias { 2.0f }"
+"    fbias { 2.0f }"
+}
+||6ct
+@Diag {
+//0.5f
+A:: @Circle /0.8c |1.5c B:: @Circle /2f
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { dwrapline } from { A } to { B }
+}
+&2.5c
+@Diag {
+//0.5f
+|1.5c B:: @Circle /0.8c A:: @Circle /2f
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { dwrapline } from { A } to { B }
+}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { uwrapline }"
+"    tbias { 2.0f }"
+"    bias { 2.0f }"
+"    fbias { 2.0f }"
+}
+||6ct
+@Diag {
+//0.5f
+/2f A:: @Circle /0.8c |1.5c B:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { uwrapline } from { A } to { B }
+}
+&2.5c
+@Diag {
+//0.5f
+/2f |1.5c B:: @Circle /0.8c A:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { uwrapline } from { A } to { B }
+}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { dwrapcurve }"
+"    tbias { 2.0f }"
+"    bias { 2.0f }"
+"    fbias { 2.0f }"
+"    radius { 1.0f }"
+}
+||6ct
+@Diag {
+//0.5f
+A:: @Circle /0.8c |1.5c B:: @Circle /2f
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { dwrapcurve } from { A } to { B }
+}
+&2.5c
+@Diag {
+//0.5f
+|1.5c B:: @Circle /0.8c A:: @Circle /2f
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { dwrapcurve } from { A } to { B }
+}
+}
+
+@LI {
+@Code {
+"@Link"
+"    path { uwrapcurve }"
+"    tbias { 2.0f }"
+"    bias { 2.0f }"
+"    fbias { 2.0f }"
+"    radius { 1.0f }"
+}
+||6ct
+@Diag {
+//0.5f
+/2f A:: @Circle /0.8c |1.5c B:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { uwrapcurve } from { A } to { B }
+}
+&2.5c
+@Diag {
+//0.5f
+/2f |1.5c B:: @Circle /0.8c A:: @Circle 
+//
+@ShowTags @Link
+    pathstyle { solid dashed }
+    path { uwrapcurve } from { A } to { B }
+}
+}
+
+@EndList
+Here is the list of abbreviations for the standard paths (note
+that @Code curve and @Code acurve are the same).  Each
+path also has an abbreviation which adds a forward arrow:
+@ID @Tab
+    @Fmta { @Col @Code { path "{" A "}" } ! @Col @Code "@"B ! @Col @Code "@"C }
+{
+@Rowa
+    A { line }
+    B { Line }
+    C { Arrow }
+@Rowa
+    A { doubleline }
+    B { DoubleLine }
+    C { DoubleArrow }
+@Rowa
+    A { curve }
+    B { Curve }
+    C { CurveArrow }
+@Rowa
+    A { acurve }
+    B { ACurve }
+    C { ACurveArrow }
+@Rowa
+    A { ccurve }
+    B { CCurve }
+    C { CCurveArrow }
+
+@Rowa
+    A { bezier }
+    B { Bezier }
+    C { BezierArrow }
+
+@Rowa
+    A { hvline }
+    B { HVLine }
+    C { HVArrow }
+@Rowa
+    A { vhline }
+    B { VHLine }
+    C { VHArrow }
+@Rowa
+    A { hvcurve }
+    B { HVCurve }
+    C { HVCurveArrow }
+@Rowa
+    A { vhcurve }
+    B { VHCurve }
+    C { VHCurveArrow }
+
+@Rowa
+    A { lvrline }
+    B { LVRLine }
+    C { LVRArrow }
+@Rowa
+    A { rvlline }
+    B { RVLLine }
+    C { RVLArrow }
+@Rowa
+    A { lvrcurve }
+    B { LVRCurve }
+    C { LVRCurveArrow }
+@Rowa
+    A { rvlcurve }
+    B { RVLCurve }
+    C { RVLCurveArrow }
+
+@Rowa
+    A { dwrapline }
+    B { DWrapLine }
+    C { DWrapArrow }
+@Rowa
+    A { uwrapline }
+    B { UWrapLine }
+    C { UWrapArrow }
+@Rowa
+    A { dwrapcurve }
+    B { DWrapCurve }
+    C { DWrapCurveArrow }
+@Rowa
+    A { uwrapcurve }
+    B { UWrapCurve }
+    C { UWrapCurveArrow }
+}
+Here is the complete list of options to the @Code "@Link" symbol.  The
+options related to {@Code xlabel}, {@Code ylabel}, and {@Code zlabel}
+have been omitted where they are the same as the {@Code linklabel} options.
+@DP
+1fx @Break @Tab
+  hmargin { 1s }
+  # vmargin { 0.6vx }
+  @Fmth { @Col @Code A ! @Col @Code " " ! @Col @Code B ! @Col @Code " " !
+	  @Col 1.0c @Wide ! @Col C }
+  @Fmta { @Col @Code A ! @Col @Code "{" ! @Col @Code B ! @Col @Code "}" !
+	  @Col 1.0c @Wide ! @Col C }
+{
+@Rowh
+  A { "@Link" }
+@Rowa
+  A { "   path" }
+  B { line }
+  C { {@Code "line"}, {@Code "doubleline"}, {@Code "curve"}, {@Code "acurve"},
+{@Code "ccurve"}, {@Code "bezier"},
+{@Code "vhline"}, {@Code "hvline"}, {@Code "vhcurve"}, {@Code "hvcurve"},
+{@Code "lvrline"}, {@Code "rvlline"}, {@Code "lvrcurve"}, {@Code "rvlcurve"},
+{@Code "dwrapline"}, {@Code "uwrapline"}, {@Code "dwrapcurve"},
+{@Code "uwrapcurve"}, or any path }
+@Rowa
+  A { "   from"}
+  B { 0,0 }
+  C { any @I point or node label }
+@Rowa
+  A { "   to"}
+  B { 1,1 }
+  C { any @I point or node label }
+@Rowa
+  A { "   bias"}
+  B { 2.0f }
+  C { any @I length }
+@Rowa
+  A { "   fbias"}
+  B { 2.0f }
+  C { any @I length }
+@Rowa
+  A { "   tbias"}
+  B { 2.0f }
+  C { any @I length }
+@Rowa
+  A { "   radius"}
+  B { 1.0f }
+  C { any @I length }
+@Rowa
+  A { "   xindent"}
+  B { 0.8f }
+  C { any @I length }
+@Rowa
+  A { "   zindent"}
+  B { 0.8f }
+  C { any @I length }
+@Rowa
+  A { "   frompt"}
+  B { 0 0 }
+  C { any @I point }
+@Rowa
+  A { "   topt"}
+  B { 0 0 }
+  C { any @I point }
+@Rowa
+  A { "   pathstyle" }
+  B { solid }
+  C { {@Code solid}, {@Code dashed}, {@Code cdashed}, {@Code dotted},
+{@Code noline}, or any sequence of one or more of these values }
+@Rowa
+  A { "   pathdashlength"}
+  B { 0.2f }
+  C { any @I length }
+@Rowa
+  A { "   pathwidth" }
+  B { thin }
+  C { {@Code thin}, {@Code medium}, {@Code thick}, or any @I length }
+@Rowa
+  A { "   pathgap" }
+  B { thin }
+  C { {@Code thin}, {@Code medium}, {@Code thick}, or any @I length }
+@Rowa
+  A { "   arrow"}
+  B { no }
+  C { {@Code no}, {@Code yes}, {@Code forward}, {@Code back},
+or {@Code both} }
+@Rowa
+  A { "   arrowstyle"}
+  B { solid }
+  C { {@Code solid}, {@Code halfopen}, {@Code open}, {@Code curvedsolid},
+{@Code curvedhalfopen}, or {@Code curvedopen} }
+@Rowa
+  A { "   arrowwidth"}
+  B { 0.3f }
+  C { any @I length }
+@Rowa
+  A { "   arrowlength"}
+  B { 0.5f }
+  C { any @I length }
+@Rowa
+  A { "   linklabel"}
+  B {  }
+  C { any object }
+@Rowa
+  A { "   linklabelmargin"}
+  B { 0.2f }
+  C { any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   linklabelfont"}
+  B { -2p }
+  C { any value suitable for the @Code "@Font" symbol }
+@Rowa
+  A { "   linklabelbreak"}
+  B { ragged nohyphen }
+  C { any value suitable for the @Code "@Break" symbol }
+@Rowa
+  A { "   linklabelformat"}
+  B { "@Body" }
+  C { any object, usually containing @Code "@Body" }
+@Rowa
+  A { "   linklabelpos"}
+  B { }
+  C { any @I point }
+@Rowa
+  A { "   linklabelangle"}
+  B { horizontal }
+  C { {@Code horizontal}, {@Code aligned}, or {@Code perpendicular};
+{@Code parallel}, {@Code antiparallel}, or any @I angle }
+@Rowa
+  A { "   linklabelprox"}
+  B { above }
+  C { {@Code above}, {@Code below}, {@Code left}, {@Code right},
+{@Code inside}, or {@Code outside}; {@Code CTR}, {@Code N}, {@Code S},
+{@Code E}, {@Code W}, {@Code NE}, {@Code NW}, {@Code SW}, or {@Code SE}
+}
+@Rowa
+  A { "   linklabelctr"}
+  B { no }
+  C { @Code yes or @Code no }
+@Rowa
+  A { "   linklabeladjust"}
+  B { 0 0 }
+  C { any @I point }
+@Rowa
+  A { "   xlabelpos"}
+  B { LFROM }
+  C { any @I point }
+@Rowa
+  A { "   ylabelpos"}
+  B { LMID }
+  C { any @I point }
+@Rowa
+  A { "   ylabelctr"}
+  B { yes }
+  C { @Code yes or @Code no }
+@Rowa
+  A { "   zlabelpos"}
+  B { LTO }
+  C { any @I point }
+@Rowa
+  A { "   fromlabel"}
+  B {  }
+  C { any object }
+@Rowa
+  A { "   fromlabelmargin"}
+  B { 0f }
+  C { any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   fromlabelfont"}
+  B {     }
+  C { Any value suitable for the @Code "@Font" symbol }
+@Rowa
+  A { "   fromlabelbreak"}
+  B { ragged nohyphen }
+  C { Any value suitable for the @Code "@Break" symbol }
+@Rowa
+  A { "   fromlabelformat"}
+  B { "@Body" }
+  C { any object, usually containing @Code "@Body" }
+@Rowa
+  A { "   fromlabelpos"}
+  B { FROM }
+  C { any @I point }
+@Rowa
+  A { "   fromlabelangle"}
+  B { antiparallel }
+  C { {@Code horizontal}, {@Code aligned}, or {@Code perpendicular};
+{@Code parallel}, {@Code antiparallel}, or any @I angle }
+@Rowa
+  A { "   fromlabelprox"}
+  B { W }
+  C { {@Code above}, {@Code below}, {@Code left}, {@Code right},
+{@Code inside}, or {@Code outside}; {@Code CTR}, {@Code N}, {@Code S},
+{@Code E}, {@Code W}, {@Code NE}, {@Code NW}, {@Code SW}, or {@Code SE}
+}
+@Rowa
+  A { "   fromlabelctr"}
+  B { no }
+  C { @Code yes or @Code no }
+@Rowa
+  A { "   fromlabeladjust"}
+  B { 0 0 }
+  C { any @I point }
+@Rowa
+  A { "   tolabel"}
+  B {  }
+  C { any object }
+@Rowa
+  A { "   tolabelmargin"}
+  B { 0f }
+  C { any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   tolabelfont"}
+  B {     }
+  C { Any value suitable for the @Code "@Font" symbol }
+@Rowa
+  A { "   tolabelbreak"}
+  B { ragged nohyphen }
+  C { Any value suitable for the @Code "@Break" symbol }
+@Rowa
+  A { "   tolabelformat"}
+  B { "@Body" }
+  C { any object, usually containing @Code "@Body" }
+@Rowa
+  A { "   tolabelpos"}
+  B { TO }
+  C { any @I point }
+@Rowa
+  A { "   tolabelangle"}
+  B { parallel }
+  C { {@Code horizontal}, {@Code aligned}, or {@Code perpendicular};
+{@Code parallel}, {@Code antiparallel}, or any @I angle }
+@Rowa
+  A { "   tolabelprox"}
+  B { W }
+  C { {@Code above}, {@Code below}, {@Code left}, {@Code right},
+{@Code inside}, or {@Code outside}; {@Code CTR}, {@Code N}, {@Code S},
+{@Code E}, {@Code W}, {@Code NE}, {@Code NW}, {@Code SW}, or {@Code SE}
+}
+@Rowa
+  A { "   tolabelctr"}
+  B { no }
+  C { @Code yes or @Code no }
+@Rowa
+  A { "   tolabeladjust"}
+  B { 0 0 }
+  C { any @I point }
+}
+@DP
+Here is the complete list of options to the @Code "@Tree" symbol:
+@DP @OneRow 1fx @Break @Tab
+  hmargin { 1s }
+  # vmargin { 0.6vx }
+  @Fmth { @Col @Code A ! @Col @Code " " ! @Col @Code B ! @Col @Code " " !
+	  @Col 1.0c @Wide ! @Col C }
+  @Fmta { @Col @Code A ! @Col @Code "{" ! @Col @Code B ! @Col @Code "}" !
+	  @Col 1.0c @Wide ! @Col C }
+{
+@Rowh
+  A { "@Tree" }
+@Rowa
+  A { "   treehindent" }
+  B { ctr }
+  C { {@Code left}, {@Code ctr}, {@Code right}, or any length from
+Section {@NumberOf objects} }
+}
+@DP
+The @Code "@HTree" option has a similar @Code "treevindent" option,
+which may be {@Code "top"}, {@Code ctr}, {@Code foot}, or any length
+from Section {@NumberOf objects}.
+@PP
+The @Code "@Diag" symbol and to the {@Code "@DiagSetup"} setup
+file symbol have all of the options of {@Code "@Node"}, {@Code "@Link"},
+{@Code "@Tree"}, and {@Code "@HTree"}.  They also have the following
+options:
+@DP
+1fx @Break @Tab
+  hmargin { 1s }
+  # vmargin { 0.6vx }
+  @Fmth { @Col @Code A ! @Col @Code " " ! @Col @Code B ! @Col @Code " " !
+	  @Col 1.0c @Wide ! @Col C }
+  @Fmta { @Col @Code A ! @Col @Code "{" ! @Col @Code B ! @Col @Code "}" !
+	  @Col 1.0c @Wide ! @Col C }
+{
+@Rowh
+  A { "@Diag" }
+@Rowa
+  A { "   maxlabels" }
+  B { 200 }
+  C { any whole number }
+@Rowa
+  A { "   save" }
+  B { no }
+  C { @Code no or @Code yes }
+@Rowa
+  A { "   treehsep" }
+  B { 0.5f }
+  C { any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   treevsep" }
+  B { 0.5f }
+  C { any length from Section {@NumberOf objects} }
+}
+@DP
+The following lists define all the ways to specify numbers, lengths,
+angles, points, and booleans.  Brief explanations appear to the right,
+with the symbols' precedences in parentheses.
+@DP
+1fx @Break @Tab
+  # vmargin { 0.6vx }
+  @Fmth { @Col { &@DisplayIndent     A } ! @Col   }
+  @Fmta { @Col { &@DisplayIndent &2s A } ! @Col B }
+{
+
+@Rowh A { @I number } vmargin { 0.2vx }
+@Rowh
+@Rowa
+  A { {@Sym minus}27.56 }
+  B { or any literal number }
+@Rowa
+  A { @Code sqrt @I number }
+  B { square root (99) }
+@Rowa
+  A { @Code abs @I number }
+  B { absolute value (99) }
+@Rowa
+  A { @Code ceiling @I number }
+  B { least integer greater than or equal to (99) }
+@Rowa
+  A { @Code floor @I number }
+  B { greatest integer less than or equal to (99) }
+@Rowa
+  A { @Code truncate @I number }
+  B { delete fractional part (99) }
+@Rowa
+  A { @Code round @I number }
+  B { round to nearest integer (99) }
+@Rowa
+  A { @Code sin @I angle }
+  B { sine of angle measured in degrees (99) }
+@Rowa
+  A { @Code cos @I angle }
+  B { cosine of angle measured in degrees (99) }
+@Rowa
+  A { @I number @Code atan @I number }
+  B { arc tangent of first over second (98) }
+@Rowa
+  A { @I number @Code exp @I number }
+  B { first number raised to second number (98) }
+@Rowa
+  A { @I number @Code log @I number }
+  B { logarithm of second number to base first (98) }
+@Rowa
+  A { @I number @Code rand @I number }
+  B { random real number in this range inclusive (98) }
+@Rowa
+  A { @I number @Code max @I number }
+  B { the larger of two numbers (98) }
+@Rowa
+  A { @I number @Code min @I number }
+  B { the smaller of two numbers (98) }
+@Rowa
+  A { @I number @Code "*" @I number }
+  B { the product of two numbers (97) }
+@Rowa
+  A { @I number @Code "/" @I number }
+  B { real-valued division (96, left associative) }
+@Rowa
+  A { @I length @Code "/" @I length }
+  B { the ratio of two lengths (96, left associative) }
+@Rowa
+  A { @I angle @Code "/" @I angle }
+  B { the ratio of two angles (96, left associative) }
+@Rowa
+  A { @I number @Code idiv @I number }
+  B { integer division of two numbers (96, left associative) }
+@Rowa
+  A { @I number @Code mod @I number }
+  B { integer remainder when first divided by second (96) }
+@Rowa
+  A { @I number @Code "+" @I number }
+  B { sum of two numbers (96, left associative) }
+@Rowa
+  A { @Code "+" @I number }
+  B { identity operation (96) }
+@Rowa
+  A { @I number @Sym minus @I number }
+  B { difference of two numbers (96, left associative) }
+@Rowa
+  A { @Sym minus @I number }
+  B { negation (96) }
+@Rowa
+  A { @Code sides }
+  B { ({@Code outline} only) value of the node's @Code sides option }
+
+@Rowh
+@Rowh
+@Rowh
+@Rowh
+@Rowh A { @I length } vmargin { 0.2vx }
+@Rowh
+@Rowa
+  A { 0 }
+  B { zero }
+@Rowa
+  A { @Code xsize }
+  B { ({@Code outline} only) distance to right boundary }
+@Rowa
+  A { @Code ysize }
+  B { ({@Code outline} only) distance to top boundary }
+@Rowa
+  A { @Code xmark }
+  B { ({@Code outline} only) distance to column mark }
+@Rowa
+  A { @Code ymark }
+  B { ({@Code outline} only) distance to row mark }
+@Rowa
+  A { @Code margin }
+  B { ({@Code outline} only) value of the node's @Code margin option }
+@Rowa
+  A { @Code shadow }
+  B { ({@Code outline} only) value of the node's @Code shadow option }
+@Rowa
+  A { @I number @Code i }
+  B { @I number inches (100) }
+@Rowa
+  A { @I number @Code c }
+  B { @I number centimetres (100) }
+@Rowa
+  A { @I number @Code p }
+  B { @I number points (100) }
+@Rowa
+  A { @I number @Code m }
+  B { @I number ems (100) }
+@Rowa
+  A { @I number @Code s }
+  B { @Code 1s is the current width of a space (100) }
+@Rowa
+  A { @I number @Code v }
+  B { @Code 1v is the current inter-line space (100) }
+@Rowa
+  A { @I number @Code f }
+  B { @Code 1f is the size of the current font (100) }
+@Rowa
+  A { @Code "xcoord" @I point }
+  B { the @I x coordinate of the point (99) }
+@Rowa
+  A { @Code "ycoord" @I point }
+  B { the @I y coordinate of the point (99) }
+@Rowa
+  A { @Code abs @I length }
+  B { absolute value (99) }
+@Rowa
+  A { @I length @Code rand @I length }
+  B { random real length in this range inclusive (98) }
+@Rowa
+  A { @I length @Code max @I length }
+  B { the larger of two lengths (98) }
+@Rowa
+  A { @I length @Code min @I length }
+  B { the smaller of two lengths (98) }
+@Rowa
+  A { @I point @Code "distance" @I point }
+  B { (non-negative) distance between two points (98) }
+@Rowa
+  A { @I length @Code "*" @I number }
+  B { length multiplied by number (97) }
+@Rowa
+  A { @I number @Code "*" @I length }
+  B { length multiplied by number (97) }
+@Rowa
+  A { @I length @Code "/" @I number }
+  B { length divided by number (96, left associative) }
+@Rowa
+  A { @I length @Code "+" @I length }
+  B { sum of two lengths (96, left associative) }
+@Rowa
+  A { @Code "+" @I length }
+  B { identity operation (96) }
+@Rowa
+  A { @I length @Sym minus @I length }
+  B { difference of two lengths (96, left associative) }
+@Rowa
+  A { @Sym minus @I length }
+  B { negation (96) }
+
+@Rowh
+@Rowh
+@Rowh
+@Rowh
+@Rowh A { @I angle } vmargin { 0.2vx }
+@Rowh
+@Rowa
+  A { @I number @Code d }
+  B { @I number degrees (100) }
+@Rowa
+  A { @I number }
+  B { @I number degrees (@Code d is optional) (100) }
+@Rowa
+  A { @Code parallel }
+  B { ({@Code labelangle} options only) angle parallel to curve at label point }
+@Rowa
+  A { @Code antiparallel }
+  B { ({@Code labelangle} options only) angle antiparallel to curve at label point }
+@Rowa
+  A { @Code perpendicular }
+  B { ({@Code labelangle} options only) angle perpendicular to curve at label point }
+@Rowa
+  A { @Code antiperpendicular }
+  B { ({@Code labelangle} options only) angle antiperpendicular to curve at label point }
+@Rowa
+  A { {@I label}{@Code "??ANGLE"} }
+  B { angle parallel to curve at {@I label} if known, else @Code "0d" (99) }
+@Rowa
+  A { @Code anglefix @I angle }
+  B { @I angle normalized to between @Code 0d inclusive and @Code 360d exclusive (99) }
+@Rowa
+  A { @Code abs @I angle }
+  B { absolute value (99) }
+@Rowa
+  A { @I length @Code atan @I length }
+  B { arc tangent of first over second (98) }
+@Rowa
+  A { @I point @Code "angleto" @I point }
+  B { angle from first point to second (98) }
+@Rowa
+  A { @I angle @Code rand @I angle }
+  B { random angle in this range inclusive (98) }
+@Rowa
+  A { @I angle @Code max @I angle }
+  B { the larger of two angles (98) }
+@Rowa
+  A { @I angle @Code min @I angle }
+  B { the smaller of two angles (98) }
+@Rowa
+  A { @I angle @Code "*" @I number }
+  B { angle multiplied by number (97) }
+@Rowa
+  A { @I number @Code "*" @I angle }
+  B { angle multiplied by number (97) }
+@Rowa
+  A { @I angle @Code "/" @I number }
+  B { division of angle by number (96, left associative) }
+@Rowa
+  A { @I angle @Code "+" @I angle }
+  B { sum of two angles (96, left associative) }
+@Rowa
+  A { @Code "+" @I angle }
+  B { identity operation (96) }
+@Rowa
+  A { @I angle @Sym minus @I angle }
+  B { difference of two angles (96, left associative) }
+@Rowa
+  A { @Sym minus @I angle }
+  B { negation (96) }
+@Rowa
+  A { @Code angle }
+  B { ({@Code outline} only) value of the node's @Code angle option }
+
+
+@Rowh
+@Rowh
+@Rowh
+@Rowh
+@Rowh A { @I point } vmargin { 0.2vx }
+@Rowh
+@Rowa
+  A { @I label }
+  B { a previously defined label }
+@Rowa
+  A { {@I any}{@Code "??"}{@I label} }
+  B { {@I any}{@Code "@"}{@I label} if sensible, else {@I any} (99) }
+@Rowa
+  A { @Code "prev" }
+  B { the previous point in a shape }
+@Rowa
+  A { @I length  @Code "atangle"  @I angle }
+  B { point at distance and angle from origin (89) }
+@Rowa
+  A { @I "point/tag" @Code "boundaryatangle" @I angle }
+  B { @I {point}, or point on boundary of @I tag at @I angle (89) }
+@Rowa
+  A { @I point  @Code "**"  @I number }
+  B { multiplication of point by number (88) }
+@Rowa
+  A { @I point  @Code "++"  @I point }
+  B { vector sum of two points (87) }
+@Rowa
+  A { @I point  {@Sym minus}{@Sym minus}  @I point }
+  B { vector difference of two points (87) }
+@Rowa
+  A { @I {number, number} }
+  B { @I x and @I y coordinates with respect to base (70) }
+@Rowa
+  A { @I {length  length} }
+  B { @I x and @I y distance from origin (5) }
+@Rowa
+  A { @Code from }
+  B { ({@Code path} only) the value of the link's @Code from option }
+@Rowa
+  A { @Code to }
+  B { ({@Code path} only) the value of the link's @Code to option }
+
+@Rowh
+@Rowh
+@Rowh
+@Rowh
+@Rowh A { @I boolean } vmargin { 0.2vx }
+@Rowh
+@Rowa
+  A { @I number @Code "=" @I number }
+  B { @Eq { non = }; also between lengths (79) }
+@Rowa
+  A { @I number @Code "!=" @I number }
+  B { @Eq { non != }; also between lengths (79) }
+@Rowa
+  A { @I number @Code "==" @I number }
+  B { @Eq { non = } between angles (79) }
+@Rowa
+  A { @I number @Code "!==" @I number }
+  B { @Eq { non != } between angles (79) }
+@Rowa
+  A { @I number @Code "<=" @I number }
+  B { @Eq { non <= }; also between lengths (79) }
+@Rowa
+  A { @I number @Code "<" @I number }
+  B { @Eq { non < }; also between lengths (79) }
+@Rowa
+  A { @I number @Code ">=" @I number }
+  B { @Eq { non >= }; also between lengths (79) }
+@Rowa
+  A { @I number @Code ">" @I number }
+  B { @Eq { non > }; also between lengths (79) }
+@Rowa
+  A { @Code "not" @I boolean }
+  B { Logical not (78) }
+@Rowa
+  A { @I boolean @Code "and" @I boolean }
+  B { Logical and (77) }
+@Rowa
+  A { @I boolean @Code "or" @I boolean }
+  B { Logical or (76) }
+@Rowa
+  A { @I boolean @Code "xor" @I boolean }
+  B { Logical exclusive or (76) }
+
+}
+@DP
+A length is represented in PostScript by a single number on the operand
+stack; so is an angle.  Therefore all number operations can be applied
+to lengths and angles as well, but the results will not always be
+useful.  For example, rounding a length to the nearest integer is
+not a useful thing to do because the result depends on the basic unit
+(what does 1 equal as a length?) which is implementation-dependent and
+genuinely subject to change.  Rounding the @I ratio of two lengths does
+make sense.  The above is an attempt to list only the useful operations;
+but if you really need the logarithm of an angle, you can have it.
+@PP
+Angles are a little more amenable to this kind of thing because they are
+always measured in degrees.  However, angles suffer from the problem that
+{@Code 0d} is really the same angle as {@Code 360d}.  For this reason,
+separate equality and inequality operators for angles are provided which
+ignore multiples of {@Code 360d}, and less than and similar relations
+are not defined for angles, because they inherently are not well
+defined.  See also the @Code anglefix symbol above.
+@PP
+A point is represented by two lengths (which are numbers) on the
+stack.  Those familiar with PostScript and willing to sacrifice portability
+and increase their risk of error can therefore write, for example,
+@OneCol { @I point @Code "exch" } to obtain the reflection of a point about
+the main diagonal, and so on.
+@PP
+The following may have a result of any type, depending on
+their options.  The options and result may be a
+sequence of things as required in shapes, including @Code "[]" and
+so forth.
+@IndentedList
+@LI @OneRow lines @Break {
+@Code if
+    @Code "cond {" @I boolean @Code "}"
+    @Code "then {" @I anything @Code "}"
+    @Code "else {" @I anything @Code "}"
+}
+@LI @OneRow lines @Break {
+@I angle @Code quadcase
+    @Code "0 {" @I anything @Code "}"
+    @Code "0-90 {" @I anything @Code "}"
+    @Code "90 {" @I anything @Code "}"
+    @Code "90-180 {" @I anything @Code "}"
+    @Code "180 {" @I anything @Code "}"
+    @Code "180-270 {" @I anything @Code "}"
+    @Code "270 {" @I anything @Code "}"
+    @Code "270-360 {" @I anything @Code "}"
+}
+@LI @OneRow lines @Break {
+@I number @Code signcase
+    @Code "neg {" @I anything @Code "}"
+    @Code "zero {" @I anything @Code "}"
+    @Code "pos {" @I anything @Code "}"
+}
+@LI @OneRow lines @Break {
+@Code "xloop from {" @I number "} to {" @I number "} by {" @I number "} do {"
+    @I anything
+@Code "}"
+}
+@LI @OneRow lines @Break {
+@Code "yloop from {" @I number "} to {" @I number "} by {" @I number "} do {"
+    @I anything
+@Code "}"
+}
+@LI @OneRow lines @Break {
+@Code "zloop from {" @I number "} to {" @I number "} by {" @I number "} do {"
+    @I anything
+@Code "}"
+}
+@EndList
+The @Code "if" symbol returns @Code "then" or @Code "else" depending on
+the value of {@Code "cond"}, and @Code "signcase" returns {@Code "neg"},
+{@Code zero}, or {@Code pos} depending on whether @I number (which
+may also be an angle or a length) is negative, zero, or positive.  The
+@Code "quadcase" symbol decides whether the given angle points in
+one of the four horizontal or vertical directions, or into the quadrants
+between them, and returns the appropriate option.  Don't be misled by
+the unorthodox option names; it is not possible to give your own
+ranges, only these ones.
+@PP
+The loops return a sequence of
+repetitions of {@I anything}; any occurrences of {@Code x} in
+{@Code xloop} will be replaced by the current value of the loop counter,
+and similarly for the other loops.
+@PP
+Symbols not covered in this summary are the retagging symbol @Code "::"
+(Section {@NumberOf dia_tags}); the symbols available within the
+{@Code "@Tree"} symbol (Section {@NumberOf dia_posi}); and {@Code ":<"},
+{@Code ":="}, {@Code "@ShowPoints"}, {@Code "@ShowTags"}, and
+{@Code "@ShowDirections"} from Section {@NumberOf dia_defi}.
+@End @Section
diff --git a/doc/user/dia_tags b/doc/user/dia_tags
new file mode 100644
index 0000000..91cd7a1
--- /dev/null
+++ b/doc/user/dia_tags
@@ -0,0 +1,168 @@
+@Section
+    @Tag { dia_tags }
+    @Title { Tags }
+@Begin
+@PP
+In addition to drawing the outline, each of the standard node
+types also attaches names, called {@I tags}, to certain points.  For
+example, the @Code "@Ellipse" symbol creates nine tags:
+@ID {
+@Code {
+"@Ellipse"
+}
+||7ct
+@Diag {
+//1.0f
+@ShowTags @Ellipse
+    vsize { 1.5c }
+    hsize { 3.0c }
+}
+}
+The standard link symbols also create tags:
+@ID {
+@Code {
+"@Link"
+}
+||7ct
+@Diag {
+2.5c @High 2c @Wide
+//
+@ShowTags @Arrow
+    from { 0,0.8 }
+    to { 1,0 }
+}
+}
+The names and positions of all standard tags may be found in the summary
+(Section {@NumberOf dia_summ}) at the end of this chapter.  Each tag
+stands for a point, and may be used wherever a point is required:
+@ID {
+@Code {
+"@Ellipse { Hello, world }"
+"//"
+"@Link from { SW } to { SE }"
+}
+||7ct
+@Diag {
+@Ellipse { Hello, world }
+//
+@Link from { SW } to { SE }
+}
+}
+A tag may only be used later in the text of the diagram than the place
+where it is defined.
+@PP
+Standard tags like @Code N and @Code S are not much use as they are,
+since in general there will be many nodes and hence many @Code N and
+@Code S tags.  The retagging symbol, {@Code "::"}, solves this problem:
+@ID {
+@Code {
+"A:: @Ellipse"
+}
+||7ct
+@Diag {
+//1.5f
+@ShowTags {
+A:: @Ellipse
+    vsize { 1.5c }
+    hsize { 3.0c }
+}
+}
+}
+Within the following object, the points have their original tags, but
+afterwards the names are changed by prefixing the word preceding
+{@Code "::"}, plus a @Code "@" character, to each one.  These longer
+tags may be used exactly like the others:
+@ID {
+@Code {
+"A:: @Ellipse { Hello, world }"
+"//"
+"@Link from { A@SW } to { A@SE }"
+}
+||7ct
+@Diag {
+A:: @Ellipse { Hello, world }
+//
+@Link from { A@SW } to { A@SE }
+}
+}
+The retagging symbol may be applied to links, and indeed to arbitrary
+objects; it will retag every tag within the following object, even
+tags that have already been retagged:
+@ID {
+@Code {
+"A:: {"
+"    1:: @Ellipse"
+"        vsize { 1.0c }"
+"        hsize { 2.5c }"
+"    @DP"
+"    @DP"
+"    2:: @Ellipse"
+"        vsize { 1.0c }"
+"        hsize { 2.5c }"
+"}"
+}
+||7ct
+@Diag {
+//1.0f
+@ShowTags {
+A:: {
+    1:: @Ellipse
+        vsize { 1.0c }
+        hsize { 2.5c }
+    @DP
+    @DP
+    2:: @Ellipse
+        vsize { 1.0c }
+        hsize { 2.5c }
+}
+}
+}
+}
+In practice one usually only retags individual nodes.  It is best to
+use only upper-case letters and digits in tags, because Lout and
+PostScript have tags of their own containing lower-case letters, and
+any mixup causes total disaster.
+@PP
+When a tag lies within the object following some node, it is
+automatically retagged in this way with tag {@Code IN}.  For example, in
+@ID @Code {
+"@Square"
+"@Circle Hello"
+}
+the circle lies within the square, and what you get in effect is
+@ID @Code {
+"@Square"
+"IN:: @Circle Hello"
+}
+This prevents confusion between the tags of the inner and outer nodes.  This
+retagging cannot be left to the user's discretion, owing to unexpected
+effects on the positioning of labels of the outer node if inner tags are
+not retagged.
+@PP
+Although @Code from and @Code to are just two of several options within
+@Code "@Diag" where a point is expected, and hence where a tag may be
+given, they have a special virtue not shared by any other options.  It is
+possible to give the name of an entire node, not just a tag denoting one
+point, to them:
+@ID {
+@Code {
+"A:: @Circle"
+"@DP"
+"B:: @Ellipse { Hello, world }"
+"//"
+"@Link from { A } to { B }"
+}
+||7ct
+@Diag {
+A:: @Circle
+@DP
+B:: @Ellipse { Hello, world }
+//
+@Link from { A } to { B }
+}
+}
+This will select a point on the outline of the named node, appropriate
+to the type of link being drawn.  It is extremely useful, of course, but
+potentially confusing:  @Code A and @Code B do not denote points and are
+not tags, strictly speaking, at all.
+@End @Section
diff --git a/doc/user/dia_tree b/doc/user/dia_tree
new file mode 100644
index 0000000..d16f2bc
--- /dev/null
+++ b/doc/user/dia_tree
@@ -0,0 +1,379 @@
+@Section
+    @Tag { dia_tree }
+    @Title { Trees }
+@Begin
+@PP
+@@Diag offers some symbols for producing tree diagrams, using the
+tree. @Index { @Code "@Tree" symbol in @@Diag }
+@Code "@Tree" symbol, which may appear anywhere within the nodes part:
+@ID @OneRow @Code {
+"@Diag {"
+"    ..."
+"    @Tree { ... }"
+"    ..."
+"}"
+}
+Within this symbol, new symbols {@Code "@LeftSub"}, {@Code "@RightSub"},
+{@Code "@FirstSub"}, {@Code "@NextSub"}, and {@Code "@StubSub"} become
+available.  The first two are used to get a (non-empty) binary tree:
+@ID @OneRow {
+@Code {
+"@Tree {"
+"    @Circle A"
+"    @LeftSub {"
+"        @Circle B"
+"        @LeftSub @Square C"
+"        @RightSub @Square D"
+"    }"
+"    @RightSub @Circle E"
+"}"
+}
+||7ct
+@Diag {
+@Tree {
+    @Circle A
+    @LeftSub {
+        @Circle B
+        @LeftSub @Square C
+        @RightSub @Square D
+    }
+    @RightSub @Circle E
+}
+}
+}
+The root of the tree, which must be a single node but may have any
+outline, comes first.  After that comes the @Code "@LeftSub" symbol
+followed by the left subtree, which must be enclosed in braces unless
+it consists of a single node.  After that comes the @Code "@RightSub"
+symbol followed by the right subtree, again enclosed in braces unless it
+consists of a single node.  These rules apply recursively and will
+produce a binary tree of arbitrary size and depth.  If a node has no
+left or right subtree, leave out the corresponding @Code "@LeftSub" or
+@Code "@RightSub" symbol.
+@PP
+A similar system using @Code "@FirstSub" and @Code "@NextSub" produces
+trees in which each node may have arbitrarily many children:
+@ID @OneRow {
+@Code {
+"@Tree {"
+"    @Circle A"
+"    @FirstSub {"
+"        @Circle B"
+"        @FirstSub @Square C"
+"        @NextSub @Square D"
+"    }"
+"    @NextSub @Circle E"
+"    @NextSub @Circle F"
+"}"
+}
+||7ct
+@Diag {
+@Tree {
+    @Circle A
+    @FirstSub {
+        @Circle B
+        @FirstSub @Square C
+        @NextSub @Square D
+    }
+    @NextSub @Circle E
+    @NextSub @Circle F
+}
+}
+}
+The first subtree is preceded by {@Code "@FirstSub"}, and subsequent
+trees are preceded by {@Code "@NextSub"}.  The subtrees are spaced
+at equal separations from each other, with the root centred over
+them, in contrast to the binary tree arrangement in which the two
+subtrees are positioned to the left and right of the root, never
+intruding into the space beneath it.
+@PP
+Although each subtree must contain a node for its root, it is not hard
+to get around this:
+@ID @OneRow {
+@Code {
+"@Tree"
+"{"
+"@Circle"
+"@FirstSub @Circle"
+"@NextSub pathstyle { noline }"
+"    @Circle outlinestyle { noline }"
+"       ..."
+"@NextSub @Circle"
+"}"
+}
+||7ct
+@Diag {
+@Tree
+{
+@Circle
+@FirstSub @Circle
+@NextSub pathstyle { noline }
+    @Circle outlinestyle { noline }
+       ...
+@NextSub @Circle
+}
+}
+}
+Clumsy as this is, it often assists in placing the unenclosed object
+in a way consistent with the surrounding nodes, and offers margins
+and so forth which help with fine-tuning its position.
+@PP
+The fifth subtree symbol, {@Code "@StubSub"}, produces a stub subtree:
+@ID @OneRow {
+@Code {
+"@Tree {"
+"@Circle @Eq { a }"
+"@StubSub @Eq { T tsub a }"
+"}"
+}
+||7ct
+@Diag {
+@Tree {
+@Circle @Eq { a }
+@StubSub @Eq { T tsub a }
+}
+}
+}
+Unlike the other subtree symbols, {@Code "@StubSub"} is not followed
+by a subtree with a node for its root; rather, it is followed by an
+arbitrary object, and the path is drawn around this stub object, which
+is placed directly underneath the parent node with zero vertical
+separation.  In practice, it is usually necessary to attach margins to
+the following object; the easiest way to do that is to enclose it in
+{@Code "@Box outlinestyle { noline }"}.  An example appears below.
+@PP
+It is possible to mix the three subtree types, by having binary tree
+symbols following some nodes, non-binary tree symbols following
+others, and a single {@Code "@StubSub"} following others.  However,
+at any one node the subtrees must be all either binary, non-binary,
+or stub.
+@PP
+The subtree symbols have all of the options of {@Code "@Link"}, and
+these apply to the link drawn from the parent of the root of the subtree
+to the root of the subtree (or anticlockwise around the stub object):
+@ID @OneRow {
+@Code {
+"@Tree {"
+"    @Circle A"
+"    @LeftSub"
+"        arrow { yes }"
+"        xlabel { 1 }"
+"    @Circle B"
+"    @RightSub"
+"        arrow { yes }"
+"        xlabel { 2 }"
+"    @Circle C"
+"}"
+}
+||7ct
+@Diag {
+@Tree {
+    @Circle A
+    @LeftSub
+        arrow { yes }
+        xlabel { 1 }
+    @Circle B
+    @RightSub
+        arrow { yes }
+        xlabel { 2 }
+    @Circle C
+}
+}
+}
+To get reverse arrows use @Code "arrow { back }" as usual.
+@PP
+The subtree symbols do not need @Code from and @Code to options,
+because they already know which nodes they are linking together.  However,
+you may use @Code from or @Code to to give a tag specifying a particular
+point within the node:
+@ID @OneRow {
+@Code {
+"@Tree {"
+"@Circle"
+"@LeftSub from { S } to { N }"
+"    @Isosceles vsize { 2f }"
+"@RightSub from { S } to { N }"
+"    @Isosceles vsize { 2f }"
+"}"
+}
+||7ct
+@Diag
+{
+@Tree {
+@Circle
+@LeftSub from { S } to { N }
+    @Isosceles vsize { 2f }
+@RightSub from { S } to { N }
+    @Isosceles vsize { 2f }
+}
+}
+}
+In this example both links go from the @Code S tag of the parent node to the
+@Code N tag of the child node (at the apex of the iscosceles triangle).  These
+options also work for {@Code "@StubSub"}, where they refer to the start and
+end of the stub path:
+@ID @OneRow {
+@Code {
+"@Tree {"
+"@Circle @Eq { a }"
+"@StubSub"
+"    from { SW }"
+"    to { SE }"
+"@Box outlinestyle { noline }"
+"    @Eq { T tsub a }"
+"}"
+}
+||7ct
+@Diag {
+@Tree {
+@Circle @Eq { a }
+@StubSub
+    from { SW }
+    to { SE }
+@Box outlinestyle { noline }
+    @Eq { T tsub a }
+}
+}
+}
+and so the tags both refer to points in the parent node in this case.
+@PP
+The @Code "@LeftSub" and @Code "@RightSub" symbols have variants called
+@Code "@ZeroWidthLeftSub" and @Code "@ZeroWidthRightSub" which are the
+same except that the resulting subtrees consume no width:
+@ID @OneRow {
+@Code {
+"@Tree {"
+"@Circle"
+"@LeftSub {"
+"    @Circle"
+"    @LeftSub @Square"
+"    @RightSub @Square"
+"}"
+"@RightSub {"
+"    @Circle"
+"    @LeftSub {"
+"        @Circle"
+"        @ZeroWidthLeftSub @Square"
+"        @ZeroWidthRightSub @Square"
+"    }"
+"    @RightSub @Square"
+"} }"
+}
+||7ct
+@Diag {
+@Tree
+{
+@Circle
+@LeftSub {
+    @Circle
+    @LeftSub @Square
+    @RightSub @Square
+}
+@RightSub {
+    @Circle
+    @LeftSub {
+        @Circle
+        @ZeroWidthLeftSub @Square
+        @ZeroWidthRightSub @Square
+    }
+    @RightSub @Square
+}
+}
+}
+}
+There is nothing analogous for the other subtree symbols.
+@PP
+The @Code "@Diag" symbol has a few options for adjusting the appearance
+of the tree.  The @Code "treehsep" option determines the horizontal space left
+between a root and its left subtree, between a root and its right subtree,
+and between one subtree and the next when @Code "@NextSub" is used.  The
+@Code "treevsep" option determines the vertical space left between a root
+and its subtrees:
+@ID @OneRow {
+@Code {
+"@Diag"
+"    treehsep { 0c }"
+"    treevsep { 0c }"
+"{"
+"@Tree"
+"{"
+"    @Circle A"
+"    @LeftSub @Square B"
+"    @RightSub @Square C"
+"}"
+"}"
+}
+||7ct
+@Diag
+    treehsep { 0c }
+    treevsep { 0c }
+{
+@Tree
+{
+    @Circle A
+    @LeftSub @Square B
+    @RightSub @Square C
+}
+}
+}
+These options may also be given to individual subtree symbols, although
+@Code "treevsep" works as expected only with @Code "@LeftSub" and
+{@Code "@FirstSub"}, since these determine the vertical separation of
+all children of their parent.
+@PP
+The @Code "treehindent" option determines where the root of a non-binary
+tree is positioned over its subtrees; the value may be @Code "left"
+for at left, @Code "ctr" for centred over them (the default),
+@Code "right" for at the right, or any length, meaning that far from
+the left.  Owing to problems behind the scenes, this option may not be
+given to individual subtree symbols; so as a consolation, it is permitted
+as an option to the @Code "@Tree" symbol.
+@PP
+It is not possible to attach tags to nodes within a tree, because
+tags are attached automatically by the tree symbols and any extra
+tags would disrupt the linking.  However, you can use @Code "@ShowTags"
+to find out what these automatic tags are, and use them in a subsequent
+links part.  For example, the tag attached to the right child of the left
+child of the root of a binary tree is {@Code "L@R@T"}, and in general the
+tag records the path from the root to the node, with @Code "T" added to
+the end.  The root always has tag {@Code "T"}.  The tree as a whole may
+be retagged in the usual way.
+@PP
+There is an @Code "@HTree" symbol which is the same as
+htree. @Index { @Code "@HTree" symbol in @@Diag }
+@Code "@Tree" except that the tree grows horizontally (from left to
+right) instead of vertically.  The same symbols are available within
+@Code "@HTree" as within {@Code "@Tree"}; @Code "@LeftSub" and
+@Code "@FirstSub" produce what might be called the top subtree, and
+@Code "@RightSub" and @Code "@NextSub" produce lower trees.  @Code "@HTree"
+has no @Code "treehindent" option; instead, it has an exactly analogous
+@Code "treevindent" option.
+@PP
+@Code "@HTree" may be used to get horizontal lists:
+@ID @OneRow {
+@Code {
+"@I @Diag"
+"    arrow { yes } treehsep { 1c } {"
+"@HTree {"
+"    @Node A"
+"    @FirstSub {"
+"        @Node B"
+"        @FirstSub @Node C"
+"    }"
+"}"
+"}"
+}
+||7ct
+@I @Diag arrow { yes } treehsep { 1c } {
+@HTree {
+@Node A
+@FirstSub {
+    @Node B
+    @FirstSub @Node C 
+}
+}
+}
+}
+The braces are clumsy but necessary.  The first node has tag {@Code "T"}, the
+second has tag {@Code "S@T"}, the third has tag {@Code "S@S@T"}, and so on.
+@End @Section
diff --git a/doc/user/draft.eps b/doc/user/draft.eps
new file mode 100644
index 0000000..bfc6e9a
--- /dev/null
+++ b/doc/user/draft.eps
@@ -0,0 +1,289 @@
+%!PS-Adobe-3.0
+%%Creator: Basser Lout Version 3.00 (July 1994)
+%%CreationDate: Fri Sep  9 10:46:13 1994
+%%DocumentData: Binary
+%%DocumentNeededResources: (atend)
+%%DocumentSuppliedResources: (atend)
+%%Pages: (atend)
+%%BoundingBox: 0 0 595 842
+%%EndComments
+
+%%BeginProlog
+%%BeginResource: procset LoutStartUp
+/m { 3 1 roll moveto show } bind def
+/s { exch currentpoint exch pop moveto show } bind def
+/k { exch neg 0 rmoveto show } bind def
+/in { 1440 mul } def
+/cm { 567 mul } def
+/pt { 20 mul } def
+/em { 120 mul } def
+/sp { louts mul } def
+/vs { loutv mul } def
+/ft { loutf mul } def
+/dg {           } def
+
+/LoutGraphic {
+  /louts exch def
+  /loutv exch def
+  /loutf exch def
+  /ymark exch def
+  /xmark exch def
+  /ysize exch def
+  /xsize exch def
+} def
+
+/LoutFont
+{ findfont exch scalefont setfont
+} bind def
+
+/LoutRecode {
+  { findfont dup length dict begin
+    {1 index /FID ne {def} {pop pop} ifelse} forall
+    /Encoding exch def
+    currentdict end definefont pop
+  }
+  stopped {}
+} bind def
+
+/BeginEPSF {
+  /LoutEPSFState save def
+  /dict_count countdictstack def
+  /op_count count 1 sub def
+  userdict begin
+  /showpage { } def
+  0 setgray 0 setlinecap
+  1 setlinewidth 0 setlinejoin
+  10 setmiterlimit [] 0 setdash newpath
+  /languagelevel where
+  { pop languagelevel
+    1 ne
+    { false setstrokeadjust false setoverprint
+    } if
+  } if
+} bind def
+
+/EndEPSF {
+  count op_count sub { pop } repeat
+  countdictstack dict_count sub { end } repeat
+  LoutEPSFState restore
+} bind def
+%%EndResource
+
+%%BeginResource encoding vec1
+/vec1 [
+/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef
+/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef
+/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef
+/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef
+/space /exclam /quotedbl /numbersign /dollar /percent /ampersand /quoteright
+/parenleft /parenright /asterisk /plus /comma /hyphen /period /slash
+/zero /one /two /three /four /five /six /seven
+/eight /nine /colon /semicolon /less /equal /greater /question
+/at /A /B /C /D /E /F /G
+/H /I /J /K /L /M /N /O
+/P /Q /R /S /T /U /V /W
+/X /Y /Z /bracketleft /backslash /bracketright /asciicircum /underscore
+/quoteleft /a /b /c /d /e /f /g
+/h /i /j /k /l /m /n /o
+/p /q /r /s /t /u /v /w
+/x /y /z /braceleft /bar /braceright /asciitilde /.notdef
+/.notdef /.notdef /.notdef /.notdef /.notdef /quotedblleft /quotedblright /fi
+/fl /endash /emdash /bullet /dagger /daggerdbl /florin /fraction
+/dotlessi /grave /acute /circumflex /tilde /macron /breve /dotaccent
+/dieresis /.notdef /ring /cedilla /.notdef /hungarumlaut /ogonek /caron
+/space /exclamdown /cent /sterling /currency /yen /brokenbar /section
+/dieresis /copyright /ordfeminine /guillemotleft /logicalnot /hyphen /registered /macron
+/degree /plusminus /twosuperior /threesuperior /acute /mu /paragraph /periodcentered
+/cedilla /onesuperior /ordmasculine /guillemotright /onequarter /onehalf /threequarters /questiondown
+/Agrave /Aacute /Acircumflex /Atilde /Adieresis /Aring /AE /Ccedilla
+/Egrave /Eacute /Ecircumflex /Edieresis /Igrave /Iacute /Icircumflex /Idieresis
+/Eth /Ntilde /Ograve /Oacute /Ocircumflex /Otilde /Odieresis /multiply
+/Oslash /Ugrave /Uacute /Ucircumflex /Udieresis /Yacute /Thorn /germandbls
+/agrave /aacute /acircumflex /atilde /adieresis /aring /ae /ccedilla
+/egrave /eacute /ecircumflex /edieresis /igrave /iacute /icircumflex /idieresis
+/eth /ntilde /ograve /oacute /ocircumflex /otilde /odieresis /divide
+/oslash /ugrave /uacute /ucircumflex /udieresis /yacute /thorn /ydieresis
+] def
+%%EndResource
+
+%%EndProlog
+
+%%BeginSetup
+%%IncludeResource: font Times-Roman
+/Times-Romanfnt86 vec1 /Times-Roman LoutRecode
+/fnt86 { /Times-Romanfnt86 LoutFont } def
+%%IncludeResource: font Times-Bold
+/Times-Boldfnt88 vec1 /Times-Bold LoutRecode
+/fnt88 { /Times-Boldfnt88 LoutFont } def
+%%IncludeResource: font Times-Italic
+/Times-Italicfnt87 vec1 /Times-Italic LoutRecode
+/fnt87 { /Times-Italicfnt87 LoutFont } def
+/LoutExtColour [ currentrgbcolor ] cvx def
+%%EndSetup
+
+%%Page: ? 1
+%%BeginPageSetup
+%%PageResources: font Times-Roman
+%%+ font Times-Bold
+%%+ font Times-Italic
+/pgsave save def
+0.0500 dup scale 10 setlinewidth
+%%EndPageSetup
+
+gsave
+0 16840 translate
+0.0000 rotate
+gsave
+3087 -14622 translate
+17.7734 17.7734 scale
+gsave
+0 0 translate
+62.0000 rotate
+240 fnt86 0.8 0.8 0.8 setrgbcolor 0 -54(DRAFT)m 
+grestore
+
+grestore
+
+grestore
+gsave
+0 16840 translate
+0.0000 rotate
+240 fnt88 LoutExtColour setrgbcolor
+5143 -3022(A)m 5376(T)s 22(est)k 5852(Example)s 240 fnt87
+5029 -3520(J)m 6(ef)k 4(fr)k 8(e)k 7(y)k
+5713(H.)s 6006(Kingston)s 240 fnt86 3998 -4021(Basser)m 4695(Department)s
+5883(of)s 6142(Computer)s 7159(Science)s 4446 -4309(The)m 4878(Uni)s 6(v)k 3(ersity)k
+5938(of)s 6197(Sydne)s 3(y)k 6973(2006)s 5512 -4597(Australia)m
+5053 -5050(9)m 5233(September)s 9(,)k 6366(1994)s 240 fnt88
+3097 -5692(Abstract)m 240 fnt86 1897 -6123(This)m 2403(is)s 2643(the)s
+3016(abstract.)s 3959(It')s 13(s)k 4344(v)s 3(ery)k
+4847(short,)s 5466(as)s 1417 -6411(be\207ts)m 2036(a)s 2243(tin)s 3(y)k
+2713(test)s 3145(document.)s 4310(Ho)s 6(we)k 6(v)k 3(er)k
+5273(it)s 5506(is)s 1417 -6699(long)m 1892(enough)s 2647(to)s
+2882(check)s 3489(that)s 3896(things)s 4530(are)s 4870(w)s 2(orking)k
+1417 -6987(as)m 1676(e)s 3(xpected.)k 240 fnt88 1417 -7780(1.)m
+1717(The)s 2176(\207rst)s 2647(section)s 240 fnt86 1897 -8211(This)m
+2408(is)s 2653(the)s 3031(\207rst)s 3488(section.)s 4371(It)s
+4602(too)s 4994(is)s 5239(v)s 3(ery)k 1417 -8499(short,)m
+2045(just)s 2480(a)s 2676(test)s 3097(section,)s 3924(nothing)s
+4746(more)s 5327([)s 5406(1)s 5526(])s 5605(.)s
+1417 -8787(This)m 1912(is)s 2141(the)s 2503(\207rst)s 2944(section.)s
+3811(It)s 4026(too)s 4402(is)s 4631(v)s 3(ery)k
+5123(short,)s 1417 -9075(just)m 1885(a)s 2114(test)s 2568(section,)s
+3428(nothing)s 4283(more.)s 4957(This)s 5505(is)s 1417 -9363(the)m
+1794(\207rst)s 2250(section.)s 3132(It)s 3362(too)s 3753(is)s
+3997(v)s 3(ery)k 4504(short,)s 5127(just)s 5557(a)s
+1417 -9651(test)m 1841(section,)s 2671(nothing)s 3496(more.)s 4140(This)s
+4658(is)s 4910(the)s 5295(\207rst)s 1417 -9939(section.)m 2255(It)s
+2441(too)s 2788(is)s 2988(v)s 3(ery)k 3451(short,)s
+4030(just)s 4416(a)s 4563(test)s 4935(section,)s 1417 -10227(nothing)m
+2254(more.)s 153 fnt86 2805 -10121(i)m 240 fnt86 2952 -10227(This)m
+3482(is)s 3746(the)s 4143(\207rst)s 4619(section.)s 5521(It)s
+1417 -10515(too)m 1794(is)s 2024(v)s 3(ery)k 2517(short,)s
+3126(just)s 3542(a)s 3719(test)s 4121(section,)s 4929(nothing)s
+1417 -10803(more.)m 2037(This)s 2531(is)s 2759(the)s 3120(\207rst)s
+3560(section.)s 4426(It)s 4640(too)s 5015(is)s 5243(v)s 3(ery)k
+1417 -11091(short,)m 2024(just)s 2438(a)s 2613(test)s 3013(section,)s
+3819(nothing)s 4620(more.)s 5240(This)s 1417 -11379(is)m 1655(the)s
+2026(\207rst)s 2476(section.)s 3352(It)s 3576(too)s 3961(is)s
+4199(v)s 3(ery)k 4700(short,)s 5317(just)s 1417 -11667(a)m
+1591(test)s 1990(section,)s 2795(nothing)s 3595(more.)s 4214(This)s
+4707(is)s 4934(the)s 5294(\207rst)s 1417 -11955(section.)m 2255(It)s
+2441(too)s 2788(is)s 2988(v)s 3(ery)k 3451(short,)s
+4030(just)s 4416(a)s 4563(test)s 4935(section,)s 1417 -12243(nothing)m
+2260(more.)s 2922(This)s 3458(is)s 3728(the)s 4131(\207rst)s
+4613(section.)s 5521(It)s 1417 -12531(too)m 1794(is)s 2024(v)s 3(ery)k
+2517(short,)s 3126(just)s 3542(a)s 3719(test)s 4121(section,)s
+4929(nothing)s 1417 -12819(more.)m 2037(This)s 2531(is)s 2759(the)s
+3120(\207rst)s 3560(section.)s 4426(It)s 4640(too)s 5015(is)s
+5243(v)s 3(ery)k 1417 -13107(short,)m 2024(just)s 2438(a)s
+2613(test)s 3013(section,)s 3819(nothing)s 4620(more.)s 5240(This)s
+1417 -13395(is)m 1655(the)s 2026(\207rst)s 2476(section.)s 3352(It)s
+3576(too)s 3961(is)s 4199(v)s 3(ery)k 4700(short,)s
+5317(just)s 1417 -13683(a)m 1591(test)s 1990(section,)s 2795(nothing)s
+3595(more.)s 4214(This)s 4707(is)s 4934(the)s 5294(\207rst)s
+1417 -13971(section.)m 2255(It)s 2441(too)s 2788(is)s 2988(v)s 3(ery)k
+3451(short,)s 4030(just)s 4416(a)s 4563(test)s 4935(section,)s
+1417 -14259(nothing)m 2260(more.)s 2922(This)s 3458(is)s 3728(the)s
+4131(\207rst)s 4613(section.)s 5521(It)s 1417 -14547(too)m 1794(is)s
+2024(v)s 3(ery)k 2517(short,)s 3126(just)s 3542(a)s
+3719(test)s 4121(section,)s 4929(nothing)s 1417 -14835(more.)m 2037(This)s
+2531(is)s 2759(the)s 3120(\207rst)s 3560(section.)s 4426(It)s
+4640(too)s 5015(is)s 5243(v)s 3(ery)k 1417 -15123(short,)m
+2024(just)s 2438(a)s 2613(test)s 3013(section,)s 3819(nothing)s
+4620(more.)s 5240(This)s 6233 -5690(is)m 6471(the)s 6842(\207rst)s
+7292(section.)s 8168(It)s 8392(too)s 8777(is)s 9015(v)s 3(ery)k
+9516(short,)s 10133(just)s 6233 -5978(a)m 6407(test)s 6806(section,)s
+7611(nothing)s 8411(more.)s 9030(This)s 9523(is)s 9750(the)s
+10110(\207rst)s 6233 -6266(section.)m 7071(It)s 7257(too)s 7604(is)s
+7804(v)s 3(ery)k 8267(short,)s 8846(just)s 9232(a)s
+9379(test)s 9751(section,)s 6233 -6554(nothing)m 7076(more.)s 7738(This)s
+8274(is)s 8544(the)s 8947(\207rst)s 9429(section.)s 10337(It)s
+6233 -6842(too)m 6610(is)s 6840(v)s 3(ery)k 7333(short,)s
+7942(just)s 8358(a)s 8535(test)s 8937(section,)s 9745(nothing)s
+6233 -7130(more.)m 6853(This)s 7347(is)s 7575(the)s 7936(\207rst)s
+8376(section.)s 9242(It)s 9456(too)s 9831(is)s 10059(v)s 3(ery)k
+6233 -7418(short,)m 6829(just)s 7232(a)s 7396(test)s 7785(section,)s
+8580(nothing)s 9370(more.)s 153 fnt86 9921 -7312(ii)m 240 fnt86
+10063 -7418(This)m 6233 -7706(is)m 6471(the)s 6842(\207rst)s 7292(section.)s
+8168(It)s 8392(too)s 8777(is)s 9015(v)s 3(ery)k
+9516(short,)s 10133(just)s 6233 -7994(a)m 6407(test)s 6806(section,)s
+7611(nothing)s 8411(more.)s 9030(This)s 9523(is)s 9750(the)s
+10110(\207rst)s 6233 -8282(section.)m 7071(It)s 7257(too)s 7604(is)s
+7804(v)s 3(ery)k 8267(short,)s 8846(just)s 9232(a)s
+9379(test)s 9751(section,)s 6233 -8570(nothing)m 7066(more.)s 153 fnt86
+7617 -8464(a)m 240 fnt86 7785 -8570(This)m 8311(is)s 8571(the)s
+8964(\207rst)s 9436(section.)s 10334(It)s 6233 -8858(too)m 6610(is)s
+6840(v)s 3(ery)k 7333(short,)s 7942(just)s 8358(a)s
+8535(test)s 8937(section,)s 9745(nothing)s 6233 -9146(more.)m 6853(This)s
+7347(is)s 7575(the)s 7936(\207rst)s 8376(section.)s 9242(It)s
+9456(too)s 9831(is)s 10059(v)s 3(ery)k 6233 -9434(short,)m
+6840(just)s 7254(a)s 7429(test)s 7829(section,)s 8635(nothing)s
+9436(more.)s 10056(This)s 6233 -9722(is)m 6471(the)s 6842(\207rst)s
+7292(section.)s 8168(It)s 8392(too)s 8777(is)s 9015(v)s 3(ery)k
+9516(short,)s 10133(just)s 6233 -10010(a)m 6407(test)s 6806(section,)s
+7611(nothing)s 8411(more.)s 9030(This)s 9523(is)s 9750(the)s
+10110(\207rst)s 6233 -10298(section.)m 7071(It)s 7257(too)s 7604(is)s
+7804(v)s 3(ery)k 8267(short,)s 8846(just)s 9232(a)s
+9379(test)s 9751(section,)s 6233 -10586(nothing)m 7076(more.)s 7738(This)s
+8274(is)s 8544(the)s 8947(\207rst)s 9429(section.)s 10337(It)s
+6233 -10874(too)m 6610(is)s 6840(v)s 3(ery)k 7333(short,)s
+7942(just)s 8358(a)s 8535(test)s 8937(section,)s 9745(nothing)s
+6233 -11162(more.)m 240 fnt88 6233 -11761(1.1)m 6533(.)s 6713(The)s
+7172(\207rst)s 7643(subsection)s 240 fnt86 6713 -12192(This)m 7244(is)s
+7509(the)s 7907(\207rst)s 8384(subsection,)s 9560(and)s 10012(what)s
+6233 -12480(is)m 6518(more)s 7135(it)s 7393(has)s 7838(sub-subsections)s
+9479(which)s 10190(are)s 6233 -12768(starting)m 7009(no)s 6(w)k 15(.)k
+240 fnt87 6233 -13415(The)m 6652(\207r)s 2(st)k 7082(sub-subsection)s
+240 fnt86 6713 -13893(This)m 7222(is)s 7465(the)s 7841(\207rst)s
+8296(sub-subsection.)s 9922(There)s 6233 -14181(will)m 6664(be)s 6950(a)s
+7116(second)s 7841(one)s 8247(in)s 8493(a)s 8659(minute.)s
+gsave
+6233 -14668 translate
+240 fnt86 LoutExtColour setrgbcolor 1134 0 0 0 240 288 60 LoutGraphic
+gsave
+0 0 moveto xsize 0 lineto stroke
+grestore
+
+grestore
+122 fnt86 LoutExtColour setrgbcolor 6233 -14836(a)m 192 fnt86 6287 -14921(This)m
+6687(is)s 6874(the)s 7168(\207rst)s 7524(footnote,)s 8270(anchored)s
+9032(to)s 4(w)k 1(ards)k 9692(the)s 9986(end)s
+10323(of)s 6233 -15151(the)m 6530(\207rst)s 6889(section.)s 7590(It)s
+7769(should)s 8343(appear)s 8916(at)s 9117(the)s 9414(bottom)s
+10020(of)s 10242(the)s 6233 -15381(page.)m 6739(Let')s 10(s)k
+7169(hope)s 7590(it)s 7744(comes)s 8281(out)s 8574(right.)s
+
+grestore
+
+pgsave restore
+showpage
+
+%%Trailer
+%%DocumentNeededResources: font Times-Roman
+%%+ font Times-Italic
+%%+ font Times-Bold
+%%DocumentSuppliedResources: procset LoutStartUp
+%%+ encoding vec1
+%%Pages: 1
+%%EOF
diff --git a/doc/user/equ b/doc/user/equ
new file mode 100644
index 0000000..7a87fdb
--- /dev/null
+++ b/doc/user/equ
@@ -0,0 +1,28 @@
+@Chapter
+   @Title { Equations }
+   @Tag { equations }
+@Begin
+@LP
+This chapter explains how to produce mathematical formulas in Lout,
+equations. @Index { equations }
+mathematics. @Index mathematics
+eq. @Index @Code "@Eq"
+using the @Code "@Eq" symbol like this:
+@ID @Code {
+"@Eq { big int supp 1 on 0 ` dx over sqrt {1 - x sup 2} = pi over 2 }"
+}
+This example produces
+@ID @Eq { big int supp 1 on 0 ` dx over sqrt {1 - x sup 2} = pi over 2 }
+The @Code "@Eq" symbol looks after all the details of spacing for
+you, and it provides several hundred mathematical symbols.
+@BeginSections
+@Include { equ_intr }
+@Include { equ_symb }
+@Include { equ_vert }
+@Include { equ_spac }
+@Include { equ_disp }
+@Include { equ_defs }
+@Include { equ_summ }
+@Include { equ_tequ }
+@EndSections
+@End @Chapter
diff --git a/doc/user/equ_defs b/doc/user/equ_defs
new file mode 100644
index 0000000..0e38da7
--- /dev/null
+++ b/doc/user/equ_defs
@@ -0,0 +1,53 @@
+@Section
+   @Title { Defining new equation formatting symbols }
+@Begin
+@PP
+Whenever you type particular equations or parts of equations repeatedly,
+you can save time by using definitions.  Definitions are the subject of
+Section {@NumberOf definitions}, so here we will just give a few examples
+of their use in equation formatting.
+@PP
+Suppose for example that @OneCol @Eq { p sub i ` log sub 2 ` p sub i }
+occurs frequently in your document.  Then
+@ID @Code "def epi { p sub i ` log sub 2 ` p sub i }"
+makes the symbol @Code "epi" stand for the object between the braces:
+@ID {
+@Code "big sum from i=1 to n ` epi"
+|7ct
+@Eq { big sum from i=1 to n ` epi }
+}
+Parameters are very useful when parts of the symbol vary:
+@ID @OneRow @Code {
+"def ep"
+"   right x"
+"{ p sub x ` log sub 2 ` p sub x"
+"}"
+}
+The parameter @Code x will be replaced by the object just to the right
+of {@Code "ep"}:
+@ID {
+@Code {
+"big sum from i=1 to k ` ep i +"
+"big sum from j=k+1 to n ep j"
+}
+||7ct
+@Eq {
+big sum from i=1 to k ` ep i +
+big sum from j=k+1 to n ep j
+}
+}
+The precedence of the symbols you define will be 100 by default.
+@PP
+To make the symbols of @Code "@Eq" available within such definitions,
+each must be preceded by {@Code "import @Eq"}.  As explained in Section
+{@NumberOf definitions}, the definitions go into a file called
+{@Code "mydefs"}, which might then look like this:
+@ID @OneRow @Code {
+"import @Eq"
+"def epi { p sub i ` log sub 2 ` p sub i }"
+""
+"import @Eq"
+"def ep right x { p sub x ` log sub 2 ` p sub x }"
+}
+Use of @Code "epi" and @Code "ep" outside @Code "@Eq" will cause an error.
+@End @Section
diff --git a/doc/user/equ_disp b/doc/user/equ_disp
new file mode 100644
index 0000000..0167b8d
--- /dev/null
+++ b/doc/user/equ_disp
@@ -0,0 +1,126 @@
+@Section
+   @Title { Displaying equations }
+   @Tag { mathdisplays }
+@Begin
+@PP
+The result of the @Code "@Eq" symbol is an object which, according to the
+displayed.equations @Index { displayed equations }
+golden rule (Section {@NumberOf objects}), may appear anywhere:  inside
+a paragraph, inside a table, and so on.  In particular, equations are
+often displayed using the @Code "@CentredDisplay" or @Code "@IndentedDisplay"
+symbols from Section {@NumberOf displays}:
+@ID @Code "@IndentedDisplay @Eq { ... }"
+Now displayed equations are often numbered, and often aligned with one
+another on their equals signs.  For this there are special display
+symbols which are the the subject of this section.  These symbols can
+align and number any display at all, but since in practice they seem to
+be used only with equations, we discuss them here rather than in
+Section {@NumberOf displays} where they really belong.
+@PP
+Let's begin by looking at a first example of a numbered display:
+aligned.displays @Index { aligned displays }
+aligned.equations @Index { aligned equations }
+numbered.displays @Index { numbered displays }
+numbered.equations @Index { numbered equations }
+@BeginAlignedDisplays
+@CentredAlignedNumberedDisplay
+  @Tag { fibeq }
+@Eq { F sub n ^= F sub {n-1} + F sub {n-2} }
+After the display we might have some more text for a while, and then
+we might want a second display, aligned on its equals sign with the
+first, and also numbered in sequence with it:
+@CentredAlignedNumberedDisplay
+@Eq { F sub n - F sub {n-1} ^= F sub {n-2} }
+@EndAlignedDisplays
+Notice that the two displays are centred as a block as well as
+aligned.  Altogether there are four ways in which displays vary:
+@BL
+@LI { A display can be raw or not raw (see below); }
+@LI { It can be a {@Code "@Display"}, {@Code "@LeftDisplay"},
+{@Code "@IndentedDisplay"}, {@Code "@QuotedDisplay"},
+{@Code "@CentredDisplay"}, {@Code "@CenteredDisplay"},
+or {@Code "@RightDisplay"}; }
+@LI { It can be aligned or not aligned; }
+@LI { It can be numbered or not numbered. }
+@EL
+All possible combinations are allowed.  The display that has everything
+is called
+@ID @Code "@RawCentredAlignedNumberedDisplay"
+By leaving out some or all of {@Code Raw}, {@Code Aligned}, and
+{@Code Numbered}, and by changing or leaving out {@Code Centred},
+we get all these combinations.  Here
+numbereddisplay. @Index @Code "@NumberedDisplay"
+aligneddisplay. @Index @Code "@AlignedDisplay"
+then is how the two displays given earlier were made:
+@ID @OneRow @Code {
+"... a first example of a numbered display:"
+"@BeginAlignedDisplays"
+"@CentredAlignedNumberedDisplay"
+"  @Tag { fibeq }"
+"@Eq { F sub n ^= F sub { n-1 } + F sub { n-2 } }"
+"After the display we might ... numbered in sequence with it:"
+"@CentredAlignedNumberedDisplay @Eq { F sub n - F sub { n-1 } ^= F sub { n-2 } }"
+"@EndAlignedDisplays"
+"Notice that the two displays are centred ..."
+}
+All numbered displays have an optional @Code "@Tag" option which is
+used for cross referencing (see Section {@NumberOf cross}).  Alignment
+and numbering work quite independently; they don't have to start or end
+together, and there can be non-aligned and non-numbered displays among
+the others.
+@PP
+When aligned displays are used, it is necessary to indicate where the
+aligned group begins and ends, by placing @Code "@BeginAlignedDisplays"
+beginaligneddisplays @Index @Code "@BeginAlignedDisplays"
+endaligneddisplays @Index @Code "@EndAlignedDisplays"
+just before the first, and @Code "@EndAlignedDisplays" just after the
+last.  The alignment points are indicated by preceding them by the
+symbol {@Code "^"}, so you aren't restricted to aligning at equals
+signs.  @Code "@BeginAlignedDisplays" and @Code "@EndAlignedDisplays"
+cannot span across several sections or subsections:  the equations
+aligned by them must lie within a single large-scale structure symbol.
+@PP
+In our example of aligned and numbered displays, the two displays
+were separated by some ordinary text.  Very often, though, aligned
+displays follow directly after each other.  This is a problem, because
+if you have one display directly following another there will be too
+much vertical space between them.  This problem was mentioned in
+Section {@NumberOf displays}, and the recommended solution was to
+use a list.  However, there are no aligned or numbered (in this sense)
+lists.
+@PP
+To solve this problem, each display symbol has a `raw' version, which
+means that no space is inserted above or below the display.  Instead,
+raw.displays @Index { raw displays }
+you must insert it yourself using paragraph symbols:
+@ID @OneRow @Code {
+"preceding text"
+"@DP"
+"@RawAlignedDisplay @Eq { ... }"
+"@DP"
+"@RawAlignedNumberedDisplay @Eq { ... }"
+"@DP"
+"following text"
+}
+You get the right spacing by placing {@Code "@DP"} symbols before,
+between, and after each display; and you get to use the specialized
+displays that you need.  Raw and non-raw displays may be numbered and
+aligned together.
+@PP
+Numbered displays are numbered automatically.  Depending on where in
+the document they appear, the number might include a chapter number
+or section number, etc.  This is controlled by options in the setup
+file; for example, setting @Code "@ChapterNumInDisplays" to @Code Yes
+ensures that numbered displays will be numbered afresh at the beginning
+of each chapter, and that the number will include a chapter number.  There
+is also a @Code "@DisplayNumStyle" option which controls the style of
+displays; the default value, {@Code "(num)"}, encloses the number in
+parentheses as is conventional when numbering equations.
+@PP
+Every display symbol has an abbreviated form consisting of @Code "@"
+followed by its capital letters only.  For example,
+@Code "@BeginAlignedDisplays" may be abbreviated to {@Code "@BAD"}, and
+the display that has everything to {@Code "@RCAND"}.  Owing to an
+unfortunate clash between the initial letters of `raw' and `right',
+@Code "@RightDisplay" and the other right displays have no abbreviations.
+@End @Section
diff --git a/doc/user/equ_intr b/doc/user/equ_intr
new file mode 100644
index 0000000..882aaff
--- /dev/null
+++ b/doc/user/equ_intr
@@ -0,0 +1,61 @@
+@Section
+   @Title { Introduction }
+@Begin
+@PP
+The Lout definitions for the @Code "@Eq" symbol are accessed via a setup
+file called {@Code "eq"}, which you must include at the start of your
+document if
+eq.file @Index { @Code "eq" file }
+you want equations, like this:
+@ID @OneRow @Code {
+"@SysInclude { tbl }"
+"@SysInclude { eq }"
+"@SysInclude { doc }"
+"@Doc @Text @Begin"
+"..."
+"@End @Text"
+}
+This shows what to do if you want both tables and equations, but you
+may leave out the line for tables if you don't want them.  Setup files
+for specialized packages, such as like {@Code "tab"} and {@Code "eq"},
+are best included before the main setup file, but may be included in
+any order.
+@PP
+With the @Code "eq" file included, you may write
+eq. @Index { @Code "@Eq" }
+@ID @Code "@Eq { ... }"
+at any point in your document, and the symbols of @Code "@Eq" will be
+available between the braces.  Any symbols available outside continue
+to be available inside, which means that equations may be freely mixed
+with other symbols, without restriction.
+@PP
+Equations may appear within a paragraph of text, or they may be
+displayed.  {@Code "@Eq"}'s job is to produce an object containing the
+equation; it neither knows nor cares where this equation goes.
+@PP
+To get an equation within a paragraph, simply place @Code "@Eq { ... }"
+at the desired point.  To make the optimal paragraph breaker work hard to
+arrange the paragraph so that the equation does not spread over two
+lines, use {@Code "@OneCol @Eq { ... }"}.  This is needed so frequently
+that a symbol @Code "@E" is defined in @Code "eq" along with @Code "@Eq"
+e. @Index { @Code "@E" }
+which is an abbreviation for {@Code "@OneCol @Eq"}.
+@PP
+To display an equation, use a display symbol like @Code "@IndentedDisplay"
+or @Code "@CentredDisplay" (Section {@NumberOf displays}).  For example,
+@ID @Code "@CentredDisplay @Eq { int supp pi on 0 sin ` x = 0 }"
+produces
+@CentredDisplay @Eq { int supp pi on 0 sin ` x = 0 }
+There are also symbols for aligned and numbered displays, which are
+very commonly used with equations.  These symbols are the subject of
+Section {@NumberOf mathdisplays}.
+@PP
+In this chapter we show the Lout input at the left, and its
+result at the right:
+@ID {
+@Code "@Eq { {x sup 2 + y sup 2} over 2 }"
+|7ct
+@Eq { {x sup 2 + y sup 2} over 2 }
+}
+Subsequent examples will omit the enclosing {@Code "@Eq { ... }"}.
+@End @Section
diff --git a/doc/user/equ_spac b/doc/user/equ_spac
new file mode 100644
index 0000000..2a79fb1
--- /dev/null
+++ b/doc/user/equ_spac
@@ -0,0 +1,81 @@
+@Section
+   @Title { Spacing }
+@Begin
+@PP
+There is a basic rule governing the use of white space characters (space,
+tab, and newline) in the input to Lout:  white space between two objects
+affects the result; white space between a symbol and its parameter does
+not.  This is explained at length in Section {@NumberOf spaces}.
+@PP
+Although this rule is just right most of the time, it is not adequate
+for equation formatting.  Getting the horizontal spacing right in
+equations is a very fiddly business, involving four different sizes of
+space (zero, thin, medium, and thick), and different rules for spacing
+within superscripts and subscripts to those applying outside, according
+to a leading authority @Cite { $knuth1984tex }.  {@Code "@Eq"} therefore
+takes the spacing decisions upon itself, and consequently chooses to
+ignore all white space in its input, even between two objects.  (The
+simplest way to restore the effect of white space to part of an equation
+is to enclose that part in a @Code "@Font" symbol.)
+@PP
+Every symbol provided by {@Code "@Eq"} has a @I {full name}, which
+full.name @Index { full name of equation symbol }
+denotes the symbol without any space attached.  Many symbols also
+have a @I {short name}, which denotes the same symbol with what
+short.name @Index { short name of equation symbol }
+{@Code "@Eq"} considers to be an appropriate amount of space for that
+symbol attached to it.  For example, @Eq { lessequal } has full name
+@Code lessequal and short name {@Code "<="}:
+@IL
+@LI {
+@Code "a lessequal b"
+|7ct
+@Eq { a lessequal b }
+}
+@LI {
+@Code "a <= b"
+|7ct
+@Eq { a <= b }
+}
+@EL
+{@Code "@Eq"} puts a thick space around relation symbols like {@Code "<="},
+relations @Index { relation symbols in equations }
+a medium space around binary operator symbols like {@Code "+"}, and a thin
+binary.op @Index { binary operators in equations }
+space after punctuation symbols (@Code ";" and {@Code ","}); except that
+punctuation @Index { punctuation in equations }
+in places where the symbols appear in a smaller size (superscripts,
+subscripts, etc.), these spaces are omitted.  No other horizontal space
+is ever inserted.
+@PP
+The short names have been carefully designed to produce good-looking
+mathematics most of the time.  It is best to rely on them in the first
+instance and only think about spacing when the result is not pleasing.  In
+that case, {@Code "@Eq"}'s space can be removed by using the full names,
+and thin, medium and thick space can be added using the following symbols:
+@ID @Tab
+    vmargin { 0.5vx }
+    @Fmta { @Col A ! @Col B }
+{
+@Rowa
+  A { @Code "`" }
+  B { {@Code "0.18f"}  ({@Code "0.018f"} in subscripts, etc.) }
+@Rowa
+  A { @Code "``" }
+  B { {@Code "0.24f"}  ({@Code "0.024f"} in subscripts, etc.) }
+@Rowa
+  A { @Code "```" }
+  B { {@Code "0.30f"}  ({@Code "0.030f"} in subscripts, etc.) }
+}
+where @Code "1f" is the current font size.  These symbols have low
+precedence.  The @Code "&" symbol from raw Lout is also available;
+the @Code "s" unit has value 0 and so is not very useful, but one can
+write @Code "&2m" for example for a two em space.  The full names are
+tedious to remember, so {@Code "@Eq"} provides a @Code "non" symbol
+non. @Index { @Code "non" in equations }
+which removes spaces from its right parameter; thus @Code "non <=" is
+equivalent to {@Code "lessequal"}.  There are also {@Code "rel"},
+{@Code "bin"}, and {@Code "punct"} symbols for telling {@Code "@Eq"}
+to add space to the following symbol as though it was a relation symbol,
+binary operator, or punctuation symbol.
+@End @Section
diff --git a/doc/user/equ_summ b/doc/user/equ_summ
new file mode 100644
index 0000000..bcfbeb3
--- /dev/null
+++ b/doc/user/equ_summ
@@ -0,0 +1,721 @@
+@Section
+   @Title { Summary }
+@Begin
+@PP
+This section is a complete list of the symbols provided by
+{@Code "@Eq"}.  We divide them into auxiliary, parameterized, short names
+(further divided into relations, binary operators, and punctuation),
+and full names.  The auxiliary symbols are:
+@ID @Tab
+     vmargin { 0.5vx }
+     @Fmta { @Col A ! @Col B }
+{
+@Rowa
+    A { @Code "`" }
+    B { Thin space }
+@Rowa
+    A { @Code "``" }
+    B { Medium space }
+@Rowa
+    A { @Code "```" }
+    B { Thick space }
+@Rowa
+    A { @Code "bin x" }
+    B { Treat @Code x as a binary operator }
+@Rowa
+    A { @Code "rel x" }
+    B { Treat @Code x as a relation }
+@Rowa
+    A { @Code "punct x" }
+    B { Treat @Code x as a punctuation symbol }
+@Rowa
+    A { @Code "non x" }
+    B { Remove spaces normally put into @Code x }
+@Rowa
+    A { @Code "vctr x" }
+    B { Centre @Code x vertically }
+@Rowa
+    A { @Code "big x" }
+    B { Make @Code x larger }
+}
+Here are all the parameterized symbols, shown in groups of equal
+precedence, with the precedence itself at right:
+@ID @OneRow lines @Break {
+@Code "matrix pmatrix bmatrix brmatrix fmatrix cmatrix amatrix not" (100)
+@Code "dot dotdot hat tilde vec dyad overbar underbar" (62)
+@Code "sup sub tsub supp" (60)   @Code "on ton" (61)
+@Code "from to widefrom wideto" (58)
+@Code "sqrt root" (56)
+@Code "over frac" (54)
+@Code "col lcol ccol rcol mcol" (52)
+@Code "row axisrow" (50)
+# @Code "above labove cabove rabove mabove" (52)
+# @Code "nextcol" (50)
+}
+See Section {@NumberOf symbols} for examples of matrices.  Here are some
+examples of the other symbols:
+@IL
+
+@LI {
+@Code "x dot"
+|7ct
+@Eq { x dot }
+}
+
+@LI {
+@Code "x dotdot"
+|7ct
+@Eq { x dotdot }
+}
+
+@LI {
+@Code "x hat"
+|7ct
+@Eq { x hat }
+}
+
+@LI {
+@Code "x tilde"
+|7ct
+@Eq { x tilde }
+}
+
+@LI {
+@Code "x vec"
+|7ct
+@Eq { x vec }
+}
+
+@LI {
+@Code "x dyad"
+|7ct
+@Eq { x dyad }
+}
+
+@LI {
+@Code "x+y overbar"
+|7ct
+@Eq { x+y overbar }
+}
+
+@LI {
+@Code "x+y underbar"
+|7ct
+@Eq { x+y underbar }
+}
+
+@EL
+These marks are centred over the preceding object, except the last two
+which are extended to the width of the object.
+@IL
+
+@LI {
+@Code "a sup b"
+|7ct
+@Eq {a sup b}
+}
+
+@LI {
+@Code "a sub b"
+|7ct
+@Eq {a sub b}
+}
+
+@LI {
+@Code "W tsub b"
+|7ct
+@Eq {W tsub b}
+}
+
+@LI {
+@Code "a supp b on c"
+|7ct
+@Eq {a supp b on c}
+}
+
+@LI {
+@Code "W supp b ton c"
+|7ct
+@Eq {W supp b ton c}
+}
+
+@EL
+Note that @Code "supp" and @Code "on" (or {@Code "ton"}) must be used
+together as shown; @Code "tsub" and @Code "ton" are exactly like
+@Code "sub" and @Code "on" except that the subscript is tucked in.
+@IL
+
+@LI {
+@Code "big sum from i"
+|7ct
+@Eq {big sum from i}
+}
+
+@LI {
+@Code "big prod to j"
+|7ct
+@Eq {big prod to j}
+}
+
+@LI {
+@Code { "{a, ... , z} widefrom"
+"{90d @Rotate blbrace}" }
+|7ct
+@Eq { {a, ... , z} widefrom {90d @Rotate blbrace} }
+}
+
+@LI {
+@Code "{a, ... , z} wideto minus"
+|7ct
+@Eq { {a, ... , z} wideto minus }
+}
+
+@EL
+@Code "widefrom" and @Code "wideto" are like @Code "from" and
+@Code "to" except that they horizontally scale the right parameter
+to the width of the left.
+@IL
+
+@LI {
+@Code "sqrt {x over y}"
+|7ct
+@Eq { sqrt {x over y} }
+}
+
+@LI {
+@Code "3 root {x over y}"
+|7ct
+@Eq { 3 root {x over y} }
+}
+
+@EL
+The left parameter of @Code "root" may be any object.  Here are
+four ways to denote division:
+@IL
+
+@LI {
+@Code "2 over 3"
+|7ct
+@Eq { 2 over 3 }
+}
+
+@LI {
+@Code "2 frac 3"
+|7ct
+@Eq { 2 frac 3 }
+}
+
+@LI {
+@Code "2 div 3"
+|7ct
+@Eq { 2 div 3 }
+}
+
+@LI {
+@Code "2 slash 3"
+|7ct
+@Eq { 2 slash 3 }
+}
+
+@EL
+The @Code "div" symbol is a binary operator (see below), and
+@Code "slash" is the full name for the @Code "/" character from
+the Adobe Symbol font.  You can't use @Code "/" itself, because
+it is one of Lout's special symbols.
+@PP
+The following short names define relations (that is, they have a thick
+space on each side):
+@DP
+ragged @Break {
+"<"		@Dbl @Eq {  <			}
+">"		@Dbl @Eq {  >			}
+"="		@Dbl @Eq {  =			}
+"<="		@Dbl @Eq {  <=			}
+"prec"		@Dbl @Eq {  prec		}
+"preceq"	@Dbl @Eq {  preceq		}
+"<<"		@Dbl @Eq {  <<			}
+"subset"	@Dbl @Eq {  subset		}
+"subseteq"	@Dbl @Eq {  subseteq		}
+"sqsubseteq"	@Dbl @Eq {  sqsubseteq		}
+"in"		@Dbl @Eq {  in			}
+"vdash"		@Dbl @Eq {  vdash		}
+"smile"		@Dbl @Eq {  smile		}
+"frown"		@Dbl @Eq {  frown		}
+">="		@Dbl @Eq {  >=			}
+"succ"		@Dbl @Eq {  succ		}
+"succeq"	@Dbl @Eq {  succeq		}
+">>"		@Dbl @Eq {  >>			}
+"supset"	@Dbl @Eq {  supset		}
+"supseteq"	@Dbl @Eq {  supseteq		}
+"sqsupseteq"	@Dbl @Eq {  sqsupseteq		}
+"ni"		@Dbl @Eq {  ni			}
+"dashv"		@Dbl @Eq {  dashv		}
+"mid"		@Dbl @Eq {  mid			}
+"parallel"	@Dbl @Eq {  parallel		}
+"=="		@Dbl @Eq {  ==			}
+"~"		@Dbl @Eq {  ~			}
+"-~"		@Dbl @Eq {  -~			}
+"asymp"		@Dbl @Eq {  asymp		}
+"~~"		@Dbl @Eq {  ~~			}
+"=~"		@Dbl @Eq {  =~			}
+"bowtie"	@Dbl @Eq {  bowtie		}
+"propto"	@Dbl @Eq {  propto		}
+"models"	@Dbl @Eq {  models		}
+"doteq"		@Dbl @Eq {  doteq		}
+"perp"		@Dbl @Eq {  perp		}
+"notsub"	@Dbl @Eq {  notsub		}
+"notin"		@Dbl @Eq {  notin		}
+"!="		@Dbl @Eq {  !=			}
+"<->"		@Dbl @Eq {  <->			}
+"<--"		@Dbl @Eq {  <--			}
+"-->"		@Dbl @Eq {  -->			}
+"up"		@Dbl @Eq {  up			}
+"down"		@Dbl @Eq {  down		}
+"<=>"		@Dbl @Eq {  <=>			}
+"<=="		@Dbl @Eq {  <==			}
+"==>"		@Dbl @Eq {  ==>			}
+"dblup"		@Dbl @Eq {  dblup		}
+"dbldown"	@Dbl @Eq {  dbldown		}
+":"		@Dbl @Eq {  :			}
+"::"		@Dbl @Eq {  ::			}
+":="		@Dbl @Eq {  :=			}
+}
+@DP
+These can be negated by preceding them with {@Code "not"}, as in
+negation. @Index { negation of equation symbols }
+{@Code "not =="}, for example, which yields {@Eq { not == }}.  The
+following short names define binary operators (medium space on each side):
+@DP
+ragged @Break {
+"+"		@Dbl @Eq {  +			}
+"-"		@Dbl @Eq {  -			}
+"+-"		@Dbl @Eq {  +-			}
+"-+"		@Dbl @Eq {  -+			}
+"setminus"	@Dbl @Eq {  setminus		}
+"cdot"		@Dbl @Eq {  cdot		}
+"times"		@Dbl @Eq {  times		}
+"*"		@Dbl @Eq {  *			}
+"circ"		@Dbl @Eq {  circ		}
+"div"		@Dbl @Eq {  div			}
+"cap"		@Dbl @Eq {  cap			}
+"cup"		@Dbl @Eq {  cup			}
+"uplus"		@Dbl @Eq {  uplus		}
+"sqcap"		@Dbl @Eq {  sqcap		}
+"sqcup"		@Dbl @Eq {  sqcup		}
+"triangleleft"	@Dbl @Eq {  triangleleft	}
+"triangleright"	@Dbl @Eq {  triangleright	}
+"wr"		@Dbl @Eq {  wr			}
+"bigcirc"	@Dbl @Eq {  bigcirc		}
+"bigtriangleup"	@Dbl @Eq {  bigtriangleup	}
+"bigtriangledown"@Dbl @Eq {  bigtriangledown	}
+"vee"		@Dbl @Eq {  vee			}
+"wedge"		@Dbl @Eq {  wedge		}
+"oplus"		@Dbl @Eq {  oplus		}
+"ominus"	@Dbl @Eq {  ominus		}
+"otimes"	@Dbl @Eq {  otimes		}
+"oslash"	@Dbl @Eq {  oslash		}
+"odot"		@Dbl @Eq {  odot		}
+"dagger"	@Dbl @Eq {  dagger		}
+"daggerdbl"	@Dbl @Eq {  daggerdbl		}
+"amalg"		@Dbl @Eq {  amalg		}
+}
+@DP
+The following names define arrow symbols (no extra space):
+@DP
+ragged @Break {
+"leftarrow"		@Dbl @Eq {  leftarrow			}
+"longleftarrow"		@Dbl @Eq {  longleftarrow		}
+"dblleftarrow"		@Dbl @Eq {  dblleftarrow		}
+"dbllongleftarrow"	@Dbl @Eq {  dbllongleftarrow		}
+"rightarrow"		@Dbl @Eq {  rightarrow			}
+"longrightarrow"	@Dbl @Eq {  longrightarrow		}
+"dblrightarrow"		@Dbl @Eq {  dblrightarrow		}
+"dbllongrightarrow"	@Dbl @Eq {  dbllongrightarrow		}
+"leftrightarrow"	@Dbl @Eq {  leftrightarrow		}
+"longleftrightarrow"	@Dbl @Eq {  longleftrightarrow		}
+"dblleftrightarrow"	@Dbl @Eq {  dblleftrightarrow		}
+{ 1.15i @Wide @HScale "dbllongleftrightarrow" } @Dbl @Eq {  dbllongleftrightarrow	}
+"mapsto"		@Dbl @Eq {  mapsto			}
+"longmapsto"		@Dbl @Eq {  longmapsto			}
+"hookleftarrow"		@Dbl @Eq {  hookleftarrow		}
+"hookrightarrow"	@Dbl @Eq {  hookrightarrow		}
+"leadsto"		@Dbl @Eq {  leadsto			}
+"leftharpoonup"		@Dbl @Eq {  leftharpoonup		}
+"rightharpoonup"	@Dbl @Eq {  rightharpoonup		}
+"leftharpoondown"	@Dbl @Eq {  leftharpoondown		}
+"rightharpoondown"	@Dbl @Eq {  rightharpoondown		}
+"rightleftharpoons"	@Dbl @Eq {  rightleftharpoons		}
+"uparrow"		@Dbl @Eq {  uparrow			}
+"dbluparrow"		@Dbl @Eq {  dbluparrow			}
+"downarrow"		@Dbl @Eq {  downarrow			}
+"dbldownarrow"		@Dbl @Eq {  dbldownarrow		}
+"updownarrow"		@Dbl @Eq {  updownarrow			}
+"dblupdownarrow"	@Dbl @Eq {  dblupdownarrow		}
+"nearrow"		@Dbl @Eq {  nearrow			}
+"searrow"		@Dbl @Eq {  searrow			}
+"swarrow"		@Dbl @Eq {  swarrow			}
+"nwarrow"		@Dbl @Eq {  nwarrow			}
+}
+@DP
+The following names define punctuation symbols (thin space on the
+right-hand side):
+@DP
+ragged @Break {
+";"		@Dbl @Eq {  ;			}
+","		@Dbl @Eq {  ,			}
+"col"		@Dbl @Eq {  col			}
+}
+@DP
+The following symbols are used in ways typified by the large sum and
+product symbols.  In display equations they should be preceded by the
+@Code "big" symbol:
+@DP
+ragged @Break {
+"sum"		@Dbl @Eq {  sum			}
+"prod"		@Dbl @Eq {  prod		}
+"coprod"	@Dbl @Eq {  coprod		}
+@LP
+"int"		@Dbl @Eq {  int			}
+"oint"		@Dbl @Eq {  oint		}
+"bcap"		@Dbl @Eq {  bcap		}
+@LP
+"bcup"		@Dbl @Eq {  bcup		}
+"bvee"		@Dbl @Eq {  bvee		}
+"bwedge"	@Dbl @Eq {  bwedge		}
+@LP
+"bodot"		@Dbl @Eq {  bodot		}
+"botimes"	@Dbl @Eq {  botimes		}
+"boplus"	@Dbl @Eq {  boplus		}
+@LP
+"buplus"	@Dbl @Eq {  buplus		}
+}
+@DP
+The following symbols are defined so that they will appear in Roman,
+as is conventional for them in equations:
+@DP
+ragged @Break {
+"arccos"	@Dbl @Eq {  arccos		}
+"arcsin"	@Dbl @Eq {  arcsin		}
+"arctan"	@Dbl @Eq {  arctan		}
+"arg"		@Dbl @Eq {  arg			}
+"cos"		@Dbl @Eq {  cos			}
+"cosh"		@Dbl @Eq {  cosh		}
+"cot"		@Dbl @Eq {  cot			}
+"coth"		@Dbl @Eq {  coth		}
+"csc"		@Dbl @Eq {  csc			}
+"deg"		@Dbl @Eq {  deg			}
+"det"		@Dbl @Eq {  det			}
+"dim"		@Dbl @Eq {  dim			}
+"exp"		@Dbl @Eq {  exp			}
+"gcd"		@Dbl @Eq {  gcd			}
+"hom"		@Dbl @Eq {  hom			}
+"inf"		@Dbl @Eq {  inf			}
+"ker"		@Dbl @Eq {  ker			}
+"lg"		@Dbl @Eq {  lg			}
+"lim"		@Dbl @Eq {  lim			}
+"liminf"	@Dbl @Eq {  liminf		}
+"limsup"	@Dbl @Eq {  limsup		}
+"ln"		@Dbl @Eq {  ln			}
+"log"		@Dbl @Eq {  log			}
+"max"		@Dbl @Eq {  max			}
+"min"		@Dbl @Eq {  min			}
+"Pr"		@Dbl @Eq {  Pr			}
+"sec"		@Dbl @Eq {  sec			}
+"sin"		@Dbl @Eq {  sin			}
+"sinh"		@Dbl @Eq {  sinh		}
+"supr"		@Dbl @Eq {  supr		}
+"tan"		@Dbl @Eq {  tan			}
+"tanh"		@Dbl @Eq {  tanh		}
+"mod"		@Dbl @Eq {  mod			}
+}
+@DP
+The following symbols are also defined to ensure that they will appear
+in Roman:
+@DP
+ragged @Break {
+"0"		@Dbl @Eq {  0			}
+"1"		@Dbl @Eq {  1			}
+"2"		@Dbl @Eq {  2			}
+"3"		@Dbl @Eq {  3			}
+"4"		@Dbl @Eq {  4			}
+"5"		@Dbl @Eq {  5			}
+"6"		@Dbl @Eq {  6			}
+"7"		@Dbl @Eq {  7			}
+"8"		@Dbl @Eq {  8			}
+"9"		@Dbl @Eq {  9			}
+"!"		@Dbl @Eq {  !			}
+"?"		@Dbl @Eq {  ?			}
+"%"		@Dbl @Eq {  %			}
+"("		@Dbl @Eq {  (			}
+")"		@Dbl @Eq {  )			}
+"["		@Dbl @Eq {  [			}
+"]"		@Dbl @Eq {  ]			}
+}
+@DP
+The following symbols make good @Code atleft and @Code atright parameters
+of the @Code matrix symbol:
+@LP
+@LP
+ragged @Break {
+"lpar"		@Dbl @Eq {  lpar		}
+"blpar"		@Dbl @Eq {  blpar		}
+"rpar"		@Dbl @Eq {  rpar		}
+"brpar"		@Dbl @Eq {  brpar		}
+"lbrack"	@Dbl @Eq {  lbrack		}
+"blbrack"	@Dbl @Eq {  blbrack		}
+"rbrack"	@Dbl @Eq {  rbrack		}
+"brbrack"	@Dbl @Eq {  brbrack		}
+"lbrace"	@Dbl @Eq {  lbrace		}
+"blbrace"	@Dbl @Eq {  blbrace		}
+"rbrace"	@Dbl @Eq {  rbrace		}
+"brbrace"	@Dbl @Eq {  brbrace		}
+"lfloor"	@Dbl @Eq {  lfloor		}
+"blfloor"	@Dbl @Eq {  blfloor		}
+"rfloor"	@Dbl @Eq {  rfloor		}
+"brfloor"	@Dbl @Eq {  brfloor		}
+"lceil"		@Dbl @Eq {  lceil		}
+"blceil"	@Dbl @Eq {  blceil		}
+"rceil"		@Dbl @Eq {  rceil		}
+"brceil"	@Dbl @Eq {  brceil		}
+"langle"	@Dbl @Eq {  langle		}
+"blangle"	@Dbl @Eq {  blangle		}
+"rangle"	@Dbl @Eq {  rangle		}
+"brangle"	@Dbl @Eq {  brangle		}
+}
+@LP
+@LP
+Here are some miscellaneous symbols:
+@DP
+ragged @Break {
+"hbar"		@Dbl @Eq {  hbar		}
+"Re"		@Dbl @Eq {  Re			}
+"Im"		@Dbl @Eq {  Im			}
+"partial"	@Dbl @Eq {  partial		}
+"infty"		@Dbl @Eq {  infty		}
+"prime"		@Dbl @Eq {  prime		}
+"nabla"		@Dbl @Eq {  nabla		}
+"surd"		@Dbl @Eq {  surd		}
+"top"		@Dbl @Eq {  top			}
+"bot"		@Dbl @Eq {  bot			}
+"dbar"		@Dbl @Eq {  dbar		}
+"triangle"	@Dbl @Eq {  triangle		}
+"backslash"	@Dbl @Eq {  backslash		}
+"forall"	@Dbl @Eq {  forall		}
+"exists"	@Dbl @Eq {  exists		}
+"neg"		@Dbl @Eq {  neg			}
+"circle"	@Dbl @Eq {  circle		}
+"square"	@Dbl @Eq {  square		}
+"ldots"		@Dbl @Eq {  ldots		}
+"cdots"		@Dbl @Eq {  cdots		}
+"vdots"		@Dbl @Eq {  vdots		}
+"ddots"		@Dbl @Eq {  ddots		}
+"del"		@Dbl @Eq {  del			}
+"grad"		@Dbl @Eq {  grad		}
+"..."		@Dbl @Eq {  ...			}
+",...,"		@Dbl @Eq {  ,...,		}
+"half"		@Dbl @Eq {  half		}
+"third"		@Dbl @Eq {  third		}
+"'"		@Dbl @Eq {  '			}
+"empty"		@Dbl @Eq {  empty		}
+}
+@DP
+Finally, here is the long list of full names from the Adobe Symbol font;
+these are the same characters as you get with the @Code "@Sym" symbol
+of Section {@NumberOf characters}, but within equations you don't need
+to type {@Code "@Sym"}:
+@DP
+ragged @Break {
+"space"		@Dbl @Eq {  space		}
+"exclam"	@Dbl @Eq {  exclam		}
+"universal"	@Dbl @Eq {  universal		}
+"numbersign"	@Dbl @Eq {  numbersign		}
+"existential"	@Dbl @Eq {  existential		}
+"percent"	@Dbl @Eq {  percent		}
+"ampersand"	@Dbl @Eq {  ampersand		}
+"suchthat"	@Dbl @Eq {  suchthat		}
+"parenleft"	@Dbl @Eq {  parenleft		}
+"parenright"	@Dbl @Eq {  parenright		}
+"asteriskmath"	@Dbl @Eq {  asteriskmath	}
+"plus"		@Dbl @Eq {  plus		}
+"comma"		@Dbl @Eq {  comma		}
+"minus"		@Dbl @Eq {  minus		}
+"period"	@Dbl @Eq {  period		}
+"slash"		@Dbl @Eq {  slash		}
+"zero"		@Dbl @Eq {  zero		}
+"one"		@Dbl @Eq {  one			}
+"two"		@Dbl @Eq {  two			}
+"three"		@Dbl @Eq {  three		}
+"four"		@Dbl @Eq {  four		}
+"five"		@Dbl @Eq {  five		}
+"six"		@Dbl @Eq {  six			}
+"seven"		@Dbl @Eq {  seven		}
+"eight"		@Dbl @Eq {  eight		}
+"nine"		@Dbl @Eq {  nine		}
+"colon"		@Dbl @Eq {  colon		}
+"semicolon"	@Dbl @Eq {  semicolon		}
+"less"		@Dbl @Eq {  less		}
+"equal"		@Dbl @Eq {  equal		}
+"greater"	@Dbl @Eq {  greater		}
+"question"	@Dbl @Eq {  question		}
+"congruent"	@Dbl @Eq {  congruent		}
+"Alpha"		@Dbl @Eq {  Alpha		}
+"Beta"		@Dbl @Eq {  Beta		}
+"Chi"		@Dbl @Eq {  Chi			}
+"Delta"		@Dbl @Eq {  Delta		}
+"Epsilon"	@Dbl @Eq {  Epsilon		}
+"Phi"		@Dbl @Eq {  Phi			}
+"Gamma"		@Dbl @Eq {  Gamma		}
+"Eta"		@Dbl @Eq {  Eta			}
+"Iota"		@Dbl @Eq {  Iota		}
+"thetaone"	@Dbl @Eq {  thetaone		}
+"Kappa"		@Dbl @Eq {  Kappa		}
+"Lambda"	@Dbl @Eq {  Lambda		}
+"Mu"		@Dbl @Eq {  Mu			}
+"Nu"		@Dbl @Eq {  Nu			}
+"Omicron"	@Dbl @Eq {  Omicron		}
+"Pi"		@Dbl @Eq {  Pi			}
+"Theta"		@Dbl @Eq {  Theta		}
+"Rho"		@Dbl @Eq {  Rho			}
+"Sigma"		@Dbl @Eq {  Sigma		}
+"Tau"		@Dbl @Eq {  Tau			}
+"Upsilon"	@Dbl @Eq {  Upsilon		}
+"sigmaone"	@Dbl @Eq {  sigmaone		}
+"Omega"		@Dbl @Eq {  Omega		}
+"Xi"		@Dbl @Eq {  Xi			}
+"Psi"		@Dbl @Eq {  Psi			}
+"Zeta"		@Dbl @Eq {  Zeta		}
+"bracketleft"	@Dbl @Eq {  bracketleft		}
+"therefore"	@Dbl @Eq {  therefore		}
+"bracketright"	@Dbl @Eq {  bracketright	}
+"perpendicular"	@Dbl @Eq {  perpendicular	}
+"underscore"	@Dbl @Eq {  underscore		}
+"radicalex"	@Dbl @Eq {  radicalex		}
+"alpha"		@Dbl @Eq {  alpha		}
+"beta"		@Dbl @Eq {  beta		}
+"chi"		@Dbl @Eq {  chi			}
+"delta"		@Dbl @Eq {  delta		}
+"epsilon"	@Dbl @Eq {  epsilon		}
+"phi"		@Dbl @Eq {  phi			}
+"gamma"		@Dbl @Eq {  gamma		}
+"eta"		@Dbl @Eq {  eta			}
+"iota"		@Dbl @Eq {  iota		}
+"phione"	@Dbl @Eq {  phione		}
+"kappa"		@Dbl @Eq {  kappa		}
+"lambda"	@Dbl @Eq {  lambda		}
+"mu"		@Dbl @Eq {  mu			}
+"nu"		@Dbl @Eq {  nu			}
+"omicron"	@Dbl @Eq {  omicron		}
+"pi"		@Dbl @Eq {  pi			}
+"theta"		@Dbl @Eq {  theta		}
+"rho"		@Dbl @Eq {  rho			}
+"sigma"		@Dbl @Eq {  sigma		}
+"tau"		@Dbl @Eq {  tau			}
+"upsilon"	@Dbl @Eq {  upsilon		}
+"omegaone"	@Dbl @Eq {  omegaone		}
+"omega"		@Dbl @Eq {  omega		}
+"xi"		@Dbl @Eq {  xi			}
+"psi"		@Dbl @Eq {  psi			}
+"zeta"		@Dbl @Eq {  zeta		}
+"braceleft"	@Dbl @Eq {  braceleft		}
+"bar"		@Dbl @Eq {  bar			}
+"braceright"	@Dbl @Eq {  braceright		}
+"similar"	@Dbl @Eq {  similar		}
+"Upsilonone"	@Dbl @Eq {  Upsilonone		}
+"minute"	@Dbl @Eq {  minute		}
+"lessequal"	@Dbl @Eq {  lessequal		}
+"fraction"	@Dbl @Eq {  fraction		}
+"infinity"	@Dbl @Eq {  infinity		}
+"florin"	@Dbl @Eq {  florin		}
+"club"		@Dbl @Eq {  club		}
+"diamond"	@Dbl @Eq {  diamond		}
+"heart"		@Dbl @Eq {  heart		}
+"spade"		@Dbl @Eq {  spade		}
+"arrowboth"	@Dbl @Eq {  arrowboth		}
+"arrowleft"	@Dbl @Eq {  arrowleft		}
+"arrowup"	@Dbl @Eq {  arrowup		}
+"arrowright"	@Dbl @Eq {  arrowright		}
+"arrowdown"	@Dbl @Eq {  arrowdown		}
+"degree"	@Dbl @Eq {  degree		}
+"plusminus"	@Dbl @Eq {  plusminus		}
+"second"	@Dbl @Eq {  second		}
+"greaterequal"	@Dbl @Eq {  greaterequal	}
+"multiply"	@Dbl @Eq {  multiply		}
+"proportional"	@Dbl @Eq {  proportional	}
+"partialdiff"	@Dbl @Eq {  partialdiff		}
+"bullet"	@Dbl @Eq {  bullet		}
+"divide"	@Dbl @Eq {  divide		}
+"notequal"	@Dbl @Eq {  notequal		}
+"equivalence"	@Dbl @Eq {  equivalence		}
+"approxequal"	@Dbl @Eq {  approxequal		}
+"ellipsis"	@Dbl @Eq {  ellipsis		}
+"arrowvertex"	@Dbl @Eq {  arrowvertex		}
+"arrowhorizex"	@Dbl @Eq {  arrowhorizex	}
+"carriagereturn"@Dbl @Eq {  carriagereturn	}
+"aleph"		@Dbl @Eq {  aleph		}
+"Ifraktur"	@Dbl @Eq {  Ifraktur		}
+"Rfraktur"	@Dbl @Eq {  Rfraktur		}
+"weierstrass"	@Dbl @Eq {  weierstrass		}
+"circlemultiply"@Dbl @Eq {  circlemultiply	}
+"circleplus"	@Dbl @Eq {  circleplus		}
+"emptyset"	@Dbl @Eq {  emptyset		}
+"intersection"	@Dbl @Eq {  intersection	}
+"union"		@Dbl @Eq {  union		}
+"propersuperset"@Dbl @Eq {  propersuperset	}
+"reflexsuperset"@Dbl @Eq {  reflexsuperset	}
+"notsubset"	@Dbl @Eq {  notsubset		}
+"propersubset"	@Dbl @Eq {  propersubset	}
+"reflexsubset"	@Dbl @Eq {  reflexsubset	}
+"element"	@Dbl @Eq {  element		}
+"notelement"	@Dbl @Eq {  notelement		}
+"angle"		@Dbl @Eq {  angle		}
+"gradient"	@Dbl @Eq {  gradient		}
+"registerserif"	@Dbl @Eq {  registerserif	}
+"copyrightserif"@Dbl @Eq {  copyrightserif	}
+"trademarkserif"@Dbl @Eq {  trademarkserif	}
+"product"	@Dbl @Eq {  product		}
+"radical"	@Dbl @Eq {  radical		}
+"dotmath"	@Dbl @Eq {  dotmath		}
+"logicalnot"	@Dbl @Eq {  logicalnot		}
+"logicaland"	@Dbl @Eq {  logicaland		}
+"logicalor"	@Dbl @Eq {  logicalor		}
+"arrowdblboth"	@Dbl @Eq {  arrowdblboth	}
+"arrowdblleft"	@Dbl @Eq {  arrowdblleft	}
+"arrowdblup"	@Dbl @Eq {  arrowdblup		}
+"arrowdblright"	@Dbl @Eq {  arrowdblright	}
+"arrowdbldown"	@Dbl @Eq {  arrowdbldown	}
+"lozenge"	@Dbl @Eq {  lozenge		}
+"angleleft"	@Dbl @Eq {  angleleft		}
+"registersans"	@Dbl @Eq {  registersans	}
+"copyrightsans"	@Dbl @Eq {  copyrightsans	}
+"trademarksans"	@Dbl @Eq {  trademarksans	}
+"summation"	@Dbl @Eq {  summation		}
+"parenlefttp"	@Dbl @Eq {  parenlefttp		}
+"parenleftex"	@Dbl @Eq {  parenleftex		}
+"parenleftbt"	@Dbl @Eq {  parenleftbt		}
+"bracketlefttp"	@Dbl @Eq {  bracketlefttp	}
+"bracketleftex"	@Dbl @Eq {  bracketleftex	}
+"bracketleftbt"	@Dbl @Eq {  bracketleftbt	}
+"bracelefttp"	@Dbl @Eq {  bracelefttp		}
+"braceleftmid"	@Dbl @Eq {  braceleftmid	}
+"braceleftbt"	@Dbl @Eq {  braceleftbt		}
+"braceex"	@Dbl @Eq {  braceex		}
+"angleright"	@Dbl @Eq {  angleright		}
+"integral"	@Dbl @Eq {  integral		}
+"integraltp"	@Dbl @Eq {  integraltp		}
+"integralex"	@Dbl @Eq {  integralex		}
+"integralbt"	@Dbl @Eq {  integralbt		}
+"parenrighttp"	@Dbl @Eq {  parenrighttp	}
+"parenrightex"	@Dbl @Eq {  parenrightex	}
+"parenrightbt"	@Dbl @Eq {  parenrightbt	}
+"bracketrighttp"@Dbl @Eq {  bracketrighttp	}
+"bracketrightex"@Dbl @Eq {  bracketrightex	}
+"bracketrightbt"@Dbl @Eq {  bracketrightbt	}
+"bracerighttp"	@Dbl @Eq {  bracerighttp	}
+"bracerightmid"	@Dbl @Eq {  bracerightmid	}
+"bracerightbt"	@Dbl @Eq {  bracerightbt	}
+}
+@DP
+The names given are the same as Adobe's, as used by the @Code "@Sym"
+symbol, except in a few places where the Adobe name contains a digit,
+which is not possible for a symbol name in Lout.
+@End @Section
diff --git a/doc/user/equ_symb b/doc/user/equ_symb
new file mode 100644
index 0000000..f56eca2
--- /dev/null
+++ b/doc/user/equ_symb
@@ -0,0 +1,357 @@
+@Section
+   @Title { Symbols }
+   @Tag { symbols }
+@Begin
+@PP
+@Code "@Eq" prints characters in the fonts appropriate for mathematics:
+@ID {
+@Code "x - 2"
+|7ct
+@Eq { x-2 }
+}
+Here @Eq { x } is in Italic, @Eq { 2 } is in Roman, and @Eq { minus } is
+from the Symbol font.  The character @Code "-" is a @I symbol which
+stands for @Eq {minus}, and @Code "2" is also a symbol, standing for
+@Eq { 2 }.  @Code "@Eq" includes a vast number of symbols:
+@ID {
+@Code "Omega delta int partial club"
+|7ct
+@Eq { Omega delta int partial club }
+}
+The summary at the end of this chapter has the complete list.
+@PP
+Symbols whose names are made from letters should be separated from each
+other by at least one space or end of line, as was done above, or else
+@Code "@Eq" will become confused:
+@ID {
+@Code "Omegadelta"
+|7ct
+@Eq { Omegadelta }
+}
+Symbols whose names are made from digits and punctuation characters can,
+however, be run together with each other and with symbols made from
+letters:
+@ID {
+@Code "Omega-delta<=2"
+|7ct
+@Eq { Omega-delta<=2 }
+}
+This rule applies throughout Lout (Section {@NumberOf spaces}).
+@PP
+Some symbols join objects together in mathematical ways:
+@ID {
+@Code "x sub 2"
+|7ct
+@Eq { x sub 2 }
+}
+Here the @Code "sub" symbol has taken the object just to its left, and
+sub. @Index { @Code "sub" in equations }
+the object just to its right, and joined them into one object in the
+form of a subscript.  The two objects are called the left and right
+parameters of {@Code "sub"}, and they may be arbitrary Lout objects.
+@PP
+Other symbols of a similar kind include {@Code "sup"} for
+sup. @Index { @Code "sup" in equations }
+superscripting, @Code "over" for built-up fractions, and @Code "from"
+over.eq. @Index { @Code "over" in equations }
+from. @Index { @Code "from" in equations }
+to. @Index { @Code "to" in equations }
+and @Code "to" for the lower and upper limits of sums, products,
+etc.  These symbols may be used together to produce complicated
+equations very easily:
+@ID {
+@Code {
+"big sum from i=0 to n r sup i"
+"= {r sup n+1 - 1} over r-1"
+}
+||7ct
+@Eq { big sum from i=0 to n r sup i
+= {r sup n+1 - 1} over r-1
+}
+}
+Here @Code "sum" is just the @Eq { summation } symbol; @Code "from" and
+@Code "to" do all the work of placing the limits.  They are quite
+independent, so either or both may be omitted.  To get a superscript
+directly over a subscript, use the @Code "supp" and @Code "on" symbols:
+supp. @Index { @Code "supp" in equations }
+on. @Index { @Code "on" in equations }
+@ID {
+@Code "A supp b on a"
+|7ct
+@Eq { A supp b on a }
+}
+These two symbols should always be used together as shown.
+@PP
+Sometimes a subscript appears to be too far to the right, owing to
+the slope of italic letters: in @Eq { W sub n }, for example.  You
+can fix this by using `tucked' subscripts, like this:
+@IndentedList
+@LI {
+@Code "W tsub n"
+|7ct
+@Eq { W tsub n }
+}
+@LI {
+@Code "W supp b ton a"
+|7ct
+@Eq { W supp b ton a }
+}
+@EndList
+The @Code "tsub" and @Code "ton" symbols are exactly like @Code "sub"
+and @Code "on" except for this tucking-in effect.  However, the
+@Code "sub" symbol itself does a certain amount of tucking in; the
+amount is determined by kerning information in the font files and
+so is sensitive to the shape of the letters.
+@PP
+As usual in Lout, braces are used to group something into an indivisible
+object.  Leaving them out creates ambiguities:
+@ID @Code "a  sup  b  over  c"
+There are two possible interpretations for this:
+@IndentedList
+@LI {
+@Code "{a  sup  b}  over  c"
+|7ct
+@Eq {  {a  sup  b}  over  c }
+}
+@LI {
+@Code "a  sup  {b  over  c}"
+|7ct
+@Eq {  a  sup  {b  over  c} }
+}
+@EndList
+@Code "@Eq" chooses between them in the following way.  Every symbol that
+takes a parameter also has a {@I precedence}, which is a number.  For
+example, @Code "sup" has precedence 60 and @Code "over" has precedence
+54.  The symbol with the highest precedence wins the object lying between
+them, so in the above case the first interpretation is chosen.  If two
+symbols of equal precedence compete for an object, the association is
+towards the left:
+@ID {
+@Code "a sup b sub 2"
+|7ct
+@Eq { a sup b sub 2 }
+}
+In this case it is more probable that the following right association
+was actually wanted:
+@ID {
+@Code "a sup { b sub 2 }"
+|7ct
+@Eq { a sup { b sub 2 } }
+}
+When in doubt, use braces to make the grouping clear.
+@PP
+White space between two objects is considered to be a symbol with
+precedence 7, which is lower than the precedence of any @Code "@Eq"
+symbol; but if the two objects are immediately adjacent and neither is
+enclosed in braces the precedence is 102, which is higher than the
+precedence of any @Code "@Eq" symbol.  Compare these three examples:
+@IL
+@LI {
+@Code "big sum from i=0 to n"
+|7ct
+@Eq {  big sum from i=0 to n }
+}
+@LI {
+@Code "big sum from {i = 0} to n"
+|7ct
+@Eq {  big sum from {i = 0} to n }
+}
+@LI {
+@Code "big sum from i = 0 to n"
+|7ct
+@Eq {  big sum from i = 0 to n }
+}
+@EL
+and you will see that some care is needed on this point.  Braces can
+always be used to override precedence and associativity, and when in
+doubt the easiest course is to insert them.  Although Lout allows
+symbols to associate towards the left or right, @Code "@Eq" chooses
+to have only left associative symbols.  The summary at the end of this
+chapter gives the precedence of every symbol.
+@PP
+The @Code matrix symbol {@PageMark matrix} builds an array of objects:
+matrix. @Index { @Code "matrix" in equations }
+@ID {
+@Code {
+"matrix"
+"   atleft { blpar }"
+"   atright { brpar }"
+"{"
+"  row col x sup 2 col y sup 2 col z sup 2"
+"  row col x col y col z"
+"  row col 1 col 1 col 1"
+"}"
+}
+||9ct
+@Eq {
+matrix
+   atleft { blpar }
+   atright { brpar }
+{
+  row col x sup 2 col y sup 2 col z sup 2
+  row col x col y col z
+  row col 1 col 1 col 1
+}
+}
+}
+The @Code atleft and @Code atright options place vertically scaled
+versions of their values at each side; if either is omitted the value
+is taken to be an empty object of zero width by default.  Although
+we have used @Code blpar and @Code brpar here, since the options are
+vertically scaled to the correct size some people prefer simply
+@ID @OneRow @Code {
+"matrix"
+"   atleft { ( }"
+"   atright { ) }"
+}
+The right parameter of @Code matrix is the array itself.  It must be
+enclosed in braces, and it is a sequence of rows introduced by
+@Code row symbols; each row is a sequence of objects introduced by
+@Code col symbols.
+@FootNote {
+Older versions of Lout use different symbols, {@Code "above"} and
+{@Code "nextcol"}, at this point.  For backward compatibility these
+symbols are still available, but they are obsolete and no longer documented.
+}
+The @Code row and @Code col symbols have low precedence, but not
+as low as white space between two objects.  Therefore, unless the
+entries in the array are very simple, it is safest to enclose each of
+them in braces.
+@PP
+Entries built with the @Code col symbol have their objects centred in
+the column.  Also available are @Code lcol for left-justified entries,
+@Code ccol meaning the same as {@Code col}, @Code rcol for
+right-justified entries, and @Code mcol for alignment along column
+marks.  Each column may contain entries of different kinds, except
+that @Code mcol does not work well with any other sort.
+@PP
+When several matrices appear side by side, slight differences in height
+can cause an unsightly appearance:
+@ID @Eq {
+matrix
+   atleft { ( }
+   atright { ) }
+{
+   row col a sub 11 col a sub 12
+   row col a sub 21 col a sub 22
+}
+matrix
+   atleft { ( }
+   atright { ) }
+{
+   row col b sub 11 col b sub 12
+   row col b sub 21 col b sub 22
+}
+=
+matrix
+   atleft { ( }
+   atright { ) }
+{
+   row col c sub 11 col c sub 12
+   row col c sub 21 col c sub 22
+}
+}
+To assist in resolving this problem, the @Code "matrix" symbol has
+a @Code "strut" option, which causes a strut to be inserted into
+every row, guaranteeing that every row has height at least equal
+to the height of the strut.  By using
+@ID @Code {
+"matrix"
+"    strut { Yes }"
+"..."
+}
+in each of the three matrices above, the result is improved to
+@ID @Eq {
+matrix
+   atleft { ( }
+   atright { ) }
+   strut { Yes }
+{
+   row col a sub 11 col a sub 12
+   row col a sub 21 col a sub 22
+}
+matrix
+   atleft { ( }
+   atright { ) }
+   strut { Yes }
+{
+   row col b sub 11 col b sub 12
+   row col b sub 21 col b sub 22
+}
+=
+matrix
+   atleft { ( }
+   atright { ) }
+   strut { Yes }
+{
+   row col c sub 11 col c sub 12
+   row col c sub 21 col c sub 22
+}
+}
+By default, the strut has height @Code "0.5f" (half the current font
+size) both above and below the axis of the row.  This can be changed
+by giving any length as the value of the @Code "strut" option:
+@Code "strut { 2.0c }" for two centimetres above and below
+the axis, and so on.
+@PP
+Some symbols have been added which produce `matrices' with commonly needed
+@Code atleft and @Code atright options already set for you.  Here are
+these symbols, on the left, with the equivalent @Code matrix symbol
+and, on the right, the result produced:
+@ID @Tab
+    @Fmta { @Col @Code A ! @Col ! @Col @Code B ! @Col ! @Col C }
+{
+@Rowa
+    A { "pmatrix" }
+    B { "matrix atleft { ( } atright { ) } { M }" }
+    C { @Eq { pmatrix { M } } }
+@Rowa
+    A { "bmatrix" }
+    B { "matrix atleft { blbrack } atright { brbrack } { M }" }
+    C { @Eq { bmatrix { M } } }
+@Rowa
+    A { "brmatrix" }
+    B { "matrix atleft { blbrace } atright { brbrace } { M }" }
+    C { @Eq { brmatrix { M } } }
+@Rowa
+    A { "fmatrix" }
+    B { "matrix atleft { blfloor } atright { brfloor } { M }" }
+    C { @Eq { fmatrix { M } } }
+@Rowa
+    A { "cmatrix" }
+    B { "matrix atleft { blceil } atright { brceil } { M }" }
+    C { @Eq { cmatrix { M } } }
+@Rowa
+    A { "amatrix" }
+    B { "matrix atleft { blangle } atright { brangle } { M }" }
+    C { @Eq { amatrix { M } } }
+}
+For example:
+@ID {
+@Code {
+"fmatrix { (n+1) over 2 }"
+}
+|7ct
+@Eq {
+fmatrix { (n+1) over 2 }
+}
+}
+As this example shows, these symbols are very useful for getting large
+scaled delimiters around things that aren't necessarily matrices at all.
+@PP
+Each of the @Code "@Eq" symbols that takes parameters also has a @Code gap
+option, which controls the amount of space inserted by the symbol:
+@IL
+@LI {
+@Code "x over y"
+|7ct
+@Eq { x over y }
+}
+@LI {
+6c @Wide @Code "x over gap { 3p } y"
+|7ct
+@Eq { x over gap { 3p } y }
+}
+@EL
+@Code "@Eq" usually gets the spacing right without help.
+@End @Section
diff --git a/doc/user/equ_tequ b/doc/user/equ_tequ
new file mode 100644
index 0000000..bbb1d20
--- /dev/null
+++ b/doc/user/equ_tequ
@@ -0,0 +1,41 @@
+@Section
+   @Title { An alternative version that uses @TeX's fonts }
+   @Tag { teq }
+@Begin
+@PP
+There is an alternative version of the @Code "@Eq" symbol that
+tex.mathfonts @SubIndex { mathematical fonts }
+uses fonts taken from the @TeX document formatting
+system.  These fonts are said to produce better-looking
+mathematics than the Adobe Systems Symbol font used by the
+standard @Code "@Eq" symbol.
+@PP
+The fonts were converted from @TeX form to PostScript form by
+Basil K. Malyshev, who has attached a license to them permitting
+non-commercial use only.  This is a much more stringent license
+than the one attached to Lout itself.  For this reason, the files
+needed to use these @TeX fonts are distributed separately from the
+rest of Lout, although you can get them from the same place (see the
+preface of this guide).
+@PP
+Once these files are installed, you change from the standard
+@Code "@Eq" symbol to the @TeX version by changing the initial
+@Code "@SysInclude { eq }" to {@Code "@SysInclude { teq }"}.  Do
+absolutely nothing else.
+@PP
+Unfortunately, the @TeX fonts are not usually resident on PostScript
+printing devices, which means that Lout is obliged to include them in its
+PostScript output file.  You don't have to do anything to make this
+happen, but the cost is fairly large:  changing to @Code "@SysInclude { teq }"
+increases the size of the PostScript output file by 252 kilobytes.
+@PP
+It is possible to gain access to characters in the @TeX
+fonts that are not accessible directly from {@Code "@Eq"}, mainly
+script capitals and bold-italic Greek letters.  For example, you can
+use @Code "{cmsy Base} @Font @Char \"A\"" to get a script A, and
+@Code "{cmmi Bold} @Font @Char \"pi\"" to get a bold-italic
+{@Sym pi}.  For the full story, consult file @Code "teq" in the
+Lout system include directory for the names of these fonts, and then
+look in Lout's font directory for their font metrics files, which
+show the names and encodings of all the characters.
+@End @Section
diff --git a/doc/user/equ_vert b/doc/user/equ_vert
new file mode 100644
index 0000000..1595ed8
--- /dev/null
+++ b/doc/user/equ_vert
@@ -0,0 +1,164 @@
+@Section
+    @Tag { vpos }
+    @Title { Vertical positioning }
+@Begin
+@PP
+Every equation and every object within every equation has an
+@I axis running through it which is used to position it vertically
+axis @Index { axis of equation }
+with respect to nearby objects.  In the Expert's Guide to Lout
+@Cite { $kingston1995lout.expert } this is called a @I { row mark },
+but we'll stick with axis.  Here are some examples with the axis
+shown as a dashed line:
+@ID {
+@ShowHMark @Eq { x sup 2 }
+||2c
+@ShowHMark @Eq { non + }
+||2c
+@ShowHMark @Eq { @ExA }
+}
+When these objects are placed adjacent to one another, their
+axes are merged, giving the correct vertical positioning:
+@ID @ShowHMark @Eq { x sup 2 + @ExA }
+Most of the time you do not need to think about vertical
+positioning, because for most objects there is just one
+sensible place for the axis to go, and Lout puts it there.
+@PP
+Matrices and the delimiters that enclose them are the two
+exceptions.  Lout makes the axis of a matrix pass through
+its exact centre, and it shifts the axes of delimiters
+so that they exactly enclose the thing delimited.  These
+choices are never disastrous, but there are other possibilities
+that might be better sometimes.
+@PP
+The axis of a matrix could reasonably be set to the axis
+of any of its rows:
+@ID {
+@ShowHMark @Eq {
+matrix userow { yes } {
+  axisrow col { x sup 3 } col { y sup 3 } col { z sup 3 }
+  row     col { x sup 2 } col { y sup 2 } col { z sup 2 }
+  row     col { x } col { y } col { z }
+}
+}
+||2c
+@ShowHMark @Eq {
+matrix userow { yes } {
+  row     col { x sup 3 } col { y sup 3 } col { z sup 3 }
+  axisrow col { x sup 2 } col { y sup 2 } col { z sup 2 }
+  row     col { x } col { y } col { z }
+}
+}
+||2c
+@ShowHMark @Eq {
+matrix userow { yes } {
+  row     col { x sup 3 } col { y sup 3 } col { z sup 3 }
+  row     col { x sup 2 } col { y sup 2 } col { z sup 2 }
+  axisrow col { x } col { y } col { z }
+}
+}
+}
+Alternatively, it could be set to where Lout usually places it,
+through the exact centre:
+@ID {
+@ShowHMark @Eq {
+matrix {
+  row     col { x sup 3 } col { y sup 3 } col { z sup 3 }
+  row     col { x sup 2 } col { y sup 2 } col { z sup 2 }
+  row     col { x } col { y } col { z }
+}
+}
+}
+Delimiters could reasonably keep the axes that they naturally
+have (approximately through their centres, but not exactly):
+@ID {
+@ShowHMark @Eq { pmatrix userow { yes } shiftdelim { no } { @ExA } }
+}
+or they could have their axes moved in the way that Lout usually does,
+to the point which allows them to evenly cover the thing delimited:
+@ID {
+@ShowHMark @Eq { pmatrix userow { yes } { @ExA } }
+}
+Altogether then there are four possibilities when these two alternatives
+interact:
+@CD lines @Break @Tab
+  @Fmta { @Col 0.5w @VShift A ! @Col ! @Col B ! @Col ! @Col C }
+{
+@Rowa
+  A { }
+  B { Matrix axis
+uses row axis }
+  C { Matrix axis passes
+through centre }
+@Rowa
+@Rowa
+  A { Delimiter
+keeps its axis }
+  B { @ShowHMark @Eq { pmatrix userow {yes} shiftdelim {no } { @ExA } } }
+  C { @ShowHMark @Eq { pmatrix userow {no } shiftdelim {no } { @ExA } } }
+@Rowa
+@Rowa
+  A { Delimiter
+axis shifted }
+  B { @ShowHMark @Eq { pmatrix userow {yes} shiftdelim {yes} { @ExA } } }
+  C { @ShowHMark @Eq { pmatrix userow {no } shiftdelim {yes} { @ExA } } }
+}
+To supply these possibilities, the @Code "matrix" symbol and all
+its variants (@Code "pmatrix" etc.) have two options whose
+values may be {@Code "yes"} or {@Code "no"}:
+@ID @Code {
+"matrix"
+"    userow { no }"
+"    shiftdelim { yes }"
+"{"
+"    ..."
+"}"
+}
+The @Code "userow" option determines whether the axis of the
+matrix will use a row axis; the default is not to, i.e. to
+centre the axis instead.  The @Code "shiftdelim" option
+determines whether the axis of the delimiter will be shifted
+so that the delimiter evenly covers the thing delimited; the
+default is to do this.
+@PP
+If @Code "userow" is {@Code "yes"}, the next question is
+which row's axis to use to make the overall axis.  If you
+do nothing, the first (or only) row's axis becomes the
+overall axis.  To select some other row instead, replace
+the @Code "row" symbol that precedes the row by {@Code "axisrow"}:
+@ID @Code @Tab
+  vmargin { 0.5vx }
+  hmargin { 1s }
+  @Fmta { @Col A ! @Col ! @Col B ! @Col ! @Col C ! @Col ! @Col D ! @Col }
+  @Fmtb { @Col A ! @Col " col {" ! @Col B ! @Col "}  col {" ! @Col C ! @Col "}  col {" ! @Col D ! @Col "}" }
+{
+@Rowa
+  A { "matrix userow { yes } {" &0io }
+@Rowb
+  A { "    row" }
+  B { "x sup 3" }
+  C { "y sup 3" }
+  D { "z sup 3" }
+@Rowb
+  A { "    axisrow" }
+  B { "x sup 2" }
+  C { "y sup 2" }
+  D { "z sup 2" }
+@Rowb
+  A { "    row" }
+  B { "x" }
+  C { "y" }
+  D { "z" }
+@Rowa
+  A { "}" }
+}
+The result of this is
+@ID @ShowHMark @Eq {
+matrix userow { yes } {
+  row     col { x sup 3 } col { y sup 3 } col { z sup 3 }
+  axisrow col { x sup 2 } col { y sup 2 } col { z sup 2 }
+  row     col { x } col { y } col { z }
+}
+}
+with the axis through the second row as desired.
+@End @Section
diff --git a/doc/user/fmt b/doc/user/fmt
new file mode 100644
index 0000000..ffd5e7f
--- /dev/null
+++ b/doc/user/fmt
@@ -0,0 +1,16 @@
+@Chapter
+    @Title { Changing the Overall Format }
+    @Tag { changes }
+@Begin
+@LP
+The symbols of Lout make many decisions behind the scenes.  Even the
+humble @Code "@PP" symbol has to decide how much vertical space to
+leave, and how far to indent the first line of the paragraph.  How to
+change these decisions is the subject of this chapter.
+@BeginSections
+@Include { fmt_setu }
+@Include { fmt_size }
+@Include { fmt_marg }
+@Include { fmt_head }
+@EndSections
+@End @Chapter
diff --git a/doc/user/fmt_head b/doc/user/fmt_head
new file mode 100644
index 0000000..77cbada
--- /dev/null
+++ b/doc/user/fmt_head
@@ -0,0 +1,313 @@
+@Section
+    @Title { Page numbers and running headers }
+    @Tag { headers }
+@Begin
+@PP
+A @I { page header } is a line at the top of a page containing a page
+page.header @Index { page header }
+running.header @Index { running header }
+number or running title.  A @I { page footer } is a similar line at
+page.footer @Index { page footer }
+the bottom of a page.  This section describes the setup file options
+that control the appearance of page headers and footers.
+@PP
+There are four basic styles, selected by the @Code "@PageHeaders" option:
+page.headers @Index @Code "@PageHeaders"
+@ID @Tab
+    @Fmta { @Col @Code { "@PageHeaders {" A "}" } ! @Col B }
+{
+@Rowa
+    A { None }
+    B { No page headers, no page footers. }
+@Rowa
+    A { Simple }
+    B { No footers, and a centred page number between hyphens for
+header on every page whose number is not 0 or 1. }
+@Rowa
+    A { Titles }
+    B { Full running titles as in the present document. }
+@Rowa
+    A { NoTitles }
+    B { Page numbers placed as for @Code { Titles }, but with the
+titles themselves blanked out. }
+}
+@Code Titles and @Code NoTitles use Lout's cross-referencing machinery,
+so will require a few runs to settle down.  @Code None and @Code Simple
+do not, so they work first time and may be used with the @Code "-s"
+command line flag.  Section {@NumberOf cross} has a fuller discussion
+of these ramifications of cross referencing.
+@PP
+The next step is to set the page numbers, using
+the @Code "@PageNumbers" and @Code "@FirstPageNumber" options.  There
+page.numbers @Index @Code "@PageNumbers"
+are two useful values for {@Code "@PageNumbers"}:
+@ID @Tab
+    @Fmta { @Col @Code { "@PageNumbers {" A "}" } ! @Col B }
+{
+@Rowa
+    A { Arabic }
+    B { Arabic page numbers }
+@Rowa
+    A { Roman }
+    B { Lower-case Roman page numbers }
+}
+although the full range of choices is {@Code "None"}, {@Code "Arabic"},
+{@Code "Roman"}, {@Code "UCRoman"}, {@Code "Alpha"}, and
+{@Code "UCAlpha"}.  @Code "@FirstPageNumber" is the number of the
+first.page.number @Index @Code "@FirstPageNumber"
+first page.  Its default value is of course {@Code 1}, although
+@ID @Code "@FirstPageNumber { 0 }"
+might be useful if the first page is really an unnumbered cover
+sheet.  @Code "@FirstPageNumber" must be an Arabic number even if
+@Code "@PageNumbers" is set to something other than {@Code "Arabic"}.
+@PP
+Some document types, such as books and technical reports with cover
+sheets, have a separate introductory
+sequence of pages preceding the main sequence.  For the page numbers on
+introductory pages there are two options, @Code "@IntroPageNumbers"
+intro.page.numbers @Index @Code "@IntroPageNumbers"
+intro.first.page.number @Index @Code "@IntroFirstPageNumber"
+and {@Code "@IntroFirstPageNumber"}, which are exactly analogous to
+@Code "@PageNumbers" and {@Code "@FirstPageNumber"}.  It is traditional
+to number introductory pages using Roman numerals, so @Code Roman is
+the default value of {@Code "@IntroPageNumbers"}.
+@PP
+Let's summarize the five options so far by looking at their values in
+the @Code book setup file, which was used to produce the present document:
+@ID @OneRow @Code {
+"@PageHeaders { Titles }"
+"@PageNumbers { Arabic }"
+"@FirstPageNumber { 1 }"
+"@IntroPageNumbers { Roman }"
+"@IntroFirstPageNumber { 1 }"
+}
+The remainder of this section goes beyond these basic choices to explain
+how to change the detailed appearance of page headers
+and footers.  Inevitably it gets quite a lot harder.
+@PP
+Pages are classified by the page header options in three ways:
+@NumberedList
+@LI { @I { Odd vs. even }.  The first page is odd, the second is even,
+odd.pages @Index { odd and even pages }
+the third is odd, and so on.  If @Code "@FirstPageNumber" is set to
+an even number, the first page will have that number, but it will still
+be classified as odd. }
+@LI { @I { Start vs. non-start }.  A start page is the first page of
+start.pages @Index { start and non-start pages }
+some major part of the document (a chapter, say); other pages are
+non-start.  The @Code { Simple } header type uses a simpler
+definition:  a page whose number is 0 or 1 is a start page, all others
+are non-start. }
+@LI { @I { Intro vs. non-intro }.  Intro pages form a separate sequence of
+intro.pages @Index { intro and non-intro pages }
+pages that precede the main (non-intro) sequence.  They typically contain
+prefatory material such as a title page, preface, and table of contents.
+In a book there will always be an even number of Intro pages, even if
+it means that the last one is empty. }
+@EndList
+These classifications are quite independent of each other:  a page
+could be a non-intro start odd page, or an intro non-start even page,
+and so on.  This makes eight (@Eq { 2 times 2 times 2 }) possibilities
+altogether.  Depending on the type of document there may also be pages
+that Lout will never place a page header or footer on.  For example, no page
+headers or footers will appear on pages containing part titles in books.
+@PP
+If you choose {@Code "@PageHeaders { None }"}, there are no page headers
+or footers, so there is nothing more to say.  If you choose
+{@Code "@PageHeaders { Simple }"}, then eight options become relevant
+for controlling the page headers on each of the eight kinds of
+pages.  Here they are with their default values:
+@ID @OneRow @Code {
+"@OddTop { @Centre { - @PageNum - } }"
+"@EvenTop { @Centre { - @PageNum - } }"
+"@StartOddTop { @Null }"
+"@StartEvenTop { @Null }"
+"@IntroOddTop { @Null }"
+"@IntroEvenTop { @Null }"
+"@IntroStartOddTop { @Null }"
+"@IntroStartEvenTop { @Null }"
+}
+If the word @Code Start is missing from an option name, the option
+applies to non-start pages; if @Code Intro is missing, it applies to
+non-intro pages.  Another eight options control footers in the same way:
+@ID @OneRow @Code {
+"@OddFoot { @Null }"
+"@EvenFoot { @Null }"
+"@StartOddFoot { @Null }"
+"@StartEvenFoot { @Null }"
+"@IntroOddFoot { @Centre @PageNum }"
+"@IntroEvenFoot { @Null }"
+"@IntroStartOddFoot { @Centre @PageNum }"
+"@IntroStartEvenFoot { @Null }"
+}
+The value of the option is an object which becomes the header or
+footer.  It may be any object, but there are some peculiarities that
+will be explained now.
+@PP
+The full set of symbols of the BasicSetup package can be used
+when setting page header options (and indeed any of the options
+of the @Code "@BasicSetup" @Code "@Use" clause package), as well as
+symbols from special-purpose
+packages that have been included before this setup file.  This means
+you can use any symbol you might reasonably expect to.  But footnotes and
+floating figures and tables, for example, are not from BasicSetup so
+cannot be used.
+@PP
+There are five symbols of special relevance to page headers and
+footers: {@Code "@Null"}, {@Code "@Centre"}, {@Code "@Center"},
+{@Code "@Right"}, and {@Code "@PageNum"}.
+@PP
+The @Code "@Null" symbol is similar to the empty object in printing as
+null. @Index @Code "@Null"
+nothing, but in addition it removes the vertical space that ordinarily
+separates the header line from the page body.  If there is no header
+there should be no vertical space either, so always use @Code "@Null"
+rather than the empty object in header and footer options.
+@PP
+@Code "@Centre" and @Code "@Center" centre the following object, and
+centre. @Index @Code "@Centre"
+center. @Index @Code "@Center"
+right. @Index @Code "@Right"
+@Code "@Right" right-justifies it:
+@ID @Code "at left  @Centre { - 27 - }  @Right { at right }"
+produces
+@QD @HExpand { at left  @Centre { - 27 - }  @Right { at right } }
+The objects should be enclosed in braces if they contain spaces.
+@PP
+The @Code "@PageNum" symbol produces the number of the current page, in
+page.num. @Index @Code "@PageNum"
+Arabic, Roman, etc. as specified by the @Code "@PageNumbers" or
+@Code "@IntroPageNumbers" option.  @Code "@PageNum" is available only
+within page header and footer options.
+@PP
+At this point you might like to pause and verify that the default
+values of the sixteen options given above produce what we said they
+would:  no footers, and a centred page number between hyphens on every
+page whose number is not 0 or 1.  It should be clear now what to do if
+you want to remove the hyphens, move the numbers to the page footer,
+make them bold, have them at the left on even pages and at the right on
+odd pages, and so on.
+@PP
+A different set of sixteen options applies when @Code "@PageHeaders"
+is set to @Code Titles or {@Code "NoTitles"}.  Here are the eight
+options for headers, with their default values:
+@ID @OneRow @Code {
+"@RunningOddTop { @I { @MinorNum @DotSep @MinorTitle }"
+"       @Right @B @PageNum }"
+"@RunningEvenTop { @B @PageNum"
+"       @Right @I { @MajorNum @DotSep @MajorTitle } }"
+"@RunningStartOddTop { @Null }"
+"@RunningStartEvenTop { @Null }"
+"@RunningIntroOddTop { @Null }"
+"@RunningIntroEvenTop { @Null }"
+"@RunningIntroStartOddTop { @Null }"
+"@RunningIntroStartEvenTop { @Null }"
+}
+Some options occupy two lines, but only because they are long:  as
+usual, the end of a line is the same as one space.  Here are the
+options for footers:
+@ID @OneRow @Code {
+"@RunningOddFoot { @Null }"
+"@RunningEvenFoot { @Null }"
+"@RunningStartOddFoot { @Centre { Bold 0.8f } @Font @PageNum }"
+"@RunningStartEvenFoot { @Centre { Bold 0.8f } @Font @PageNum }"
+"@RunningIntroOddFoot { @Right @PageNum  }"
+"@RunningIntroEvenFoot { @PageNum }"
+"@RunningIntroStartOddFoot { @Null }"
+"@RunningIntroStartEvenFoot { @Null }"
+}
+All these options are similar to the earlier ones, in providing one
+option for each of the eight kinds of pages.  The names are the same
+except that @Code Running is added to each.  Remember that a start
+page is now one that begins a major part of the document.
+@PP
+In addition to the symbols described earlier for simple page headers
+and footers, these running header options may contain the symbols
+{@Code "@MajorNum"}, {@Code "@MajorTitle"}, {@Code "@MinorNum"},
+{@Code "@MinorTitle"}, {@Code "@DotSep"}, {@Code "@NoDotSep"},
+{@Code "@DotJoin"}, {@Code "@NoDotJoin"}, {@Code "@DashJoin"},
+and {@Code "@NumSep"} described below.
+major.num @Index @Code "@MajorNum"
+major.title @Index @Code "@MajorTitle"
+minor.num @Index @Code "@MinorNum"
+minor.title @Index @Code "@MinorTitle"
+@PP
+The exact values of {@Code "@MajorNum"}, {@Code "@MajorTitle"},
+{@Code "@MinorNum"}, and {@Code "@MinorTitle"} depend on the document
+type, but they are intended to describe what is on the current page.  Here
+are some values typical of books:
+@ID @Tab
+    @Fmta { @Col @Code A ! @Col @Code B }
+    vmargin { 0.5vx }
+{
+@Rowa
+    A { "@MajorNum" }
+    B { Chapter 2 }
+@Rowa
+    A { "@MajorTitle" }
+    B { Adding Structure to Documents }
+@Rowa
+    A { "@MinorNum" }
+    B { 2.7 }
+@Rowa
+    A { "@MinorTitle" }
+    B { Tables of contents }
+}
+It is not possible to change the values assigned to these symbols, but
+the sixteen options allow you to choose whether to use them and how to
+arrange them, in the usual way.
+@PP
+The @Code "@DotSep" symbol consumes the objects to its left and right
+dot.sep @Index @Code "@DotSep"
+and produces them separated by a dot and two spaces:
+@ID @Code "@MinorNum @DotSep @MinorTitle"
+is the same as
+@ID @Code "@MinorNum.  @MinorTitle"
+However, if either object is empty, the dot and two spaces are
+omitted.  It's a fine point, needed mainly for unnumbered chapters
+and sections.  @Code "@DotJoin" is the same as @Code "@DotSep" but
+dot.join @Index @Code "@DotJoin"
+without the two spaces.  @Code "NoDotSep" is the same as
+nodot.sep @Index @Code "@NoDotSep"
+@Code "@DotSep" but leaving out the dot, @Code "@NoDotJoin" is the same
+nodot.join @Index @Code "@NoDotJoin"
+as @Code "@DotJoin" but again leaving out the dot, and @Code "@DashJoin"
+dash.join @Index @Code "@DashJoin"
+is the same as @Code "@DotJoin" except that `--' replaces the dot.
+@PP
+Lout uses @Code "@DotSep" between numbers and titles by default.  To
+get rid of all dots between numbers and titles it is necessary to
+change all occurrences of @Code "@DotSep" in the setup file to
+{@Code "@NoDotSep"}.  There are about ten occurrences, depending
+on the setup file.
+@PP
+@Code "@NumSep" {@PageMark numsep} is similar to @Code "@NoDotSep"
+except that one space
+num.sep @Index @Code "@NumSep"
+hungarian @Index { Hungarian and @Code "@NumSep" }
+is used, not two, and also the order of the two parts is reversed and
+a dot is added if the current language is Hungarian (apparently
+Hungarians write `3. Table' where other people write `Table 3').
+@Code "@NumSep" is used behind the scenes in a variety of places.
+@PP
+The present document was produced using @Code "@PageHeaders { Titles }"
+with the default values of the sixteen options unchanged, as you might
+like to verify.  @Code "@PageHeaders { NoTitles }" is identical to
+@Code "@PageHeaders { Titles }" except that {@Code "@MajorNum"},
+{@Code "@MajorTitle"}, {@Code "@MinorNum"}, and {@Code "@MinorTitle"}
+are always replaced by empty objects.  The description given at the
+beginning of this section, `like @Code "Titles" but with the titles
+blanked out,' is therefore accurate.
+@PP
+There is a @Code "@StructPageNums" setup file option that produces
+structpagenums. @Index @Code "@StructPageNums"
+structured page numbers when it is changed to {@Code Yes}; that is,
+page numbers that include a section number, subsection number, and so
+on.  Precisely which structure numbers are included is determined by the
+@Code "@SectionNumInRunners" option and its relatives.  @Code "@PageHeaders"
+must be @Code Titles when structured page numbers are used, and it is
+probably best to set @Code "@SectionGap" and some similar options to
+{@Code "2b"} (meaning new page) as well.  The @Code "@NumberSeparator"
+setup file option (Section {@NumberOf largescale}) affects the format
+of the structured page numbers.
+@End @Section
diff --git a/doc/user/fmt_marg b/doc/user/fmt_marg
new file mode 100644
index 0000000..1b82d41
--- /dev/null
+++ b/doc/user/fmt_marg
@@ -0,0 +1,121 @@
+@Section
+    @Title { Page margins, page boxes, and page backgrounds }
+    @Tag { margins }
+@Begin
+@PP
+There are six options for setting the top and bottom margins on each
+margins. @RawIndex { margins }
+margins.in.pages @SubIndex { in pages }
+top.margin @Index @Code "@TopMargin"
+foot.margin @Index @Code "@FootMargin"
+odd.left.margin @Index @Code "@OddLeftMargin"
+odd.right.margin @Index @Code "@OddRightMargin"
+even.left.margin @Index @Code "@EvenLeftMargin"
+even.right.margin @Index @Code "@EvenRightMargin"
+page, and the left and right margins on odd and even pages.  Here they
+are with their default values:
+@ID @OneRow @Code {
+"@TopMargin { 2.50c }"
+"@FootMargin { 2.50c }"
+"@OddLeftMargin { 2.50c }"
+"@OddRightMargin { 2.50c }"
+"@EvenLeftMargin { 2.50c }"
+"@EvenRightMargin { 2.50c }"
+}
+When setting these options you must ensure that
+@ID @Eq { @Code "@OddLeftMargin" + @Code "@OddRightMargin" =
+@Code "@EvenLeftMargin" + @Code "@EvenRightMargin" }
+In other words, the total margin on odd pages must be the same as on
+even pages.
+@PP
+You can have a box drawn around each page if you wish.  Here are the
+relevant options and their default values:
+@ID @OneRow @Code {
+"@PageBoxType { None }"
+"@PageBoxMargin { 1.00c }"
+"@PageBoxLineWidth {}"
+"@PageBoxPaint { None }"
+"@PageBoxShadow { 0.06c }"
+}
+You get boxes by changing the @Code "@PageBoxType" option:
+page.box.type @Index @Code "@PageBoxType"
+@ID @OneRow @Tab
+    @Fmta { @Col @Code A ! @Col @CC B }
+{
+@Rowa
+    A { "@PageBoxType { None }" }
+    B { (no box) }
+@Rowa
+@Rowa
+    A { "@PageBoxType { Box }" }
+    B { @Box 1.0c @Wide 1.4c @High }
+@Rowa
+@Rowa
+    A { "@PageBoxType { CurveBox }" }
+    B { @CurveBox 1.0c @Wide 1.4c @High }
+@Rowa
+@Rowa
+    A { "@PageBoxType { ShadowBox }" }
+    B { @ShadowBox 1.0c @Wide 1.4c @High }
+}
+Page boxes reduce the amount of space available to the page contents,
+so your columns will become somewhat narrower and shorter when you
+introduce them.
+@PP
+The {@Code "@PageBoxMargin"}, {@Code "@PageBoxLineWidth"},
+{@Code "@PageBoxPaint"}, and {@Code "@PageBoxShadow"} options affect
+the page box exactly as the {@Code margin}, {@Code linewidth},
+{@Code paint}, and {@Code shadow} options described
+for other boxes in Section {@NumberOf boxes} do.  For example,
+@ID @OneRow @Code {
+"@PageBoxType { CurveBox }"
+"@PageBoxMargin { 1.0c }"
+"@PageBoxPaint { grey }"
+}
+draws a curved box, painted grey, around each page, with a one
+centimetre margin between its boundary and the page contents.  If the
+left margin is 2.5 centimetres, say, this gives a total left margin
+from the page edge to the page contents of 3.5 centimetres.
+@PP
+Finally, it is possible to have something other than the usual white
+background on the page, using the @Code "@PageBackground" option:
+page.background @Index @Code "@PageBackground"
+@ID @Code {
+"@PageBackground { @Scale 60d @Rotate lightgrey @Colour DRAFT }"
+}
+The value of the option is an object which is drawn on each page,
+within the margins, before the page contents are drawn.  This
+example draws a large word DRAFT in light grey diagonally across each
+page:
+@ID @Box margin { 0c } 0.2 @Scale @IncludeGraphic draft.eps
+You have to find a suitable angle by experiment.  As Section
+{@NumberOf scaling} explains, @Code "@Scale" with no scale factor
+only takes account of the available horizontal space, not the
+available vertical space, so if your angle is too steep the result
+will be too tall for the page and you will get a regrettably obscure
+warning message about a `broken size constraint.'  The solution is
+to try a smaller angle.
+@PP
+Another useful page background draws marks to show where the margins
+boundarymarks @Index @Code "@BoundaryMarks"
+cut.marks @Index { cut marks }
+lie:
+@ID @Code "@PageBackground { @BoundaryMarks }"
+produces something like this around each page:
+@DP @DP
+@ID { |@DisplayIndent 3c @High 2c @Wide @HExpand @VExpand @BoundaryMarks }
+@DP @DP
+The @Code "@BoundaryMarks" symbol has options for controlling the
+line width (thickness), the line length, and the gap between the
+ends of the lines and the corner of the text area:
+@ID @OneRow @Code {
+"@PageBackground {"
+"    @BoundaryMarks"
+"        linewidth { 0.2p }"
+"        length { 0.5c }"
+"        gap { 0.5c }"
+"}"
+}
+This shows the default values:  0.2 points for line width,
+0.5 centimetres for the others.
+@End @Section
diff --git a/doc/user/fmt_setu b/doc/user/fmt_setu
new file mode 100644
index 0000000..6e1bb05
--- /dev/null
+++ b/doc/user/fmt_setu
@@ -0,0 +1,210 @@
+@Section
+    @Title { Setup files }
+    @Tag { setup }
+@Begin
+@PP
+As mentioned briefly in Section {@NumberOf start}, each Lout document
+begins with an instruction to include (i.e. to read) a @I { setup file }:
+setup.file @Index { setup file }
+sysinclude. @Index @Code "@SysInclude"
+system.include @Index { system include directory }
+doc.file @Index { @Code "doc" file }
+@ID @Code "@SysInclude { doc }"
+The setup file's name in this example is @Code { doc }, and the @Code Sys
+in @Code "@SysInclude" means that @Code doc is stored in the @I { Lout
+system include directory }, which is where all the standard setup files
+are kept.  Each document type (Chapter {@NumberOf types}) has its own
+setup file, and each specialized package (for equations, tables, and
+so on) has a setup file too.
+@PP
+To change the overall format of a document, you need to create your own
+setup file by copying and modifying one of the standard ones.  We will
+assume that you are making an ordinary document, with the @Code doc
+setup file, but a similar procedure works for any setup file.
+@PP
+You first need to find out the name of the Lout system include
+directory, by typing
+@ID @Code "lout  -V"
+in Unix.  This causes Lout to print out various facts about itself.  Then,
+supposing that this tells you that the Lout system include directory
+is @Code { "/usr/lout/include" }, type the Unix command
+@ID @Code "cp  /usr/lout/include/doc  mydoc"
+to place a copy of the @Code doc setup file in your directory,
+mydoc.file @Index { @Code "mydoc" file }
+renaming it @Code {mydoc}.  Since @Code "doc" is read-only, you may
+also need to change the mode of @Code mydoc to be writable (by
+@Code "chmod +w mydoc" in Unix).  Now replace
+@ID @Code "@SysInclude { doc }"
+at the beginning of your document by
+@ID @Code "@Include { mydoc }"
+and Lout will read @Code mydoc as the setup file instead of
+@Code { doc }.  Since the two files are at present identical, this has
+changed nothing so far; but now any changes you make to @Code mydoc
+will affect your document.  Notice the use of @Code "@Include"
+rather than @Code { "@SysInclude" }; @Code "@Include" will search your
+current directory for @Code { mydoc }, whereas @Code "@SysInclude"
+searches only the system directory.
+@PP
+The remainder of this section is a tour through @Code {doc},
+explaining the various parts and how to modify them.  The first lines
+that actually do anything are these:
+@ID @OneRow @Code {
+"@SysInclude { fontdefs }"
+"@SysInclude { langdefs }"
+"@SysInclude { bsf }"
+"@SysInclude { dsf }"
+"@SysInclude { docf }"
+}
+We already know that @Code "@SysInclude" causes Lout to read a file from
+the Lout system include directory.  Files @Code fontdefs and @Code langdefs
+fontdefs.file @Index { @Code "fontdefs" file }
+langdefs.file @Index { @Code "langdefs" file }
+tell Lout what fonts and languages there are.  Files @Code "bsf" and
+@Code "dsf" contain
+bsf.file @Index { @Code "bsf" file }
+dsf.file @Index { @Code "dsf" file }
+the definitions of the BasicSetup and DocumentSetup packages, in which
+all the symbols of the first two chapters of this guide are defined.  File
+@Code "docf" contains extra definitions specific to
+docf.file @Index { @Code "docf" file }
+ordinary documents (as distinct from technical reports, books, or the
+other document types of Chapter {@NumberOf types}).  So this line
+will be different in the setup files for those other types.
+@PP
+The next line is
+@ID @Code {
+"@Include { mydefs }"
+}
+This searches your current directory for a file called @Code { mydefs },
+which (as Section {@NumberOf definitions} explains) is intended to hold
+your own personal set of definitions of new symbols.  It does no harm
+if there is no @Code "mydefs" file in your current directory, because
+@Code "@Include" then searches the Lout system include directory for
+it, and there is an empty @Code mydefs file there.  When using your own
+setup file, you might prefer to delete @Code "@Include { mydefs }" and
+put your definitions in its place, so that you have one file of setup
+material rather than two.
+@PP
+Next we come to the BasicSetup @Code "@Use" clause.  It looks like this:
+use. @Index @Code "@Use"
+@ID @OneRow @Code @Verbatim {
+@Use { @BasicSetup
+  # @InitialFont { Times Base 12p }
+  # @InitialBreak { {adjust 1.20fx hyphen} @OrIfPlain {ragged 1fx nohyphen} }
+  # @InitialSpace { lout }
+  # @InitialLanguage { English }
+  # @InitialColour { black }
+  # @OptimizePages { No }
+  # @HeadingFont { Bold }
+  # @ParaGap { 1.3vx @OrIfPlain 1f }
+  # @ParaIndent { 2.00f @OrIfPlain 5s }
+}
+}
+@Code "@BasicSetup" is a symbol, and @Code { "@InitialFont" },
+basic.layout @Index @Code "@BasicSetup"
+@Code { "@InitialBreak" }, etc. are its options.  There are more options
+than we've shown; the display above just shows the first
+few.  You change the overall format of your document by changing
+these options.
+@PP
+As it stands, the options are all hidden within comments, so the
+default values (shown within braces) are in force.  To change an
+option, delete the @Code "#" and change the value between
+braces.  For example, to set the document in Helvetica 10 point
+font, change the @Code { "@InitialFont" } line to
+@ID @Code "@InitialFont { Helvetica Base 10p }"
+We won't go through all the options now, since they are the subject of
+following sections.
+@PP
+The @Code "@OrIfPlain" symbol that appears within some setup file
+options is used to set the value of the option differently when
+plain text output (Section {@NumberOf plain}) is being produced.  For
+example, the default value of @Code "@InitialBreak" is usually
+{@Code "adjust 1.20fx hyphen"}, but when plain text is being produced
+it switches to {@Code "ragged 1fx nohyphen"}.  When changing such
+options you can leave the @Code "@OrIfPlain" symbol there and change
+one or both of the alternative values as you wish.
+@PP
+Next comes a similar @Code "@Use" clause, for the DocumentSetup package:
+@ID @OneRow @Code {
+"@Use { @DocumentSetup"
+"  # @PageType { A4 @OrIfPlain Other }"
+"  # @PageWidth { 80s }"
+"  # @PageHeight { 66f }"
+"  # @PageOrientation { Portrait }"
+"  # @PageBackground {}"
+"  # @TopMargin { 2.5c @OrIfPlain 6f }"
+"}"
+}
+This one has many options, starting with options for page
+layout as shown, then going on to figures and tables, tables of
+contents, etc.
+@PP
+The standard setup files are all much the same up to this point; the
+main variation is that in some files, some options are already set.  The
+@Code "slides" setup file, for example, contains
+@ID @Code "@InitialFont { Times Base 20p }"
+so that overhead transparencies will have a large font size.  However,
+now comes a third @Code "@Use" clause whose symbol and options depend
+on the document type.  For ordinary documents (i.e. in the @Code "doc"
+setup file) this clause is
+@ID @OneRow @Code {
+"@Use { @OrdinarySetup"
+"  # @IndexWord { index }"
+"  # @AppendixWord { appendix }"
+"  # @SectionNumbers { Arabic }"
+"  # @AppendixNumbers { UCAlpha }"
+"  # @SectionHeadingFont { Bold }"
+"}"
+}
+Once again this is just some of the options.  In the @Code slides
+setup file for overhead transparencies, we find this:
+@ID @OneRow @Code {
+"@Use { @OverheadSetup"
+"  # @DateLine { No }"
+"  # @ContentsWord { contents }"
+"  # @FirstOverheadNumber { 1 }"
+"  # @OverheadNumbers { Arabic }"
+"  # @TitlePageFont { Helvetica Base 1.5f }"
+"  # @OverheadHeadingFont { Bold }"
+"  # @OverheadInContents { No }"
+"}"
+}
+In general this third @Code "@Use" clause assigns values to options
+specific to the document type we are using, whereas the first and
+second @Code "@Use" clauses assign values to options that are relevant to many
+or all document types.
+@PP
+The setup file ends with a comment identifying a spot where database
+declarations may
+database.dec @Index { database declarations, where to put }
+be put, and one such declaration, for reference printing styles.
+@PP
+The setup files used with other packages, such as C and C++ program printing,
+diagrams, and graphs, are similar to the @Code { doc } setup file we
+have just gone through.  They contain a @@SysInclude line analogous to
+@Code "@SysInclude { dsf }" for reading the package's definition, followed
+by a @@Use clause for setting the package's options.  The same procedure
+is followed for changing these options.  For example, to change the
+options of the @Code "diag" package, copy file @Code "diag" from the
+Lout system include directory to your directory, replace the
+@ID @Code "@SysInclude { diag }"
+line at the top of your document by {@Code "@Include { mydiag }"}, then
+edit @Code "mydiag" and change the options as you wish.
+@PP
+If you are using several packages and you would like a single setup file,
+that is quite easy to arrange.  For example, suppose you have
+@ID @Code {
+"@Include { mydoc }"
+"@Include { mydiag }"
+"@Include { mycprint }"
+}
+To create a single setup file, just concatenate these three files into
+one file (call it @Code { mysetup }, say), and replace the three lines by
+@ID @Code {
+"@Include { mysetup }"
+}
+As explained earlier, you can even replace the @Code "@Include { mydefs }"
+line within the setup file by the actual definitions, giving just one
+file of setup material for the entire document.
+@End @Section
diff --git a/doc/user/fmt_size b/doc/user/fmt_size
new file mode 100644
index 0000000..8e4a258
--- /dev/null
+++ b/doc/user/fmt_size
@@ -0,0 +1,91 @@
+@Section
+    @Title { Page size and page orientation }
+    @Tag { pagesize }
+@Begin
+@PP
+This section explains how to use the setup file options that determine
+page size and page orientation.  Here they are with their default values:
+page.type @Index @Code "@PageType"
+@ID @OneRow @Code {
+"@PageType { A4 }"
+"@PageWidth {}"
+"@PageHeight {}"
+"@PageOrientation { Portrait }"
+}
+The usual way to determine the page size is to set the @Code "@PageType"
+option to the name of the paper you use:
+@ID @Tab
+    vmargin { 0.5vx }
+    @Fmtb { @Col ! @Col ! @Col @I @RR B ! @Col @I @RR C }
+    @Fmta { @Col @Code { "@PageType {" A "}" } ! @Col ! @Col @Code @CC B !
+            @Col @Code @CC C }
+{
+@Rowb B { width in points }          C { height in points }
+@Rowa A { Letter }	B {  612p }  C {  792p }
+@Rowa A { Tabloid }	B {  792p }  C { 1224p }
+@Rowa A { Ledger }	B { 1224p }  C {  792p }
+@Rowa A { Legal  }	B {  612p }  C { 1008p }
+@Rowa A { Statement }	B {  396p }  C {  612p }
+@Rowa A { Executive }	B {  540p }  C {  720p }
+@Rowa A { A3 }		B {  842p }  C { 1190p }
+@Rowa A { A4 }		B {  595p }  C {  842p }
+@Rowa A { A5 }		B {  420p }  C {  595p }
+@Rowa A { B4 }		B {  729p }  C { 1032p }
+@Rowa A { B5 }		B {  516p }  C {  729p }
+@Rowa A { Folio }	B {  612p }  C {  936p }
+@Rowa A { Quarto }	B {  610p }  C {  780p }
+@Rowa A { 10x14 }	B {  720p }  C { 1008p }
+}
+This will automatically assign the widths and heights shown above to
+the @Code "@PageWidth" and @Code "@PageHeight" options, so you don't
+have to worry about those options.  If your paper size is not on this
+list, set @Code "@PageType" to @Code Other and supply your own width
+and height:
+page.width @Index @Code "@PageWidth"
+page.height @Index @Code "@PageHeight"
+@ID @Tab
+    vmargin { 0.5vx }
+    @Fmta { @Col @Code A }
+{
+@Rowa A { "@PageType { Other }" }
+@Rowa A { "@PageWidth { 12.0c }" }
+@Rowa A { "@PageHeight { 18.0c }" }
+}
+The width and height may each be any length (Section {@NumberOf objects}),
+and do not have to be in points.
+@PP
+The basic page orientations are @I portrait and @I landscape:
+page.orientation @Index @Code "@PageOrientation"
+@ID @Tab
+    @Fmta { @Col 8c @Wide @Code A ! @Col B }
+{
+@Rowa
+    A { "@PageOrientation { Portrait }" }
+    B { @Box 1.0c @Wide 1.4c @High { Hello } }
+@Rowa
+@Rowa
+    A { "@PageOrientation { Landscape }" }
+    B { @Box 1.4c @Wide 1.0c @High { Hello } }
+}
+When changing to {@Code Landscape}, do not change the page type, page
+width, or page height, and do not change the way you feed your paper
+into the printer.  Lout knows what to do.
+@PP
+Two other orientations are provided which are 180@Degree rotations of
+the basic ones:
+@ID @Tab
+    @Fmta { @Col 8c @Wide @Code A ! @Col B }
+{
+@Rowa
+    A { "@PageOrientation { ReversePortrait }" }
+    B { @Box 1.0c @Wide 1.4c @High { //1rt &1rt 180d @Rotate Hello } }
+@Rowa
+@Rowa
+    A { "@PageOrientation { ReverseLandscape }" }
+    B { @Box 1.4c @Wide 1.0c @High { //1rt &1rt 180d @Rotate Hello } }
+}
+@Code ReverseLandscape might be useful when post-processing the PostScript output
+to print two landscape pages per sheet.  The @Code "@PageOrientation" symbol is
+available at the start of a document, as well as in the setup file, like
+{@Code "@InitialFont"} and {@Code "@PageHeaders"}.
+@End @Section
diff --git a/doc/user/gra b/doc/user/gra
new file mode 100644
index 0000000..58c73ac
--- /dev/null
+++ b/doc/user/gra
@@ -0,0 +1,46 @@
+@Chapter
+  @Title { Graphs }
+  @Tag { graphs }
+@Begin
+@LP
+This chapter describes how to draw graphs, using the @Code "@Graph"
+graphs. @Index { graphs (statistical) }
+graph. @Index @Code "@Graph"
+symbol.  For example,
+@ID @OneRow @Code {
+"@Graph"
+"    abovecaption { New South Wales road deaths, 1960--1990"
+"(fatalities per 100 million vehicle km) }"
+"{"
+"    @Data  points { plus }  pairs { dashed }"
+"    { 1963 5.6  1971 4.3  1976 3.7  1979 3.4  1982 2.9  1985 2.3  1988 2.0 }"
+"}"
+}
+produces the graph
+@CD @Graph
+    abovecaption { New South Wales road deaths, 1960--1990
+(fatalities per 100 million vehicle km) }
+{
+    @Data
+        points { plus }
+        pairs { dashed }
+    {
+        1963 5.6  1971 4.3  1976 3.7  1979 3.4  1982 2.9  1985 2.3  1988 2.0
+    }
+}
+The features of @Code "@Graph" include captions, automatic and manual
+ticks and labels, logarithmic axes, histograms, and plotting of
+mathematical functions.
+@BeginSections
+@Include { gra_intr }
+@Include { gra_over }
+@Include { gra_capt }
+@Include { gra_tick }
+@Include { gra_data }
+@Include { gra_plac }
+@Include { gra_func }
+@Include { gra_keys }
+@Include { gra_erro }
+@Include { gra_summ }
+@EndSections
+@End @Chapter
diff --git a/doc/user/gra_capt b/doc/user/gra_capt
new file mode 100644
index 0000000..089e6e5
--- /dev/null
+++ b/doc/user/gra_capt
@@ -0,0 +1,72 @@
+@Section
+   @Title { Captions }
+   @Tag { captions }
+@Begin
+@PP
+There are options for placing captions above, below, left, and right of
+captions.graphs @SubIndex { in graphs }
+the frame:
+@ID @OneRow @Code {
+"@Graph"
+"    abovecaption { This appears above }"
+"    belowcaption { This appears below }"
+"    leftcaption { At left }"
+"    rightcaption { At right }"
+"{"
+"}"
+}
+produces
+@CD @Graph
+    abovecaption { This appears above }
+    belowcaption { This appears below }
+    leftcaption { At left }
+    rightcaption { At right }
+{
+}
+The captions may be arbitrary Lout objects, so may include
+equations, {@Code "@Rotate"}, and so on.  Each caption except
+@Code rightcaption is printed in the
+@Code "clines @Break" style, which means that multiple lines in one
+caption will be centred beneath each other.  The @Code rightcaption
+option uses the @Code "lines @Break" style, in which the lines are
+left justified beneath each other.  Incidentally, this example shows
+what happens if there is no data.
+@PP
+There are options for controlling the amount of space between each
+caption (when non-empty) and the frame.  Here they are with their
+default values:
+@ID @OneRow @Code {
+"@Graph"
+"    abovegap { 0.5 cm }"
+"    belowgap { 0.5 cm }"
+"    leftgap { 1.5 cm }"
+"    rightgap { 0.5 cm }"
+"{"
+"    ..."
+"}"
+}
+This is particularly important in the case of {@Code "leftgap"} (and
+@Code "rightgap" if @Code rticks is used), because
+Lout has no idea how wide the ticks and labels attached to the y axis
+are; 1.5 cm is just a wild guess and often needs adjustment.  On the
+other hand, Lout does know how high the ticks and labels on the x axis
+are; it allows 1.7 times the current font size for them, and
+@Code "belowgap" is additional to this.
+@PP
+When a graph is to be presented as a centred display, it is generally
+best if the centring is done with respect to the frame alone, not the
+captions, ticks, and labels.  The @Code "hidecaptions" option does this by
+making the left and right captions and gaps seem to Lout to have zero width:
+@ID @OneRow @Code {
+"@Graph"
+"    hidecaptions { yes }"
+"{"
+"    ..."
+"}"
+}
+Actually @Code "yes" has been made the default value, since the vast
+majority of graphs are centred displays.  In the rare cases where
+this feature is not wanted (for example, if a graph appears as an entry
+in a table), use {@Code "hidecaptions { no }"}.  The y and r ticks and labels
+seem to Lout to have zero width already, so do not need to be hidden.
+@End @Section
diff --git a/doc/user/gra_data b/doc/user/gra_data
new file mode 100644
index 0000000..323f155
--- /dev/null
+++ b/doc/user/gra_data
@@ -0,0 +1,267 @@
+@Section
+   @Title { Changing the appearance of the data }
+   @Tag { data }
+@Begin
+@PP
+The @Code "@Data" symbol has options for controlling the
+data. @Index @Code "@Data"
+appearance of its data.  We have already seen the
+@Code "points" option, which controls what is printed at each data
+point:
+points.graphs @Index { @Code "points" option in graphs }
+@CD @Tab
+   vmargin { 0.5vx }
+   @Fmta { @Col @Code A ! @Col B ! @Col ! @Col @Code C ! @Col D }
+{
+@Rowa
+    A { cross }
+    B { @GraphCross }
+    C { plus }
+    D { @GraphPlus }
+@Rowa
+    A { square }
+    B { @GraphSquare }
+    C { filledsquare }
+    D { @GraphFilledSquare }
+@Rowa
+    A { diamond }
+    B { @GraphDiamond }
+    C { filleddiamond }
+    D { @GraphFilledDiamond }
+@Rowa
+    A { circle }
+    B { @GraphCircle }
+    C { filledcircle }
+    D { @GraphFilledCircle }
+@Rowa
+    A { triangle }
+    B { @GraphTriangle }
+    C { filledtriangle }
+    D { @GraphFilledTriangle }
+}
+If the @Code "points" option is omitted or empty, nothing is printed.  The
+symbols are centred over the data point.  There is a @Code "symbolsize"
+option which controls the size (radius) of all these symbols:
+symbolsize. @Index { @Code "symbolsize" option in graphs }
+@ID @OneRow @Code {
+"@Data"
+"    symbolsize { 0.15 ft }"
+}
+shows the default, 0.15 times the current font size.  More
+precisely, the default value is taken from an option
+to the @Code "@Graph" symbol, also called {@Code "symbolsize"}.  By
+setting that option you can therefore set the symbol size of all data
+points in the graph at once; its default value is {@Code "0.15 ft"}.
+@PP
+The @Code "@Data" symbol also has a @Code "pairs" option which
+pairs. @Index { @Code "pairs" option in graphs }
+determines how each pair of points is connected.  The choices are
+@Code none (not connected, the default), @Code solid (a solid line),
+@Code dashed (a dashed line), or @Code dotted (a dotted line).  For
+example,
+@ID @OneRow @Code {
+"@Graph"
+"    abovecaption { Estimated population of Boston, New York, and Philadelphia }"
+"{"
+"    @Data  points { plus }  pairs { solid }"
+"    { 1720 12000  1730 13000  1740 15601  1760 15631  1770 15877 }"
+""
+"    @Data  points { plus }  pairs { dashed }"
+"    { 1720 7000  1730 8622  1740 10451  1750 14255  1760 18000  1770 22667 }"
+""
+"    @Data  points { plus }  pairs { dotted }"
+"    { 1720 10000  1730 11500  1740 12654  1750 18202  1760 23750  1770 34583 }"
+"}"
+}
+produces
+@CD @Graph
+    abovecaption { Estimated population of Boston, New York, and Philadelphia
+}
+{
+    @Data  points { plus }  pairs { solid }
+    { 1720 12000  1730 13000  1740 15601  1760 15631  1770 15877 }
+
+    @Data  points { plus }  pairs { dashed }
+    { 1720 7000  1730 8622  1740 10451  1750 14255  1760 18000  1770 22667 }
+
+    @Data  points { plus }  pairs { dotted }
+    { 1720 10000  1730 11500  1740 12654  1750 18202  1760 23750  1770 34583 }
+
+}
+(R. C. Simmons, @I { The American Colonies }, W. W. Norton, New York,
+1981.)  We will see in Section {@NumberOf key} how to add an explanatory key to
+this graph.  If the points have symbols, these connecting lines will stop 1.5
+symbolsizes away from the data points, so as not to overstrike them.  If
+the points have no symbols and @Code "pairs" is {@Code "dashed"}, the
+first and last dash in each segment will have half the length of the
+others.
+@PP
+A @Code "dashlength" option controls the length of dashes and also the
+separation between dots, and a @Code "linewidth" option controls the
+width (thickness) of the lines and dots:
+@ID @OneRow @Code {
+"@Data"
+"    dashlength { 0.2 ft }"
+"    linewidth { 0.5 pt }"
+"{"
+"    ..."
+"}"
+}
+This shows the default values, {@Code "0.2 ft"} for @Code "dashlength"
+and {@Code "0.5 pt"} (half a point) for {@Code "linewidth"}.  Actually
+the default value for @Code "linewidth" is whatever happens to be
+already in use, but Lout sets line widths to half a point initially.
+This option also controls the separation between bars in histograms.
+@PP
+The @Code "pairs" option is also used for producing histograms, like
+histograms. @Index { histograms }
+this:
+@ID @OneRow @Code {
+"@Graph"
+"    hidecaptions { yes }"
+"    abovecaption { Computer Science 3 Results (1993) }"
+"    leftcaption { Number of"
+"students }"
+"    belowcaption { Final mark (%) }"
+"    yextra { 0 cm }"
+"    ymax { 80 }"
+"{"
+"    @Data pairs { yhisto }"
+"    { 0 1 10 3 20 2 30 4 40 15 50 60 60 58 70 28 80 15 90 7 100 0 }"
+"}"
+}
+which has result
+@CD @Graph
+    hidecaptions { yes }
+    abovecaption { Computer Science 3 Results (1993) }
+    leftcaption { Number of
+students }
+    belowcaption { Final mark (%) }
+    yextra { 0 cm }
+    ymax { 80 }
+{
+    @Data
+        pairs { yhisto }
+    { 0 1 10 3 20 2 30 4 40 15 50 60 60 58 70 28 80 15 90 7 100 0 }
+}
+Note carefully that one y histogram rectangle occupies the space from
+one x value to the next, with height equal to the y value lying between
+these two x values.  This means that the very last y value has no effect
+on the result (however, there must be a last y value anyway).
+@PP
+There is an alternative to @Code "yhisto" called {@Code "surfaceyhisto"}:
+@CD @Graph
+    hidecaptions { yes }
+    abovecaption { Computer Science 3 Results (1993) }
+    leftcaption { Number of
+students }
+    belowcaption { Final mark (%) }
+    yextra { 0 cm }
+    ymax { 80 }
+{
+    @Data
+        pairs { surfaceyhisto }
+    { 0 1 10 3 20 2 30 4 40 15 50 60 60 58 70 28 80 15 90 7 100 0 }
+}
+As you can see, @Code "surfaceyhisto" draws just the surface of the
+histogram, not the descending lines.
+@PP
+There are @Code "xhisto" and @Code "surfacexhisto" values of
+@Code "pairs" which produce a histogram whose bars are parallel to
+the x axis.  There are also {@Code "filledyhisto" } and
+{@Code "filledxhisto" } values which produce filled rectangles rather
+than outlined ones:
+@ID @OneRow @Code {
+"@Graph"
+"    abovecaption { Fertility rates in some developing countries }"
+"    xextra { 0 cm }"
+"    yextra { 0 cm }"
+"    xmax { 8 }"
+"    yticks {"
+"        1.5 (Turkey) 2.5 (Thailand)"
+"        3.5 (Indonesia) 4.5 (Costa Rica)"
+"        5.5 (Colombia) 6.5 (Cameroon)"
+"        7.5 (Botswana) 8.5 (Bangladesh)"
+"    }"
+"    yticklength { 0 cm }"
+"{"
+"    @Data"
+"        pairs { filledxhisto }"
+"    { 0 1 3.2 2 2.2 3 3.0 4 3.5 5 2.8 6 5.9 7 4.8 8 5.3 9 }"
+"}"
+}
+produces
+@CD @Graph
+    abovecaption { Fertility rates in some developing countries
+    }
+    xextra { 0 cm }
+    yextra { 0 cm }
+    xmax { 8 }
+    yticks { 1.5 (Turkey) 2.5 (Thailand) 3.5 (Indonesia) 4.5 (Costa Rica)
+             5.5 (Colombia) 6.5 (Cameroon) 7.5 (Botswana) 8.5 (Bangladesh) }
+    yticklength { 0 cm }
+{
+    @Data
+        pairs { filledxhisto }
+    { 0 1 3.2 2 2.2 3 3.0 4 3.5 5 2.8 6 5.9 7 4.8 8 5.3 9 }
+}
+(Bryant Robey, Shea O. Rutstein, and Leo Morros:  The fertility decline in
+developing countries, @I { Scientific American }, December 1993.)  Once
+again each bar goes from one y value to the next, with its x value
+equal to the x value lying between the two y values; this time the very
+first x value has no effect on the result.
+@PP
+The colour of one set of data can be changed with a @Code "colour"
+option:
+@ID @OneRow @Code {
+"@Data"
+"    colour { blue }"
+}
+For the complete list of acceptable colour names, see Section
+{@NumberOf colour}.  The @Code "colour" option's name may also be
+spelt @Code {"color"}.
+@PP
+It is also possible to paint the area between the data points and
+the x axis (or frame if @Code "style" is not {@Code "axes"}), using
+@ID @OneRow @Code {
+"@Data"
+"    paint { yes }"
+}
+The paint colour is determined by the @Code "colour" option just
+introduced; it will be @Code "black" if no colour is specified.  Paint
+(including white paint) hides paint, points, and lines drawn by previous
+data sets.  However the points and lines of each data set are drawn after
+painting that set, so they cannot be hidden under their own paint; and
+axes and frames are drawn last so that they too are never hidden.
+@PP
+A @Code "dataformat" option is provided for changing the interpretation
+dataformat. @Index { @Code "dataformat" option in graphs }
+of the data.  Ordinarily, as we know, the numbers are taken to be pairs of
+x and y coordinates, like this:
+@ID @OneRow @Code {
+"@Data"
+"{"
+"    x y  x y  ...  x y"
+"}"
+}
+However, by setting @Code "dataformat" to {@Code "yonly"}, the
+interpretation is changed to a sequence of y coordinates only:
+@ID @OneRow @Code {
+"@Data"
+"    dataformat { yonly }"
+"{"
+"    y y  ...  y"
+"}"
+}
+and x values 1, 2, and so on are inserted automatically, just as though
+the original input had been
+@ID @OneRow @Code {
+"@Data"
+"{"
+"    1 y  2 y  ..."
+"}"
+}
+There is also {@Code "xonly"}, which inserts y values 1, 2, and so on.  The
+default value, {@Code "xandy"}, gives the usual interpretation.  The
+layout of data on lines has no effect on the interpretation.
+@End @Section
diff --git a/doc/user/gra_erro b/doc/user/gra_erro
new file mode 100644
index 0000000..3c123a3
--- /dev/null
+++ b/doc/user/gra_erro
@@ -0,0 +1,40 @@
+@Section
+   @Title { Errors }
+   @Tag { grerrors }
+@Begin
+@PP
+Lout normally produces output that will print without mishap on
+any PostScript device.  However, some of the options of @Code "@Graph"
+and all of the data and labels are passed through Lout without
+checking.  Any errors in this material will not be detected
+until the file is printed.
+@PP
+The most likely errors are @I { rangecheck errors}, for example if
+an attempt is made to divide by zero or take the square root of a
+negative number, and @I { undefined errors }, arising from symbols
+misspelt, use of @Code "x" outside an {@Code "xloop"}, etc.  Less commonly,
+everything may be correct but the graph is too large in some
+way:  too much data, expression too deeply nested, and so on.
+@PP
+When an error is detected, @Code "@Graph" arranges for the offending page
+to be printed up to the point where the error occurred, with a message
+nearby describing the error.  Printing of the document is then
+aborted.  The problem is usually easy to locate since it lies in whatever
+should have been printed next.
+@PP
+If you see @Code VMerror in an error message, it means that the printer
+has run out of memory.  All the data is stored in the printer while the
+graph is being printed, and it remains there until the end of the current
+page, when it is discarded and all memory consumed by the graph is
+reclaimed.  If you do run out of memory, one option is to try
+@ID @Code {
+"@Graph"
+"    save { yes }"
+"..."
+}
+This causes the memory used by the graph to be reclaimed as soon as
+the graph is printed, which might well solve your problem if you have
+several graphs on one page.  However, if the graph is nested
+inside some other major Lout package, notably {@Code "@Diag"}, this
+option could cause PostScript errors in that package.
+@End @Section
diff --git a/doc/user/gra_func b/doc/user/gra_func
new file mode 100644
index 0000000..d30e82c
--- /dev/null
+++ b/doc/user/gra_func
@@ -0,0 +1,179 @@
+@Section
+   @Title { Mathematical functions, loops, and tests }
+   @Tag { functions }
+@Begin
+@PP
+@Code "@Graph" offers quite a large selection of mathematical functions,
+mathematical.functions @Index { mathematical functions in graphs }
+available everywhere that x and y coordinates are required:  within
+the @Code xticks and @Code yticks options, within the points within
+the @Code "objects" option, and within the right parameter of the
+@Code "@Data" symbol.  For example,
+@ID @OneRow @Code {
+"@Data"
+"    pairs { solid }"
+"{"
+"    0 0  pi sin { pi/2 }"
+"}"
+}
+draws a solid line from @Eq {(0, 0)} to @Eq {(pi, sin(pi "/" 2))}.  Section
+{@NumberOf grsummary} lists all the functions; they include the four
+arithmetical operators @Eq { non + }, @Eq { non - }, @Eq { non * }, and
+@Eq { "/" }, as well as {@Code "sin"}, {@Code "cos"}, {@Code "sqrt"}, and
+many others.  Braces are used for grouping, never parentheses.
+@PP
+For plotting functions there are three looping symbols, {@Code "xloop"},
+{@Code "yloop"}, and {@Code "zloop"}.  For example, the following plots
+the two functions @Eq { y = 2 } and @Eq { y = sqrt { pi x "/" 4 } + 1 }
+for @Eq { x } from 10 to 500:
+@ID @OneRow @Code {
+"-2p @Font @Graph"
+"    style { axes }"
+"    xorigin { 0 }"
+"    yorigin { 0 }"
+"    width { 8 cm }"
+"    xticks { 10@ 50@ 100@ 200@ 500@ }"
+"    objects {  @NE at { 300 2 } @I { Exponential }"
+"               @SE at { 300 sqrt { pi*300/4 } + 1 } @I { Uniform } }"
+"    belowcaption { @I n }"
+"    belowgap { 0 cm }"
+"    leftcaption { Right shell nodes }"
+"{"
+"    @Data points { filledcircle }"
+"    { 10 1.97  50 2.01  100 2.00  200 2.0  500 2.00 }"
+""
+"    @Data points { filledcircle }"
+"    { 10 3.53  50 7.45  100 9.32  200 13.41  500 21.63 }"
+""
+"    @Data pairs { dashed }"
+"    { 10 2  500 2 }"
+""
+"    @Data pairs { dashed }"
+"    {"
+"        xloop from { 10 } to { 500 } by { 20 } do"
+"        {"
+"            x  sqrt { pi*x / 4 } + 1"
+"        }"
+"    }"
+"}"
+}
+The @Code "do" option of @Code xloop is replicated repeatedly with each
+occurrence of @Code x replaced by 10, 30, 50, ... up to 490.  The
+result is
+@FootNote { Source:  Jeffrey H. Kingston, Analysis of tree algorithms
+for the simulation event list.  @I { Acta Informatica } {@B 22},
+pp. 15--33 (1985). }
+@CD -2p @Font @Graph
+    style { axes }
+    xorigin { 0 }
+    yorigin { 0 }
+    width { 8 cm }
+    xticks { 10@ 50@ 100@ 200@ 500@ }
+    objects {
+       @NE at { 300 2 } @I { Exponential }
+       @SE at { 300 sqrt { pi*300/4 } + 1 } @I { Uniform }
+    }
+    belowcaption { @I n }
+    belowgap { 0 cm }
+    leftcaption { Right shell nodes }
+{
+    @Data points { filledcircle }
+    { 10 1.97  50 2.01  100 2.00  200 2.0  500 2.00 }
+
+    @Data points { filledcircle }
+    { 10 3.53  50 7.45  100 9.32  200 13.41  500 21.63 }
+
+    @Data pairs { dashed }
+    { 10 2  500 2 }
+
+    @Data pairs { dashed }
+    {
+        xloop from { 10 } to { 500 } by { 20 } do
+        {
+            x  sqrt { pi*x / 4 } + 1
+        }
+    }
+}
+The points are connected by straight line segments as usual, but a
+smallish @Code "by" option of about one-twentieth of the range creates
+the illusion of a smooth curve quite well.
+@PP
+There is also an @Code "if" symbol which produces alternative results,
+depending on whether a condition evaluates to @Code "true" or
+{@Code"false"}:
+@ID @OneRow @Code {
+"xloop from { -5 } to { +5 } by { 0.2 } do"
+"{"
+"    if cond { abs { x } > 0.1 } then { x 1/x } else {}"
+"}"
+}
+This plots the function @Eq { y = 1 "/" x }, skipping points near
+zero.  Actually the @Code "else" part could be omitted since its default
+value is empty.
+@PP
+Adventurous users might enjoy nesting a @Code "yloop" or @Code "zloop"
+within an {@Code "xloop"}, or using loops to generate ticks, like this:
+@ID @OneRow @Code {
+"xticks {"
+"    xloop from { 0 } to { 20 } do"
+"    {"
+"       x if cond { x mod 5 = 0 } then { @ }"
+"    }"
+"}"
+}
+The missing @Code "by" option defaults to 1, so this produces x ticks at
+0, 1, 2, ..., 20, with labels at 0, 5, 10, 15, and 20.  It is quite all
+right to mix @Code "@" and even labels in with numbers, as long as the
+final result obeys the rules of Section {@NumberOf ticks}.
+@PP
+You can define your own functions using Lout definitions, placed in your
+@Code "mydefs" file as explained in Section {@NumberOf definitions}.  Here
+is an example of a function definition:
+@ID @OneRow @Code {
+"import @Graph @Data"
+"def @Tan"
+"    precedence 40"
+"    right x"
+"{"
+"    sin x / cos x"
+"}"
+}
+This defines a function called @Code "@Tan" which implements the
+trigonometric tangent function.  It may then be used in expressions
+just like any other function:
+@ID @OneRow @Code {
+"@Data {"
+"    yloop from { 0 } to { 0.95 } by { 0.05 } do"
+"    {"
+"        y   @Tan { y / pi }"
+"    }"
+"}"
+}
+Following is a detailed explanation.
+@PP
+The first line, {@Code "import @Graph @Data"}, is the import clause.  Its
+function is to grant the definition access to the three previously defined
+functions (symbols) that it uses, namely {@Code "sin"}, {@Code "cos"},
+and {@Code "/"}.  These are found within the @Code "@Data" symbol within
+{@Code "@Graph"}.
+@PP
+After the import clause comes the @Code "def" keyword, meaning
+`define,' and then the name of the symbol being defined, in this case
+@Code "@Tan".  We have chosen @Code "@Tan" rather than @Code "tan"
+because symbols defined by the user in this way are visible throughout
+the document, and we do not want the literal word @Code "tan" to be
+taken as a symbol.
+@PP
+Next comes the symbol's precedence, in this case the same as @Code "sin" and
+@Code "cos" (see Section {@NumberOf dia_summ} for the precedence of
+each symbol).  Next is a list of the formal parameters, in this case
+just one, called {@Code "x"}, that is to be passed on the right.
+@PP
+Finally comes the body of the definition enclosed in braces.  When
+@Code "@Tan" is invoked, its value will be this body with each occurrence
+of the formal parameter @Code "x" replaced by the object following the
+@Code "@Tan" symbol.  For example, the @Code "do" option of the @Code
+"yloop" above becomes
+@ID @Code "y   sin { y / pi } / cos { y / pi }"
+as you would expect.
+@End @Section
diff --git a/doc/user/gra_intr b/doc/user/gra_intr
new file mode 100644
index 0000000..28dfd1b
--- /dev/null
+++ b/doc/user/gra_intr
@@ -0,0 +1,51 @@
+@Section
+   @Title { Introduction }
+   @Tag { grintro }
+@Begin
+@PP
+The Lout definitions for graph formatting are kept in a file called
+{@Code "graph"}, which you must include at the start of your document if
+graph.file @Index { @Code "graph" file }
+you want graphs, like this:
+@ID @OneRow @Code {
+"@SysInclude { graph }"
+"@SysInclude { doc }"
+"@Doc @Text @Begin"
+"..."
+"@End @Text"
+}
+Setup files for specialized packages, such as {@Code "graph"}, should be
+included before the main setup file.  Once this is done, the @Code "@Graph"
+symbol used below will then be available for use anywhere within your document.
+@PP
+@Code "@Graph" distinguishes between the overall graph, produced by the
+@Code "@Graph" symbol itself, and the data sets to be placed within it,
+each of which is enclosed by a @Code "@Data" symbol:
+@ID @OneRow @Code {
+"@CentredDisplay @Graph"
+"{"
+"    @Data  points { plus }"
+"    { 1 1.10  2 1.21  3 1.33  4 1.46  5 1.61  6 1.77  7 1.95  8 2.14 }"
+""
+"    @Data  points { circle }"
+"    { 1 1.20  2 1.44  3 1.73  4 2.07  5 2.45  6 2.99  7 3.58  8 4.30 }"
+"}"
+}
+Although it is good practice to lay the input data out neatly, layout
+has no effect on the result.  It is not necessary to have one data point
+per line, for example.  The result of this example is
+@CentredDisplay @Graph
+{
+    @Data
+        points { plus }
+    { 1 1.10  2 1.21  3 1.33  4 1.46  5 1.61  6 1.77  7 1.95  8 2.14 }
+
+    @Data
+        points { circle }
+    { 1 1.20  2 1.44  3 1.73  4 2.07  5 2.45  6 2.99  7 3.58  8 4.30 }
+}
+We have used the @Code "@CentredDisplay" symbol from Section
+{@NumberOf displays} to produce a centred display, but the
+@Code "@Graph" symbol produces an object which may appear anywhere
+at all -- in a figure, for example, or as an entry in a table.
+@End @Section
diff --git a/doc/user/gra_keys b/doc/user/gra_keys
new file mode 100644
index 0000000..089139a
--- /dev/null
+++ b/doc/user/gra_keys
@@ -0,0 +1,104 @@
+@Section
+   @Title { Adding a key to the graph }
+   @Tag { key }
+@Begin
+@PP
+A @I key to a graph is an explanation of what each data set
+key. @Index { key in graph }
+represents.  To assist you in constructing a key, some extra symbols
+are provided in addition to {@Code "@Graph"}:
+graph.cross @Index @Code "@GraphCross"
+graph.plus @Index @Code "@GraphPlus"
+graph.square @Index @Code "@GraphSquare"
+graph.filled.square @Index @Code "@GraphFilledSquare"
+graph.diamond @Index @Code "@GraphDiamond"
+graph.filled.diamond @Index @Code "@GraphFilledDiamond"
+graph.circle @Index @Code "@GraphCircle"
+graph.filled.circle @Index @Code "@GraphFilledCircle"
+graph.triangle @Index @Code "@GraphTriangle"
+graph.filled.triangle @Index @Code "@GraphFilledTriangle"
+graph.noline @Index @Code "@GraphNoLine"
+graph.solid @Index @Code "@GraphSolid"
+graph.dashed @Index @Code "@GraphDashed"
+graph.dotted @Index @Code "@GraphDotted"
+@ID @Tab
+    @Fmta { @Col @Code A ! @Col B ! @Col @Code C ! @Col D }
+{
+@Rowa
+    A { "@GraphCross" }
+    B { @GraphCross }
+    C { "@GraphPlus" }
+    D { @GraphPlus }
+@Rowa
+    A { "@GraphSquare" }
+    B { @GraphSquare }
+    C { "@GraphFilledSquare" }
+    D { @GraphFilledSquare }
+@Rowa
+    A { "@GraphDiamond" }
+    B { @GraphDiamond }
+    C { "@GraphFilledDiamond" }
+    D { @GraphFilledDiamond }
+@Rowa
+    A { "@GraphCircle" }
+    B { @GraphCircle }
+    C { "@GraphFilledCircle" }
+    D { @GraphFilledCircle }
+@Rowa
+    A { "@GraphTriangle" }
+    B { @GraphTriangle }
+    C { "@GraphFilledTriangle" }
+    D { @GraphFilledTriangle }
+@Rowa
+@Rowa
+    A { "@GraphNoLine" }
+    B { @GraphNoLine }
+@Rowa
+    A { "@GraphSolid" }
+    B { @GraphSolid }
+@Rowa
+    A { "@GraphDashed" }
+    B { @GraphDashed }
+@Rowa
+    A { "@GraphDotted" }
+    B { @GraphDotted }
+}
+These extra symbols may be used anywhere in your document except within
+the right parameter of {@Code "@Graph"}; they are commonly used within
+the caption options of {@Code "@Graph"}:
+@ID @OneRow @Code {
+"@Graph"
+"    rightcaption {"
+"@GraphPlus @GraphSolid @GraphPlus  Boston"
+"@GraphPlus @GraphDashed @GraphPlus  New York"
+"@GraphPlus @GraphDotted @GraphPlus  Philadelphia"
+"}"
+}
+Recall that unlike the other captions, @Code rightcaption is set using
+the @Code "lines @Break" style rather than {@Code "clines @Break"}
+(Section {@NumberOf captions}).  Adding this caption to the graph
+from Section {@NumberOf data}, the complete result is
+@CD @Graph
+    rightcaption {
+@GraphPlus @GraphSolid @GraphPlus  Boston
+@GraphPlus @GraphDashed @GraphPlus  New York
+@GraphPlus @GraphDotted @GraphPlus  Philadelphia
+}
+{
+    @Data  points { plus }  pairs { solid }
+    { 1720 12000  1730 13000  1740 15601  1760 15631  1770 15877 }
+
+    @Data  points { plus }  pairs { dashed }
+    { 1720 7000  1730 8622  1740 10451  1750 14255  1760 18000  1770 22667 }
+
+    @Data  points { plus }  pairs { dotted }
+    { 1720 10000  1730 11500  1740 12654  1750 18202  1760 23750  1770 34583 }
+
+}
+The first eight symbols have a @Code "symbolsize" option with the
+usual meaning and the usual default value ({@Code "0.15 ft"}).  The
+last four symbols have @Code "dashlength" and @Code "linewidth" options
+with the usual default values, {@Code "0.2 ft"} and {@Code "0.5 pt"}
+respectively, and a @Code "length" option, which determines the length
+of the line drawn by each symbol; its default value is {@Code "1.0 ft"}.
+@End @Section
diff --git a/doc/user/gra_over b/doc/user/gra_over
new file mode 100644
index 0000000..1b9653a
--- /dev/null
+++ b/doc/user/gra_over
@@ -0,0 +1,179 @@
+@Section
+   @Title { Changing the overall appearance of the graph }
+   @Tag { overall }
+@Begin
+@PP
+The overall appearance of the graph is controlled by options to the
+@Code "@Graph" symbol.  As usual, these options follow the @Code "@Graph"
+symbol, with their values enclosed in braces; they may appear in any order,
+and if omitted are assigned some sensible default value.
+@PP
+There is a @Code "style" option for controlling the overall style of the
+style.graph @Index { @Code "style" option of @Code "@Graph" }
+axes. @Index { axes in graphs }
+graph, whose value may be either {@Code "frame"}, {@Code "none"},
+or {@Code "axes"}.  The default value is {@Code "frame"}, and it produces
+a frame around the graph with ticks and labels along its left and bottom
+edges, as in previous examples.  The {@Code "none"} style prints
+nothing (no frame, no ticks, no labels), which is useful for producing
+graphs that don't look like graphs, as it were.
+@PP
+If the other value, {@Code "axes"}, is chosen, two other options called
+{@Code xorigin} and {@Code yorigin} become compulsory:
+@ID @OneRow @Code {
+"-2p @Font @Graph"
+"    style { axes }"
+"    xorigin { 0 }"
+"    yorigin { 0 }"
+"    width { 12 cm }"
+"    height { 7 cm }"
+"    leftcaption { 90d @Rotate { counts (%) } }"
+"    leftgap { 1.0 cm }"
+"    belowcaption { time (min) }"
+"    belowgap { 0 cm }"
+"{"
+"    @Data"
+"        points { filledsquare }"
+"        pairs { solid }"
+"    { 0 0.0 1 4.8 2 7.0 3 15.2 4 19.8 5 20.0 6 21.0 7 25.0"
+"      10 29.5 15 31.2 20 35.0 30 40.0 60 50.8"
+"    }"
+""
+"    @Data"
+"        points { square }"
+"        pairs { solid }"
+"    {"
+"      0 0.0 1 3.7 1.5 43.1 2 99.1 3 85.6 4 69.1 5 47.0 6 44.1 7 40.8"
+"      10 35.0 15 29.4 20 25.0 30 21.1 60 15.5"
+"    }"
+"}"
+}
+We have requested a smaller font size for this graph as a whole by
+preceding it with {@Code "-2p @Font"}, meaning two points smaller, and
+we have used some other options which will be explained shortly.  The
+resulting graph has an x axis and a y axis instead of a frame, like this:
+@CD -2p @Font @Graph
+    style { axes }
+    xorigin { 0 }
+    yorigin { 0 }
+    width { 12 cm }
+    height { 7 cm }
+    leftcaption { 90d @Rotate { counts (%) } }
+    leftgap { 1.0 cm }
+    belowcaption { time (min) }
+    belowgap { 0 cm }
+{
+    @Data
+        points { filledsquare }
+        pairs { solid }
+    { 0 0.0 1 9.5 2 15.0 3 18.2 4 20.1 5 22.1 7 25.0
+      10 28.3 15 31.2 20 35.0 30 40.0 60 50.8
+    }
+
+    @Data
+        points { square }
+        pairs { solid }
+    {
+      0 0.0 1 3.7 1.5 43.1 2 99.1 3 85.6 4 69.1 5 47.0 6 44.1 7 40.8
+      10 35.0 15 29.4 20 25.0 30 21.1 60 15.5
+    }
+}
+The point where the axes cross is ({@Code xorigin}, {@Code yorigin}).
+@PP
+Although @Code "@Graph" does not provide explicit support for
+multiple axes, you can simulate them by overstriking two
+separate graphs of equal size.  There is an @Code "@OverStrike"
+overstrike. @Index @Code "@OverStrike"
+symbol which overstrikes two objects, so
+@ID @Code "@Graph { ... } @OverStrike @Graph { ... }"
+will do the job.  Typically one of the graphs would have y ticks,
+and the other would have r ticks (adjacent to the right-hand side of the
+frame).
+@PP
+There are @Code "xlog" and @Code "ylog" options which produce
+logarithmic.axes @Index { logarithmic axes in graphs }
+logarithmic x and y axes:
+@ID @OneRow @Code {
+"@Graph"
+"    xlog { 10 }"
+"    ylog { 10 }"
+"{"
+"    ..."
+"}"
+}
+The value is the base of the logarithm, usually 10 or 2, or
+{@Code none} (the default) meaning not logarithmic.  Logarithms
+to different bases differ only by a constant factor, so the main effect
+of different bases is on the choice of ticks and labels.  An @Code "xlog"
+option will be ignored if there are any negative or zero x data points,
+x ticks, or {@Code "xorigin"} or {@Code "xmin"} options; and similarly
+for {@Code "ylog"}.
+@PP
+There are @Code "width" and @Code "height" options for setting the size
+of the total area enclosed:
+@ID @OneRow @Code {
+"@Graph"
+"    width { 6.0 cm }"
+"    height { 4.0 cm }"
+"{"
+"    ..."
+"}"
+}
+This shows the default width and height, six centimetres and four
+centimetres.  These lengths and others discussed below can be specified
+using a variety of units of measurement (see Section {@NumberOf grsummary}
+for the details).
+@PP
+Within the frame or axes, a small margin is kept free of data points.  The
+size of this margin is controlled by @Code "xextra" and @Code "yextra"
+options:
+@ID @OneRow @Code {
+"@Graph"
+"    xextra { 0.5 cm }"
+"    yextra { 0.5 cm }"
+"{"
+"    ..."
+"}"
+}
+Setting @Code "xextra" to @Code "0.5 cm" (the default value if the
+@Code style option is {@Code frame}) means that the smallest x value
+will be placed 0.5 centimetres to the right of the left boundary, and
+the largest will be placed 0.5 centimetres to the left of the right
+boundary.  It is quite safe to set @Code "xextra" to @Code "0 cm" if
+desired, and indeed this is the default value when @Code style is
+{@Code axes} or {@Code none}.  The @Code "yextra" option works in
+exactly the same way for y values.
+@PP
+The @Code "xdecreasing" option plots the x values in decreasing order
+instead of increasing:
+@ID @Code {
+"@Graph"
+"    xdecreasing { yes }"
+"    abovecaption { New South Wales road deaths, 1960--1990"
+"(fatalities per 100 million vehicle km) }"
+"{"
+"    @Data"
+"        points { plus }"
+"        pairs { dashed }"
+"    {"
+"        1963 5.6  1971 4.3  1976 3.7  1979 3.4  1982 2.9  1985 2.3  1988 2.0"
+"    }"
+"}"
+}
+produces
+@CD @Graph
+    xdecreasing { yes }
+    abovecaption { New South Wales road deaths, 1960--1990
+(fatalities per 100 million vehicle km) }
+{
+    @Data
+        points { plus }
+        pairs { dashed }
+    {
+        1963 5.6  1971 4.3  1976 3.7  1979 3.4  1982 2.9  1985 2.3  1988 2.0
+    }
+}
+The value of @Code "xdecreasing" should be either @Code "no" (the default
+value) or {@Code "yes"}.  A similar @Code "ydecreasing" option does the same
+thing to the y axis.
+@End @Section
diff --git a/doc/user/gra_plac b/doc/user/gra_plac
new file mode 100644
index 0000000..7084eb2
--- /dev/null
+++ b/doc/user/gra_plac
@@ -0,0 +1,51 @@
+@Section
+   @Title { Placing arbitrary objects on the graph }
+   @Tag { arbobj }
+@Begin
+@PP
+As we have just seen, the repertoire of symbols that @Code "@Data" is
+able to place on the graph is quite limited.  However, there is a way
+to place any number of arbitrary Lout objects anywhere on the graph,
+using the @Code objects option to the @Code "@Graph" symbol:
+@ID @OneRow @Code {
+"@Graph"
+"    objects {"
+"        @CTR at {2.5  6.0}  @Eq { y = x sup 2 }"
+"        @CTR at {4.5  7.0}  @Eq { y = x sup 3 }"
+"    }"
+}
+where we have used the @Code "@Eq" symbol from Chapter {@NumberOf equations}
+twice to place two equations onto the graph at the points {@Code "2.5  6.0"}
+and {@Code "4.5 7.0"} respectively.  An example result appears in the next
+section.
+@PP
+In addition to {@Code "@CTR"}, there are eight other symbols which may
+be used within the @Code "objects" option in the same way:  {@Code "@NW"},
+{@Code "@SW"}, {@Code "@SE"}, {@Code "@NE"}, {@Code "@N"}, {@Code "@W"},
+{@Code "@S"}, and {@Code "@E"}.  These place the object just to the
+northwest of the point, to the southwest, and so on instead of centring
+it over the point.  By `to the northwest' we mean that the object's bottom
+right corner coincides with the point, and similarly for the other symbols.
+@PP
+Each of these symbols has a @Code "margin" option which enlarges the
+object by adding a margin around it before placing it:
+@ID @Code "@NW at {2.5  6.0} margin { 0.3 ft }  @Eq { y = x sup 2 }"
+shows the default value, 0.3 times the current font size.  As the margin
+is increased, the object moves further away from the point.
+@PP
+The major advantage of the @Code "objects" option over the @Code "@Data"
+symbol is that arbitrary Lout objects may be used.  The @Code "@Data"
+symbol however is able to place many copies of its symbols onto the graph,
+and also allow for them when connecting points together with lines.  Also,
+the points within the @Code "objects" option are not taken into account
+when deciding on the permissible range of x and y values, whereas the
+points within the @Code "@Data" symbol are.  Altogether it seems best
+to use the @Code "@Data" symbol for the bulk of the data points, and to
+use the @Code "objects" option for adding a small number of labels or
+other decorations.
+@PP
+The @Code "objects" option may contain @Code "@Graph" symbols, but in
+that case, owing to a deficiency in the implementation, those symbols
+will need to have their @Code save options (Section {@NumberOf grerrors})
+set to {@Code yes}.
+@End @Section
diff --git a/doc/user/gra_summ b/doc/user/gra_summ
new file mode 100644
index 0000000..ea074b9
--- /dev/null
+++ b/doc/user/gra_summ
@@ -0,0 +1,466 @@
+@Section
+   @Title { Summary }
+   @Tag { grsummary }
+@Begin
+@PP
+The options to the @Code "@Graph" symbol, their default values, and
+their possible values are:
+@ID -2.1px @Break -1p @Font @Tab
+   hmargin { 0.15c }
+   @Fmta { @Col @Code { "    "A } ! @Col @Code "{" ! @Col @Code B !
+	   @Col @Code "}" ! @Col ! @Col ! @Col C }
+   @Fmtb { @Col @Code A ! @Col ! @Col ! @Col ! @Col ! @Col ! @Col }
+{
+@Rowb
+    A { "@Graph" }
+@Rowa
+    A { style }
+    B { frame }
+    C { {@Code frame}, {@Code axes}, or {@Code none} }
+@Rowa
+    A { width }
+    B { 6.0 cm }
+    C { any @I distance }
+@Rowa
+    A { height }
+    B { 4.0 cm }
+    C { any @I distance }
+@Rowa
+    A { xextra }
+    B { 0.5 cm }
+    C { any @I distance ({@Code axes} and {@Code none} default is {@Code "0 cm"}) }
+@Rowa
+    A { yextra }
+    B { 0.5 cm }
+    C { any @I distance ({@Code axes} and {@Code none} default is {@Code "0 cm"}) }
+@Rowa
+    A { xdecreasing }
+    B { no }
+    C { @Code yes or @Code no }
+@Rowa
+    A { ydecreasing }
+    B { no }
+    C { @Code yes or @Code no }
+@Rowa
+    A { leftcaption }
+    B { }
+    C { any Lout object }
+@Rowa
+    A { rightcaption }
+    B { }
+    C { any Lout object }
+@Rowa
+    A { abovecaption }
+    B { }
+    C { any Lout object }
+@Rowa
+    A { belowcaption }
+    B { }
+    C { any Lout object }
+@Rowa
+    A { leftgap }
+    B { 1.5 cm }
+    C { any @I distance }
+@Rowa
+    A { rightgap }
+    B { 0.5 cm }
+    C { any @I distance }
+@Rowa
+    A { abovegap }
+    B { 0.5 cm }
+    C { any @I distance }
+@Rowa
+    A { belowgap }
+    B { 0.5 cm }
+    C { any @I distance }
+@Rowa
+    A { hidecaptions }
+    B { yes }
+    C { @Code yes or @Code no }
+@Rowa
+    A { xorigin }
+    B { none }
+    C { {@Code none} or any @I number }
+@Rowa
+    A { yorigin }
+    B { none }
+    C { {@Code none} or any @I number }
+@Rowa
+    A { xlog }
+    B { none }
+    C { {@Code none} or any @I number greater than 1 }
+@Rowa
+    A { ylog }
+    B { none }
+    C { {@Code none} or any @I number greater than 1 }
+@Rowa
+    A { xmin }
+    B { none }
+    C { @Code none or any {@I number} }
+@Rowa
+    A { xmax }
+    B { none }
+    C { @Code none or any {@I number} }
+@Rowa
+    A { ymin }
+    B { none }
+    C { @Code none or any {@I number} }
+@Rowa
+    A { ymax }
+    B { none }
+    C { @Code none or any {@I number} }
+@Rowa
+    A { xticksep }
+    B { none }
+    C { {@Code none} or any @I number greater than 0 }
+@Rowa
+    A { yticksep }
+    B { none }
+    C { {@Code none} or any @I number greater than 0 }
+@Rowa
+    A { rticksep }
+    B { none }
+    C { {@Code none} or any @I number greater than 0 }
+@Rowa
+    A { xticks }
+    B { auto  }
+    C { @I sequence (of numbers and strings), or @Code auto meaning
+automatic }
+@Rowa
+    A { yticks }
+    B { auto }
+    C { @I sequence (of numbers and strings), or @Code auto meaning
+automatic }
+@Rowa
+    A { rticks }
+    B { }
+    C { @I sequence (of numbers and strings), or @Code auto meaning
+automatic }
+@Rowa
+    A { xticklength }
+    B { 0.5 ft }
+    C { any @I distance }
+@Rowa
+    A { yticklength }
+    B { 0.5 ft }
+    C { any @I distance }
+@Rowa
+    A { rticklength }
+    B { 0.5 ft }
+    C { any @I distance }
+@Rowa
+    A { objects }
+    B { }
+    C { sequence of {@Code "@CTR"}, {@Code "@NW"}, {@Code "@SW"}, {@Code "@SE"},
+{@Code "@NE"}, {@Code "@N"}, {@Code "@W"}, {@Code "@S"}, {@Code "@E"} symbols }
+@Rowa
+    A { points }
+    B { none }
+    C { {@Code none}, {@Code plus}, {@Code cross}, {@Code square},
+{@Code filledsquare}, {@Code diamond}, {@Code filleddiamond},
+{@Code circle}, {@Code filledcircle}, {@Code triangle}, {@Code filledtriangle} }
+@Rowa
+    A { pairs }
+    B { none }
+    C { {@Code none}, {@Code solid}, {@Code dashed}, {@Code dotted},
+{@Code yhisto}, {@Code xhisto}, {@Code filledyhisto}, {@Code filledxhisto},
+{@Code surfaceyhisto}, {@Code surfacexhisto} }
+@Rowa
+    A { "colour/color" }
+    B { none }
+    C { {@Code none} or any colour name from Section {@NumberOf colour}}
+@Rowa
+    A { paint }
+    B { no }
+    C { {@Code no} or {@Code yes} }
+@Rowa
+    A { dataformat }
+    B { xandy }
+    C { {@Code xandy}, {@Code yonly}, {@Code xonly} }
+@Rowa
+    A { dashlength }
+    B { 0.2 ft }
+    C { any @I distance }
+@Rowa
+    A { linewidth }
+    B { 0.5 pt }
+    C { any @I distance }
+@Rowa
+    A { symbolsize }
+    B { 0.15 ft }
+    C { any @I distance }
+}
+@I Number means an ordinary decimal number; @I distance means a number
+followed by at least one space followed by any one of the following
+units of measurement:
+@ID @Tab
+    vmargin { 0.5vx }
+    @Fmta { @Col @Code A ! @Col B }
+{
+@Rowa
+    A { cm }
+    B { centimetres }
+@Rowa
+    A { in }
+    B { inches }
+@Rowa
+    A { em }
+    B { Ems (12 ems = 1 inch) }
+@Rowa
+    A { pt }
+    B { Points (72 points = 1 inch) }
+@Rowa
+    A { ft }
+    B { @Code "1 ft" is the size of the current font }
+@Rowa
+    A { sp }
+    B { @Code "1 sp" is the width of the space character in the current font }
+@Rowa
+    A { vs }
+    B { @Code "1 vs" is the current inter-line spacing }
+}
+In general, numbers denote x or y values while distances denote lengths
+on the printed result.
+@PP
+The minimum plottable x value is the minimum of all the x data,
+{@Code xticks}, {@Code xorigin}, {@Code xmin}, and {@Code xmax} whenever
+these are not {@Code none}.  If @Code xticks is {@Code none}, this
+minimum may be reduced further to a `round' number.  The maximum plottable
+x value is the maximum of the same values, and it may be increased further
+if {@Code xticks} is {@Code none}.  Similar remarks apply to y values.
+@PP
+The value of the @Code "objects" option is a sequence of zero or more of
+the following:
+@ID @Tab
+    vmargin { 0.5vx }
+    @Fmta { @Col A ! @Col { @Code "at {" @I expression @I expression
+@Code "}" } ! @Col @I object }
+{
+@Rowa A { @Code "@CTR" }
+@Rowa A { @Code "@NW"  }
+@Rowa A { @Code "@SW"  }
+@Rowa A { @Code "@SE"  }
+@Rowa A { @Code "@NE"  }
+@Rowa A { @Code "@N"   }
+@Rowa A { @Code "@W"   }
+@Rowa A { @Code "@S"   }
+@Rowa A { @Code "@E"   }
+}
+where @I object is an arbitrary Lout object.  Each of these nine symbols
+also has a @Code "margin" option whose value may be any non-negative
+distance, with default value {@Code "0.3 ft"}.
+@PP
+The options to the @Code "@Data" symbol, their default values, and
+their possible values are:
+@ID 0.85vx @Break @Tab
+   hmargin { 0.15c }
+   @Fmta { @Col @Code { "    "A } ! @Col @Code "{" ! @Col @I inherited !
+	   @Col @Code "}" ! @Col ! @Col ! @Col C }
+   @Fmtb { @Col A ! @Col ! @Col ! @Col ! @Col ! @Col ! @Col }
+{
+@Rowb
+    A { @Code "@Data" }
+@Rowa
+    A { points }
+    C { {@Code none}, {@Code plus}, {@Code cross}, {@Code square},
+{@Code filledsquare}, {@Code diamond}, {@Code filleddiamond},
+{@Code circle}, {@Code filledcircle},
+{@Code triangle}, {@Code filledtriangle} }
+@Rowa
+    A { pairs }
+    C { {@Code none}, {@Code solid}, {@Code dashed}, {@Code dotted},
+{@Code yhisto}, {@Code xhisto}, {@Code filledyhisto}, {@Code filledxhisto},
+{@Code surfaceyhisto}, {@Code surfacexhisto} }
+@Rowa
+    A { "colour/color" }
+    C { {@Code none}, or any colour name from Section {@NumberOf colour} }
+@Rowa
+    A { paint }
+    C { {@Code no} or {@Code yes} }
+@Rowa
+    A { dataformat }
+    C { {@Code xandy}, {@Code yonly}, {@Code xonly} }
+@Rowa
+    A { dashlength }
+    C { any @I distance }
+@Rowa
+    A { linewidth }
+    C { any @I distance }
+@Rowa
+    A { symbolsize }
+    C { any @I distance }
+@Rowb
+    A { @Code "{" @I sequence @Code "}" }
+    C { any @I sequence }
+}
+@I Inherited means that the default value is taken from the
+@Code "@Graph" option with the same name.
+@PP
+The right parameter of @Code "@Data" contains a @I sequence of zero
+or more {@I expressions}.  The {@Code xticks}, {@Code yticks}, and
+{@Code rticks} options also are sequences, which may contain @Code "@"
+and labels as well as expressions.  An @I expression is any of the
+following (operators are shown in decreasing precedence order, with
+the precedence, if relevant, at right):
+@ID @Tab
+    vmargin { 0.5vx }
+    @Fmta { @Col A ! @Col ! @Col B }
+{
+@Rowa
+    A { @I number }
+@Rowa
+    A { @Code x   (within @Code xloop only) }
+@Rowa
+    A { @Code y   (within @Code yloop only) }
+@Rowa
+    A { @Code z   (within @Code zloop only) }
+@Rowa
+    A { @Code pi }
+@Rowa
+    A { @Code e }
+@Rowa
+    A { @Code "{" @I expression @Code "}" }
+@Rowa
+    A { @Code "sqrt" @I expression }
+    B { 40 }
+@Rowa
+    A { @Code "abs" @I expression }
+    B { 40 }
+@Rowa
+    A { @Code "ceiling" @I expression }
+    B { 40 }
+@Rowa
+    A { @Code "floor" @I expression }
+    B { 40 }
+@Rowa
+    A { @Code "truncate" @I expression }
+    B { 40 }
+@Rowa
+    A { @Code "round" @I expression }
+    B { 40 }
+@Rowa
+    A { @Code "cos" @I expression }
+    B { 40 }
+@Rowa
+    A { @Code "sin" @I expression }
+    B { 40 }
+@Rowa
+    A { @I expression @Code "atan" @I expression }
+    B { 39 }
+@Rowa
+    A { @I expression @Code "exp" @I expression }
+    B { 38 }
+@Rowa
+    A { @I expression @Code "log" @I expression }
+    B { 37 }
+@Rowa
+    A { @I expression @Code "rand" @I expression }
+    B { 36 }
+@Rowa
+    A { @I expression @Eq { non * } @I expression }
+    B { 35 }
+@Rowa
+    A { @I expression @Code "/" @I expression }
+    B { 34 }
+@Rowa
+    A { @I expression @Code "idiv" @I expression }
+    B { 34 }
+@Rowa
+    A { @I expression @Code "mod" @I expression }
+    B { 34 }
+@Rowa
+    A { @I expression @Eq { non - } @I expression }
+    B { 33 }
+@Rowa
+    A { @Eq { non - } @I expression }
+    B { 33 }
+@Rowa
+    A { @I expression @Code "+" @I expression }
+    B { 32 }
+@Rowa
+    A { @Code "+" @I expression }
+    B { 32 }
+@Rowa
+   A { @Code "if cond {" @I boolean @Code "} then {" @I expression
+@Code "} else {" @I expression @Code "}" }
+}
+A @Eq { non - } immediately followed by a digit or decimal point is
+always taken to be a minus sign, never a subtraction.  The left
+parameter of @Code "exp" and @Code "log" is the base of the
+exponentiation and logarithm respectively; @Code "idiv" is integer
+division; and @Code "rand" returns a uniform random integer lying between
+its two parameters (inclusive).  Now a @I sequence is zero or more of
+the following:
+@ID @Tab
+    vmargin { 0.5vx }
+    @Fmta { @Col A }
+{
+@Rowa
+   A { 2c @Wide "@" (within {@Code xticks}, {@Code yticks}, and {@Code rticks} only) }
+@Rowa
+   A { 2c @Wide { ({@I label}) } (within {@Code xticks}, {@Code yticks}, and {@Code rticks} only) }
+@Rowa
+   A { @I expression }
+@Rowa
+   A { @Code "xloop from {" @I expression @Code "} to {" @I expression
+@Code "} by {" @I expression @Code "} do {" @I sequence @Code "}" }
+@Rowa
+   A { @Code "yloop from {" @I expression @Code "} to {" @I expression
+@Code "} by {" @I expression @Code "} do {" @I sequence @Code "}" }
+@Rowa
+   A { @Code "zloop from {" @I expression @Code "} to {" @I expression
+@Code "} by {" @I expression @Code "} do {" @I sequence @Code "}" }
+@Rowa
+   A { @Code "if cond {" @I boolean @Code "} then {" @I sequence
+@Code "} else {" @I sequence @Code "}" }
+}
+The @Code "by" part of the loop symbols is optional with default
+value 1; the @Code "else" part of @Code "if" is optional with
+default value equal to the empty sequence.  A @I boolean is any one of
+the following things, again shown in decreasing precedence order, with
+the precedence at right:
+@ID @Tab
+    vmargin { 0.5vx }
+    @Fmta { @Col A ! @Col ! @Col B }
+{
+@Rowa
+    A { @Code true }
+@Rowa
+    A { @Code false }
+@Rowa
+    A { @Code "{" @I boolean @Code "}" }
+@Rowa
+    A { @I expression @Code = @I expression }
+    B { 30 }
+@Rowa
+    A { @I expression @Code != @I expression }
+    B { 30 }
+@Rowa
+    A { @I expression @Code < @I expression }
+    B { 30 }
+@Rowa
+    A { @I expression @Code <= @I expression }
+    B { 30 }
+@Rowa
+    A { @I expression @Code > @I expression }
+    B { 30 }
+@Rowa
+    A { @I expression @Code >= @I expression }
+    B { 30 }
+@Rowa
+    A { @Code not @I boolean }
+    B { 25 }
+@Rowa
+    A { @I boolean @Code and @I boolean }
+    B { 24 }
+@Rowa
+    A { @I boolean @Code xor @I boolean }
+    B { 23 }
+@Rowa
+    A { @I boolean @Code or @I boolean }
+    B { 22 }
+@Rowa
+   A { @Code "if cond {" @I boolean @Code "} then {" @I boolean
+@Code "} else {" @I boolean @Code "}" }
+}
+@End @Section
diff --git a/doc/user/gra_tick b/doc/user/gra_tick
new file mode 100644
index 0000000..f6079cf
--- /dev/null
+++ b/doc/user/gra_tick
@@ -0,0 +1,205 @@
+@Section
+   @Title { Ticks and labels }
+   @Tag { ticks }
+@Begin
+@PP
+@I Ticks are the short lines that mark off intervals along the axes, and
+ticks.graph @Index { ticks in graphs }
+labels.graph @Index { labels in graphs }
+@I labels are the numbers appearing near the ticks (not to be confused
+with captions).  {@Code "@Graph"} produces ticks and labels automatically
+with some care, so it is probably best not to worry about them unless the
+result is not pleasing, in which case there are options for controlling them.
+@PP
+One simple way to control the production of x ticks is with the
+{@Code xmin}, {@Code xmax}, and {@Code xticksep} options to @Code
+"@Graph".  For example,
+@ID @OneRow @Code {
+"@Graph"
+"    xmin { 0 }"
+"    xmax { 5 }"
+"    xticksep { 0.5 }"
+}
+specifies that x values in the range 0 to 5 are to be expected, and that
+a tick and label is to appear every 0.5 units along the x axis.  One or
+both of @Code "xmin" and @Code "xmax" may be omitted, in which case
+suitable values will be inferred from the data as usual.
+@PP
+Alternatively, complete control over the appearance of x ticks and labels
+is provided by the @Code "xticks" option.  For example,
+xticks.graph @Index { @Code "xticks" option to @Code "@Graph" }
+@ID @OneRow @Code {
+"@Graph"
+"    xticks { 0@  5  10@  15  20@ }"
+}
+specifies that x ticks are to be drawn at 0, 5, 10, 15, and 20.  An
+@Code "@" following a number indicates that a label is to be printed as
+well, so the above example will produce labels at 0, 10, and 20.  For
+even finer control, @Code "@" may be replaced by a label enclosed
+in parentheses:
+@ID @OneRow @Code {
+"@Graph"
+"    xticks { 1 (Democrat)  2 (Republican)  3 (Other) }"
+}
+As this example shows, a label does not have to be a number; it can be
+any string of characters, including spaces and balanced parentheses;
+but it may not be an arbitrary Lout object.
+@PP
+The character @Code "^" in a label indicates that the
+remainder is to be treated as an exponent:
+@ID @OneRow @Code {
+"@Graph"
+"    xlog { 10 }"
+"    xticks { 1 (1)  10 (10)  100 (10^2)  1000 (10^3)  10000 (10^4)  100000 (10^5) }"
+"{"
+"    @Data points { plus }"
+"    { 1 2.1  10 3.4  100 4.9  1000 6.1  10000 7.2  100000 7.6 }"
+"}"
+}
+In fact, the labels inserted automatically when @Code xticks is omitted have
+exponents when the axis is logarithmic, so @Code xticks is hardly necessary
+in this example.  Anyway the result is
+@CD @Graph
+    height { 3 cm }
+    xlog { 10 }
+    xticks { 1 (1)  10 (10)  100 (10^2)  1000 (10^3)  10000 (10^4)  100000 (10^5) }
+{
+    @Data points { plus }
+    {
+        1 2.1  10 3.4  100 4.9  1000 6.1  10000 7.2  100000 7.6
+    }
+}
+Setting @Code "xticks" to empty produces no x ticks (this is not the
+same as omitting {@Code xticks}).
+@PP
+Similar options control ticks and labels on the y axis:  {@Code "ymin"},
+{@Code "ymax"}, {@Code "yticksep"}, and {@Code "yticks"}.  There are
+yticks.graph @Index { @Code "yticks" option to @Code "@Graph" }
+also @Code "xticklength" and @Code "yticklength" options which set
+the length of ticks:
+@ID @OneRow @Code {
+"@Graph"
+"    xticklength { 0.5 ft }"
+"    yticklength { 0.5 ft }"
+}
+shows the default values, half the current font size in both cases.
+@PP
+There is also an {@Code "rticks"} option which is similar to
+{@Code "yticks"} except that the ticks it controls appear on the
+right-hand side of the frame (this option is relevant only when
+the @Code style option is {@Code frame}).  Unlike @Code "xticks" and
+{@Code "yticks"}, {@Code "rticks"} has empty default value, which is
+why you don't usually see r ticks.  They are most useful when overstriking
+two graphs using @Code "@OverStrike" as explained earlier; one graph will
+have y ticks in the usual way, the other will have r ticks and empty
+y ticks:
+@CD {
+
+@Graph
+    style { frame }
+    width { 6c }
+    height { 8c }
+    xextra { 0 cm }
+    yextra { 0 cm }
+    rightcaption { -90d @Rotate { Precipitation mm } }
+    rightgap { 3.0f }
+    hidecaptions { no }
+    xmin { 0 }
+    xmax { 12 }
+    ymin { 0 }
+    ymax { 450 }
+    xticks { }
+    xticklength { 0 cm }
+    rticks { 0@ 50@ 100@ 150@ 200@ 250@ 300@ 350@ 400@ 450@ }
+    yticks {}
+{
+    @Data
+	pairs { filledyhisto }
+	colour { blue }
+	linewidth { 1 pt }
+    {
+	0 340
+	1 410
+	2 430
+	3 340
+	4 290
+	5 175
+	6 140
+	7 125
+	8 110
+	9 100
+	10 85
+	11 175
+	12 0
+    }
+}
+
+@OverStrike
+
+@Graph
+    style { frame }
+    width { 6c }
+    height { 8c }
+    xextra { 0 cm }
+    yextra { 0 cm }
+    leftcaption { 90d @Rotate { Temperature {@Degree}C } }
+    leftgap { 2.5f }
+    hidecaptions { no }
+    xmin { 0 }
+    xmax { 12 }
+    ymin { -30 }
+    ymax { 50 }
+    xticks {
+        0.5 (J)
+        1.5 (F)
+        2.5 (M)
+        3.5 (A)
+        4.5 (M)
+        5.5 (J)
+        6.5 (J)
+        7.5 (A)
+        8.5 (S)
+        9.5 (O)
+       10.5 (N)
+       11.5 (D)
+    }
+    xticklength { 0 cm }
+    yticks { -30@ -20@ -10@ 0@ 10@ 20@ 30@ 40@ }
+{
+    @Data
+	pairs { solid }
+	colour { red }
+	linewidth { 1 pt }
+    {
+        0.0 24
+        1.0 24
+        2.0 25
+        3.0 26
+        4.0 26
+        5.0 26
+        6.0 26
+        7.0 27
+        8.0 26
+        9.0 27
+       10.0 28
+       11.0 28
+       12.0 26
+    }
+}
+
+}
+Here the first graph has
+@ID @Code {
+"rticks { 0@ 50@ 100@ 150@ 200@ 250@ 300@ 350@ 400@ 450@ }"
+"yticks {}"
+}
+for its ticks.
+@PP
+Lout has only a hazy idea of how much space is occupied by ticks and
+labels.  Unless @Code "xticks" is empty, Lout allows 1.7 times the
+current font size below the graph for x ticks and labels, which is
+usually about right; but it does not allow any space for y and r ticks and
+labels since it has no idea how wide the labels will be.  The discussion
+of captions in Section {@NumberOf captions} explains how to use the
+@Code "leftgap" and @Code "rightgap" options to work around this deficiency.
+@End @Section
diff --git a/doc/user/letterbook b/doc/user/letterbook
new file mode 100644
index 0000000..269f073
--- /dev/null
+++ b/doc/user/letterbook
@@ -0,0 +1,356 @@
+###############################################################################
+#                                                                             #
+#   Lout setup file for books                                                 #
+#                                                                             #
+#   Jeffrey H. Kingston                                                       #
+#   5 February 1999                                                           #
+#                                                                             #
+###############################################################################
+
+
+###############################################################################
+#                                                                             #
+#  @SysInclude commands for standard packages.                                #
+#                                                                             #
+###############################################################################
+
+  @SysInclude { fontdefs	} # font definitions
+  @SysInclude { langdefs	} # language definitions
+  @SysInclude { bsf		} # BasicSetup package
+  @SysInclude { dsf		} # DocumentSetup package
+  @SysInclude { bookf		} # BookSetup extension
+
+
+###############################################################################
+#                                                                             #
+#  @Include command for reading personal definitions from current directory.  #
+#                                                                             #
+###############################################################################
+
+  @Include { mydefs }
+
+###############################################################################
+#                                                                             #
+#  The @BasicSetup @Use clause - basics, lists, paragraphs, displays.         #
+#                                                                             #
+#  To change the default value of any option, delete the # at the start of    #
+#  its line and change the value between braces.                              #
+#                                                                             #
+###############################################################################
+ 
+@Use { @BasicSetup
+  # @InitialFont	{ Times Base 12p	} # initial font
+  # @InitialBreak	{{adjust 1.2fx hyphen} @OrIfPlain {ragged 1fx nohyphen}}
+  # @InitialSpace	{ lout			} # initial space style
+  # @InitialLanguage	{ English		} # initial language
+  # @InitialColour	{ black			} # initial colour
+  # @OptimizePages	{ No			} # optimize page breaks?
+  # @HeadingFont	{ Bold			} # font for @Heading
+  # @ParaGap		{ 1.3vx @OrIfPlain 1f	} # gap between paragraphs
+  # @ParaIndent		{ 2.00f	@OrIfPlain 5s	} # first-line indent for @PP
+  # @DisplayGap		{ 1.00v	@OrIfPlain 1f	} # gap above, below displays
+  # @DisplayIndent	{ 2.00f	@OrIfPlain 5s	} # @IndentedDisplay indent
+  # @DefaultIndent	{ 0.5rt			} # @Display indent
+  # @DisplayNumStyle	{ (num)			} # style of display numbers
+  # @WideIndent		{ 4.00f	@OrIfPlain 10s	} # @WideTaggedList indent
+  # @VeryWideIndent	{ 8.00f	@OrIfPlain 20s	} # @VeryWideTaggedList indent
+  # @ListGap		{ 1.00v	@OrIfPlain 1f	} # gap between list items
+  # @ListIndent		{ 0s			} # indent of list items
+  # @ListRightIndent	{ 0s			} # right indent of list items
+  # @ListLabelWidth	{ 2.00f	@OrIfPlain 5s	} # width allowed for list tags
+  # @NumberSeparator	{ .			} # separates nums like 2.3.7
+}
+
+
+###############################################################################
+#                                                                             #
+#  The @DocumentSetup @Use clause - page layout plus figures, tables, etc.    #
+#                                                                             #
+#  To change the default value of any option, delete the # at the start of    #
+#  its line and change the value between braces.                              #
+#                                                                             #
+###############################################################################
+
+@Use { @DocumentSetup
+    @PageType		{ Letter @OrIfPlain Other} # page type (width, height)
+  # @PageWidth		{ 80s			} # page width if type Other
+  # @PageHeight		{ 66f			} # page height if type Other
+  # @PageOrientation	{ Portrait		} # Portrait, Landscape, etc.
+  # @PageBackground	{  			} # background of each page
+  # @TopMargin		{ 2.5c	@OrIfPlain 6f	} # top margin of all pages
+  # @FootMargin		{ 2.5c	@OrIfPlain 6f	} # bottom margin of all pages
+  # @OddLeftMargin	{ 2.5c	@OrIfPlain 10s	} # left margin of odd pages
+  # @OddRightMargin	{ 2.5c	@OrIfPlain 10s	} # right margin of odd pages
+  # @EvenLeftMargin	{ 2.5c	@OrIfPlain 10s	} # left margin of even pages
+  # @EvenRightMargin	{ 2.5c	@OrIfPlain 10s	} # right margin of even pages
+  # @PageBoxType	{ None			} # None Box CurveBox ShadowBox
+  # @PageBoxMargin	{ 1.00c			} # page box margin
+  # @PageBoxLineWidth	{			} # page box line thickness
+  # @PageBoxPaint	{ none			} # page box paint
+  # @PageBoxShadow	{ 0.60c			} # shadow margin if ShadowBox
+  # @ColumnNumber	{ 1			} # number of columns (1 to 10)
+  # @ColumnGap		{ 1.00c	@OrIfPlain 6s	} # column gap
+  # @FigureLocation	{ PageTop		} # default figure location
+  # @TableLocation	{ PageTop		} # default table location
+  # @FigureFormat	{ @CC @Body		} # default figure format
+  # @TableFormat	{ @CC @Body		} # default table format
+  # @FigureWord		{ figure		} # "Figure" word else anything
+  # @TableWord		{ table			} # "Table" word else anything
+  # @FigureNumbers	{ Arabic		} # method of numbering figures
+  # @TableNumbers	{ Arabic		} # method of numbering tables
+  # @FigureCaptionPos	{ Below 		} # Above or Below
+  # @TableCaptionPos	{ Below			} # Above or Below
+  # @CaptionFont        {                       } # figure, table caption font
+  # @CaptionBreak       {                       } # figure, table caption break
+  # @CaptionFormat      { @B { number @DotSep @OneCol }	} # figure, table caption format
+  # @MakeFigureContents { No                    } # list of figures at start
+  # @MakeTableContents  { No                    } # list of tables at start
+  # @MakeContents	{ No			} # make contents? Yes or No
+    @MakeContents	{ Yes			} # make contents? Yes or No
+  # @ContentsGap	{ 0.20v	@OrIfPlain 0f	} # extra gap above minor entry
+  # @ContentsGapAbove	{ 0.80v	@OrIfPlain 1f	} # extra gap above major entry
+  # @ContentsGapBelow	{ 0.00v	@OrIfPlain 0f	} # extra gap below major entry
+  # @ContentsPartGapAbove { 1.00v @OrIfPlain 1f	} # extra gap above `part' entry
+  # @ContentsPartGapBelow { 0.00v @OrIfPlain 0f	} # extra gap below `part' entry
+  # @ContentsFormat	{ number @DotSep title	} # contents entry format
+  # @ContentsLeader	{ ..			} # leader symbol in contents
+  # @ContentsLeaderGap	{ 4s	@OrIfPlain 2s	} # gap between leaders
+  # @ContentsRightWidth	{ 3f	@OrIfPlain 6s	} # page numbers column width
+  # @MakeReferences	{ Yes			} # make references? Yes or No
+  # @RefCiteStyle	{ [cite]		} # citation style
+  # @RefCiteLabels	{ @RefNum		} # citation items
+  # @RefNumbers		{ Arabic		} # reference numbers
+  # @RefListFormat	{ Labels		} # NoLabels, Labels, etc.
+  # @RefListLabels	{ [@RefNum]		} # ref list label format
+  # @RefListTitle	{ references		} # title of reference list
+  # @ChapRefListTitle	{ references		} # title of chapter ref list
+  # @RefListIndent	{ 0s			} # indent to left of labels
+  # @RefListRightIndent	{ 0s			} # indent to right of items
+  # @RefListGap		{ @ListGap		} # gap between ref list items
+  # @RefListFont	{        		} # font used in reference list
+  # @RefListBreak	{        		} # break style of ref list
+  # @RefListLabelWidth 	{ @ListLabelWidth	} # Labels column width
+  # @RefListSortKey	{ @Tag			} # sorting key
+  # @MakeIndex		{ No			} # make index? Yes or No
+    @MakeIndex		{ Yes			} # make index? Yes or No
+  # @IndexFont		{			} # index entries font
+  # @IndexBreak		{ {oragged 1.2fx} @OrIfPlain {oragged 1fx} } # and break
+  # @IndexColumnNumber	{ 2			} # index columns (1 to 10)
+  # @IndexColumnGap	{ 1.00c	@OrIfPlain 6s	} # index column gap
+  # @MakeIndexA		{ No 			} # make index A? Yes or No
+  # @IndexAFont		{			} # index A entries font
+  # @IndexABreak	{ {oragged 1.2fx} @OrIfPlain {oragged 1fx} } # and break
+  # @IndexAColumnNumber	{ 2			} # index A columns (1 to 10)
+  # @IndexAColumnGap	{ 1.00c	@OrIfPlain 6s	} # index A column gap
+  # @MakeIndexB		{ No 			} # make index B? Yes or No
+  # @IndexBFont		{			} # index B entries font
+  # @IndexBBreak	{ {oragged 1.2fx} @OrIfPlain {oragged 1fx} } # and break
+  # @IndexBColumnNumber	{ 2			} # index B columns (1 to 10)
+  # @IndexBColumnGap	{ 1.00c	@OrIfPlain 6s	} # index B column gap
+  # @TopGap		{ 0.75c	@OrIfPlain 2f	} # gap between figures
+  # @MidGap		{ 0.75c	@OrIfPlain 2f	} # gap above/below body text
+  # @FootNoteNumbers	{ Arabic		} # footnote numbers
+  # @FootNoteThrough	{ No			} # numbered through chapter?
+  # @FootNoteLocation	{ ColFoot		} # where the footnote appears
+  # @FootNoteFont	{ 0.80f			} # font for footnotes
+  # @FootNoteBreak	{ 1.2fx	@OrIfPlain 1fx	} # break for footnotes
+  # @FootLen		{ 2.00c	@OrIfPlain 10s	} # length of footnote line
+  # @FootAboveGap	{ @DisplayGap		} # gap above footnote line
+  # @FootGap		{ 0.20c	@OrIfPlain 1fx	} # gap between footnotes
+  # @MarginNoteFont	{ 0.80f			} # font of margin notes
+  # @MarginNoteBreak	{ ragged 1.10fx		} # break style of margin notes
+  # @MarginNoteHGap	{ 0.5c   		} # horizontal gap to notes
+  # @MarginNoteVGap	{ @DisplayGap		} # min vertical gap between
+  # @MarginNoteWidth	{ 1.50c  		} # width of margin notes
+  # @EndNoteNumbers	{ Arabic		} # endnote numbers
+  # @EndNoteFont	{ 0.80f			} # font of endnotes
+  # @EndNoteBreak	{ 1.2fx	@OrIfPlain 1fx	} # break for endnotes
+  # @EndNoteGap		{ 0.20c	@OrIfPlain 1f	} # gap between endnotes
+  # @TheoremWord	{ theorem		} # "Theorem" word, etc.
+  # @DefinitionWord	{ definition		} # "Definition" word, etc.
+  # @ClaimWord		{ claim			} # "Claim" word, etc.
+  # @PropositionWord	{ proposition		} # "Proposition" word, etc.
+  # @LemmaWord		{ lemma			} # "Lemma" word, etc.
+  # @CorollaryWord	{ corollary		} # "Corollary" word, etc.
+  # @ExampleWord	{ example		} # "Example" word, etc.
+  # @ProofWord		{ proof			} # "Proof" word, etc.
+  # @PageHeaders	{ Simple		} # None Simple Titles NoTitles
+    @PageHeaders	{ Titles		} # None Simple Titles NoTitles
+  # @PageNumbers	{ Arabic		} # page numbers
+  # @FirstPageNumber	{ 1			} # number of first page 
+  # @IntroPageNumbers	{ Roman			} # intro page numbers
+  # @IntroFirstPageNumber{ 1			} # number of first intro page 
+  # @StructPageNums	{ No			} # make structured page numbers
+
+  # @OddTop		{ @Centre{- @PageNum -}	} # Simple page headers
+  # @OddFoot		{ @Null			}
+  # @EvenTop		{ @Centre{- @PageNum -}	}
+  # @EvenFoot		{ @Null			}
+  # @StartOddTop	{ @Null			}
+  # @StartOddFoot	{ @Null			}
+  # @StartEvenTop	{ @Null			}
+  # @StartEvenFoot	{ @Null			}
+  # @IntroOddTop	{ @Null			}
+  # @IntroOddFoot	{ @Centre @PageNum	}
+  # @IntroEvenTop	{ @Null			}
+  # @IntroEvenFoot	{ @Centre @PageNum	}
+  # @IntroStartOddTop	{ @Null			}
+  # @IntroStartOddFoot	{ @Null			}
+  # @IntroStartEvenTop	{ @Null			}
+  # @IntroStartEvenFoot	{ @Null			}
+
+						  # Titles, NoTitles headers
+  # @RunningOddTop  { @I {@MinorNum @DotSep @MinorTitle} @Right @B @PageNum }
+  # @RunningOddFoot		{ @Null					}
+  # @RunningEvenTop { @B @PageNum @Right @I {@MajorNum @DotSep @MajorTitle} }
+  # @RunningEvenFoot		{ @Null					}
+  # @RunningStartOddTop 	{ @Null					}
+  # @RunningStartOddFoot	{ @Centre { Bold 0.8f } @Font @PageNum	}
+  # @RunningStartEvenTop	{ @Null					}
+  # @RunningStartEvenFoot	{ @Centre { Bold 0.8f } @Font @PageNum	}
+  # @RunningIntroOddTop		{ @Null					}
+  # @RunningIntroOddFoot	{ @Right @PageNum			}
+  # @RunningIntroEvenTop	{ @Null					}
+  # @RunningIntroEvenFoot	{ @PageNum				}
+  # @RunningIntroStartOddTop	{ @Null					}
+  # @RunningIntroStartOddFoot	{ @Null					}
+  # @RunningIntroStartEvenTop	{ @Null					}
+  # @RunningIntroStartEvenFoot	{ @Null					}
+}
+
+
+###############################################################################
+#                                                                             #
+#  The @BookSetup @Use clause - options specific to books.                    #
+#                                                                             #
+###############################################################################
+
+@Use { @BookSetup
+  # @TitlePageFont		{ Helvetica Base} # title page font (not size)
+  # @SeparateIntroNumbering	{ Yes		} # separate intro page numbers
+  # @PrefaceAfterContents  	{ No		} # Yes or No
+  # @ChapterStartPages		{ Any		} # Any, Odd, or Even
+  # @ReferencesBeforeAppendices	{ No		} # references before appendices
+  # @PrefaceWord		{ preface	} # word for "Preface"
+  # @ContentsWord		{ contents	} # word for "Contents"
+  # @FigureListWord		{ figurelist	} # word for "List of Figures"
+  # @TableListWord		{ tablelist	} # word for "List of Tables"
+  # @IntroductionWord		{ introduction	} # word for "Introduction"
+  # @ChapterWord		{ chapter	} # word for "Chapter"
+  # @AppendixWord		{ appendix	} # word for "Appendix"
+  # @IndexWord			{ index		} # word for "Index"
+  # @IndexAWord			{ index		} # word for "Index" (A)
+  # @IndexBWord			{ index		} # word for "Index" (B)
+  # @ChapterNumbers		{ Arabic	} # kind of chapter numbers
+  # @FirstChapterNumber		{ 1		} # first chapter number (Arabic)
+  # @SectionNumbers		{ Arabic	} # kind of section numbers
+  # @FirstSectionNumber		{ 1		} # first section number (Arabic)
+  # @SubSectionNumbers		{ Arabic	} # kind of subsection numbers
+  # @FirstSubSectionNumber	{ 1		} # first subsect number (Arabic)
+  # @SubSubSectionNumbers	{ Arabic	} # kind of sub-subs. numbers
+  # @FirstSubSubSectionNumber	{ 1		} # first sub-sub number (Arabic)
+  # @AppendixNumbers		{ UCAlpha	} # kind of appendix numbers
+  # @FirstAppendixNumber	{ 1		} # first appendix num (Arabic)
+  # @SubAppendixNumbers		{ Arabic	} # kind of subappendix numbers
+  # @FirstSubAppendixNumber	{ 1		} # first sub-app num (Arabic)
+  # @SubSubAppendixNumbers	{ Arabic	} # kind of sub-subapp. numbers
+  # @FirstSubSubAppendixNumber	{ 1		} # first sub-sub num (Arabic)
+  # @PartHeadingFont		{ Helvetica Base 2.50f	} # part head font
+  # @PartHeadingBreak		{ clines 1.2fx nohyphen	} # part head break
+  # @PartHeadingFormat          { @CD number @DP @CD title } # part head format
+  # @ChapterHeadingFont		{ Bold 2.00f		} # chapter head font
+  # @ChapterHeadingBreak	{ ragged 1.2fx nohyphen	} # chapter head break
+  # @ChapterHeadingFormat	{ number @DotSep title	} # format of chap. head
+  # @SectionHeadingFont		{ Bold			} # section head font
+  # @SectionHeadingBreak	{ ragged 1.2fx nohyphen	} # section head break
+  # @SectionHeadingFormat	{ number @DotSep title	} # section head fmt
+  # @SubSectionHeadingFont	{ Bold			} # subs. head font
+  # @SubSectionHeadingBreak	{ ragged 1.2fx nohyphen	} # subs. head break
+  # @SubSectionHeadingFormat	{ number @DotSep title	} # subs. head fmt
+  # @SubSubSectionHeadingFont	{ Slope			} # sub-subs. head font
+  # @SubSubSectionHeadingBreak	{ ragged 1.2fx nohyphen	} # sub-subs. head break
+  # @SubSubSectionHeadingFormat	{ number @DotSep title	} # sub-subs. head fmt
+  # @AppendixHeadingFont	{ Bold 2.00f		} # appendix head font
+  # @AppendixHeadingBreak	{ ragged 1.2fx nohyphen	} # appendix head break
+  # @AppendixHeadingFormat	{ number @DotSep title	} # appendix head fmt
+  # @SubAppendixHeadingFont	{ Bold			} # subapp. head font
+  # @SubAppendixHeadingBreak	{ ragged 1.2fx nohyphen	} # subapp. head break
+  # @SubAppendixHeadingFormat	{ number @DotSep title	} # subapp. head fmt
+  # @SubSubAppendixHeadingFont	{ Slope			} # sub-suba. head font
+  # @SubSubAppendixHeadingBreak	{ ragged 1.2fx nohyphen	} # sub-suba. head break
+  # @SubSubAppendixHeadingFormat{ number @DotSep title	} # sub-suba. head fmt
+  # @AbovePartGap		{ 4.00f			} # gap above part title
+  # @AboveChapterGap		{ 3.00f			} # above major titles
+  # @SectionGap			{ 2.0v	@OrIfPlain 3f	} # between sections
+  # @SubSectionGap		{ 1.5v	@OrIfPlain 2f	} # between subsects
+  # @SubSubSectionGap		{ 1.5v	@OrIfPlain 2f	} # between sub-subs.
+  # @SubAppendixGap		{ 2.0v	@OrIfPlain 3f	} # between subappendices
+  # @SubSubAppendixGap		{ 1.5v	@OrIfPlain 2f	} # between sub-subapps
+  # @IntroductionInContents	{ Yes		} # add introduction to contents
+  # @PartInContents		{ Yes		} # add parts to contents
+  # @ChapterInContents		{ Yes		} # add chapters to contents
+  # @SectionInContents		{ Yes		} # add sections to contents
+  # @SubSectionInContents	{ Yes		} # add subsections to contents
+  # @SubSubSectionInContents	{ No		} # add sub-subsects to contents
+  # @AppendixInContents		{ Yes		} # add appendices to contents
+  # @SubAppendixInContents	{ Yes		} # add subappendices to contents
+  # @SubSubAppendixInContents	{ No		} # add sub-subapps to contents
+  # @ReferencesInContents	{ Yes		} # add ref. section to contents
+  # @IndexInContents		{ Yes		} # add index to contents
+  # @IndexAInContents		{ Yes		} # add index A to contents
+  # @IndexBInContents		{ Yes		} # add index B to contents
+  # @PartContentsIndent         { 0.5rt		} # indent of part contents entry
+  # @ChapterNumInTheorems	{ Yes		} # theorem num has chapter num
+  # @SectionNumInTheorems	{ No		} # theorem num has section num
+  # @SubSectionNumInTheorems	{ No		} # theorem num has subsect num
+  # @SubSubSectionNumInTheorems	{ No		} # theorem num has sub-ss. num
+  # @AppendixNumInTheorems	{ Yes		} # theorem num has appendix num
+  # @SubAppendixNumInTheorems	{ No		} # theorem num has sub-app num
+  # @SubSubAppendixNumInTheorems{ No		} # theorem num has sub-sa. num
+  # @ChapterNumInDisplays	{ Yes		} # display num has chapter num
+  # @SectionNumInDisplays	{ Yes		} # display num has section num
+  # @SubSectionNumInDisplays	{ No		} # display num has subsect num
+  # @SubSubSectionNumInDisplays	{ No		} # display num has sub-ss. num
+  # @AppendixNumInDisplays	{ Yes		} # display num has appendix num
+  # @SubAppendixNumInDisplays	{ Yes		} # display num has sub-app num
+  # @SubSubAppendixNumInDisplays{ No		} # display num has sub-sa. num
+  # @ChapterNumInFigures	{ Yes		} # figure num has chapter num
+  # @SectionNumInFigures	{ No		} # figure num has section num
+  # @SubSectionNumInFigures	{ No		} # figure num has subsect num
+  # @SubSubSectionNumInFigures	{ No		} # figure num has sub-ss. num
+  # @AppendixNumInFigures	{ Yes		} # figure num has appendix num
+  # @SubAppendixNumInFigures	{ No		} # figure num has sub-app num
+  # @SubSubAppendixNumInFigures	{ No		} # figure num has sub-sa. num
+  # @ChapterNumInTables		{ Yes		} # table num has chapter num
+  # @SectionNumInTables		{ No		} # table num has section num
+  # @SubSectionNumInTables	{ No		} # table num has subsect num
+  # @SubSubSectionNumInTables	{ No		} # table num has sub-ss. num
+  # @AppendixNumInTables	{ Yes		} # table num has appendix num
+  # @SubAppendixNumInTables	{ No		} # table num has sub-app num
+  # @SubSubAppendixNumInTables	{ No		} # table num has sub-sa. num
+  # @SectionNumInRunners 	{ Yes		} # runners have section num
+  # @SubSectionNumInRunners 	{ No		} # runners have subsect num
+  # @SubSubSectionNumInRunners 	{ No		} # runners have sub-ss. num
+  # @SubAppendixNumInRunners 	{ Yes		} # runners have sub-app num
+  # @SubSubAppendixNumInRunners { No		} # runners have sub-sa. num
+  # @PrefacePrefix		{		} # for structured page nums
+  # @ContentsPrefix		{		} # for structured page nums
+  # @FigureContentsPrefix	{		} # for structured page nums
+  # @TableContentsPrefix	{		} # for structured page nums
+  # @IntroductionPrefix		{		} # for structured page nums
+  # @ChapterPrefix		{		} # for structured page nums
+  # @AppendixPrefix		{		} # for structured page nums
+  # @ReferencesPrefix		{		} # for structured page nums
+  # @IndexPrefix		{		} # for structured page nums
+  # @IndexAPrefix		{		} # for structured page nums
+  # @IndexBPrefix		{		} # for structured page nums
+}
+
+
+###############################################################################
+#                                                                             #
+#  @Database (and @SysDatabase) clauses go here.                              #
+#                                                                             #
+###############################################################################
+
+@SysDatabase @RefStyle { refstyle }		  # reference printing styles
diff --git a/doc/user/mydefs b/doc/user/mydefs
new file mode 100644
index 0000000..2ef9639
--- /dev/null
+++ b/doc/user/mydefs
@@ -0,0 +1,203 @@
+
+   ###################################################
+   #                                                 #
+   #  Lout keywords and @Code symbol.                #
+   #                                                 #
+   ###################################################
+
+   def @Code right x
+   { { Helvetica Base -1p } @Font lines @Break x }
+
+   def @@BackEnd           { @Code "@BackEnd"           }
+   def @@Begin             { @Code "@Begin"             }
+   def @@Break             { @Code "@Break"             }
+   def @@Case              { @Code "@Case"              }
+   def @@Database          { @Code "@Database"          }
+   def @@End               { @Code "@End"               }
+   def @@Font              { @Code "@Font"              }
+   def @@Char              { @Code "@Char"              }
+   def @@Galley            { @Code "@Galley"            }
+   def @@Graphic           { @Code "@Graphic"           }
+   def @@HAdjust           { @Code "@HAdjust"           }
+   def @@HContract         { @Code "@HContract"         }
+   def @@HCover            { @Code "@HCover"            }
+   def @@HExpand           { @Code "@HExpand"           }
+   def @@HScale            { @Code "@HScale"            }
+   def @@High              { @Code "@High"              }
+   def @@HShift            { @Code "@HShift"            }
+   def @@Include           { @Code "@Include"           }
+   def @@Insert            { @Code "@Insert "           }
+   def @@IncludeGraphic    { @Code "@IncludeGraphic"    }
+   def @@Key               { @Code "@Key"               }
+   def @@LClos             { @Code "@LClos"             }
+   def @@LEnv              { @Code "@LEnv"              }
+   def @@LInput            { @Code "@LInput"            }
+   def @@LVis              { @Code "@LVis"              }
+   def @@Moment            { @Code "@Moment"            }
+   def @@Next              { @Code "@Next"              }
+   def @@Null              { @Code "@Null"              }
+   def @@OneCol            { @Code "@OneCol"            }
+   def @@OneRow            { @Code "@OneRow"            }
+   def @@Open              { @Code "@Open"              }
+   def @@PAdjust           { @Code "@PAdjust"           }
+   def @@PrependGraphic    { @Code "@PrependGraphic"    }
+   def @@Rotate            { @Code "@Rotate"            }
+   def @@Scale             { @Code "@Scale"             }
+   def @@SetColor          { @Code "@SetColor"          }
+   def @@SetColour         { @Code "@SetColour"         }
+   def @@Language          { @Code "@Language"          }
+   def @@CurrLang          { @Code "@CurrLang"          }
+   def @@Space             { @Code "@Space"             }
+   def @@SysDatabase       { @Code "@SysDatabase"       }
+   def @@SysInclude        { @Code "@SysInclude"        }
+   def @@SysIncludeGraphic { @Code "@SysIncludeGraphic" }
+   def @@SysPrependGraphic { @Code "@SysPrependGraphic" }
+   def @@Tag               { @Code "@Tag"               }
+   def @@Tagged            { @Code "@Tagged"            }
+   def @@Use               { @Code "@Use"               }
+   def @@VAdjust           { @Code "@VAdjust"           }
+   def @@VContract         { @Code "@VContract"         }
+   def @@VCover            { @Code "@VCover"            }
+   def @@VExpand           { @Code "@VExpand"           }
+   def @@VScale            { @Code "@VScale"            }
+   def @@VShift            { @Code "@VShift"            }
+   def @@Wide              { @Code "@Wide"              }
+   def @@Yield             { @Code "@Yield"             }
+
+
+   ###################################################
+   #                                                 #
+   #  Miscellaneous symbols used in the guide.       #
+   #                                                 #
+   ###################################################
+
+   def @TeX
+   { @OneCol { T &0.4fo {-0.2f @VShift E} &0.45fo X }
+   }
+
+   def @LaTeX
+   { @OneCol { L &0.3fo { +0.1f @VShift 0.8f @Font A } &0.4fo @TeX }
+   }
+
+   import @BasicSetup
+   def @Batlow { Batlow Food Distributors Pty. Ltd. }
+
+   import @BasicSetup
+   def @GreyBox right x { @Box paint { lightgrey } x }
+
+   import @BasicSetup
+   def @HeadingBox left x right y
+   {
+       @Box { @CentredDisplay @Heading x y }
+   }
+
+   def @FilledBox
+   {
+     @BackEnd @Case {
+       PostScript @Yield {
+         { "0 0 moveto xsize 0 lineto xsize ysize lineto 0 ysize lineto"
+           "closepath fill"
+         } @Graphic { 0.6f @High ^/ 0.4f @High 4f @Wide }
+       }
+       PDF @Yield {
+         { "0 0 m __xsize 0 l __xsize __ysize l 0 __ysize l h f"
+         } @Graphic { 0.6f @High ^/ 0.4f @High 4f @Wide }
+       }
+     }
+   }
+
+   import @Eq
+   def epi { p sub i ` log sub 2 ` p sub i }
+ 
+   import @Eq
+   def ep right x { p sub x ` log sub 2 ` p sub x }
+ 
+   def @Dbl left x right y
+   { 1.95i @Wide
+     { 1.25i @Wide { |1rt @Code x } |0.2i @Eq {non y} }
+   }
+ 
+   import @Eq
+   def @ExA { 1 over sqrt { 1 - 4 x sup 2 } }
+
+   def @@Diag { @Code "@Diag" }
+
+   extend @DiagSetup @Diag
+   macro @MyNode {
+    @Node
+	outline {
+	    LR:: { xsize 0 }
+	    LR:< 0d
+	    UL:: { 0 ysize }
+	    UL:< 270d
+	    0 0 LR UL 0 0
+	}
+   }
+
+   extend @DiagSetup @Diag
+   macro @MyLink {
+    @Link
+	path {
+	    FROM:: from
+	    TO:: to
+	    FROM TO
+	}
+   }
+
+   def @ShowHMark
+      named linewidth  { 0.015 cm }
+      named linestyle  { dashed   }
+      named dashlength { 0.15 cm  }
+      named paint      { light    }
+      right x
+   {
+      @Fig
+      {
+         @Figure
+                 shape {
+                   @BackEnd @Case {
+                     PostScript @Yield {
+                         -0.3 cm ymark
+                         {xsize ymark} ++ {0.3 cm 0}
+                     }
+                     PDF @Yield { ""    #       VT: PDF currently has no output
+                     }
+                   }
+                 }
+                 linewidth { linewidth }
+                 linestyle { linestyle }
+                 dashlength { dashlength }
+         x
+      }
+   }
+ 
+   def @ZeroWidth right x { @OneCol { |0io x |0io } }
+ 
+   def @SomeText
+   {
+Johnson suddenly uttered, in a strong determined tone, an apophegm, at
+which many will start:  `Patriotism is the last refuge of a scoundrel.'
+   }
+ 
+   import @DiagSetup
+   def @OpenCircle { @Diag { @Circle margin { 0.2f } } }
+ 
+   import @DiagSetup
+   def @ClosedCircle { @Diag { @Circle paint { black } margin { 0.2f } } }
+ 
+   import @TblSetup @BasicSetup
+   def @AmberLight
+   {
+       @OneRow @Tbl
+           aformat { @Cell A }
+           marginhorizontal { 0i }
+           marginvertical { 0i }
+           strut { no }
+           rule { no }
+           paint { no }
+        {
+            @Rowa A { @OpenCircle }
+            @MarkRowa A { @ClosedCircle }
+            @Rowa A { @OpenCircle }
+        }
+   }
diff --git a/doc/user/pascal b/doc/user/pascal
new file mode 100644
index 0000000..41376df
--- /dev/null
+++ b/doc/user/pascal
@@ -0,0 +1,162 @@
+@Chapter
+    @Title { Pascal and Modula-2 Programs }
+@Begin
+@LP
+There is a @Code "@Pas" symbol for printing Pascal programs
+pascal @Index { Pascal programs }
+pas. @Index @Code "@Pas"
+@Cite { $jensen1975pascal }.  No attempt is made to follow any
+particular printing standard; the design simply reflects this author's
+taste.  To use {@Code "@Pas"}, place @Code "@SysInclude { pas }" at the
+start of your document in the usual way.  A Pascal program or program
+fragment is entered like this:
+@ID @Code {
+"@ID @Pas {"
+"procedure PriDelete(x: PriEntry; var Q: PriorityQueue);"
+"    var i: integer;"
+"begin"
+"    with Q^ do begin"
+"        size := size - 1;"
+"        if x^.back <= size then"
+"        begin"
+"            i := x^.back;"
+"            A[i] := A[size + 1];"
+"            A[i]^.back := i;"
+"            PriAddRoot(i, Q);"
+"            PriAddLeaf(i, Q)"
+"        end"
+"    end"
+"end;"
+"}"
+}
+This produces
+@ID @Pas {
+procedure PriDelete(x: PriEntry; var Q: PriorityQueue);
+    var i: integer;
+begin
+    with Q^ do begin
+	size := size - 1;
+	if x^.back <= size then
+	begin
+	    i := x^.back;
+	    A[i] := A[size + 1];
+	    A[i]^.back := i;
+	    PriAddRoot(i, Q);
+	    PriAddLeaf(i, Q)
+	end
+    end
+end;
+}
+Blank lines, line breaks, indents and spaces in the input are respected,
+with a tab being considered equal to eight spaces.  @Code "@Pas" can also
+be used within a paragraph to produce a fragment like
+@OneCol @Pas { A[i..j] }.  Use @Code "@OneCol @Pas { ... }" to prevent the
+result from breaking over two lines.
+@PP
+@Code "@Pas" does not attempt to rearrange the program in any way.  Each
+item is simply printed according to the following plan:
+@ID {
+7c @Wide {
+      @Code and 	|2.5ct @Pas { and }
+//1vx @Code array 	|2.5ct @Pas { array }
+//1vx @Code begin 	|2.5ct @Pas { begin }
+//1vx @Code case 	|2.5ct @Pas { case }
+//1vx @Code const 	|2.5ct @Pas { const }
+//1vx @Code div 	|2.5ct @Pas { div }
+//1vx @Code do 		|2.5ct @Pas { do }
+//1vx @Code downto 	|2.5ct @Pas { downto }
+//1vx @Code else 	|2.5ct @Pas { else }
+//1vx @Code end 	|2.5ct @Pas { end }
+//1vx @Code file 	|2.5ct @Pas { file }
+//1vx @Code for 	|2.5ct @Pas { for }
+//1vx @Code forward	|2.5ct @Pas { forward }
+//1vx @Code function 	|2.5ct @Pas { function }
+//1vx @Code goto 	|2.5ct @Pas { goto }
+//1vx @Code if 		|2.5ct @Pas { if }
+//1vx @Code in 		|2.5ct @Pas { in }
+//1vx @Code label 	|2.5ct @Pas { label }
+//1vx @Code mod 	|2.5ct @Pas { mod }
+//1vx @Code nil 	|2.5ct @Pas { nil }
+//1vx @Code not 	|2.5ct @Pas { not }
+//1vx @Code of 		|2.5ct @Pas { of }
+//1vx @Code or 		|2.5ct @Pas { or }
+//1vx @Code otherwise 	|2.5ct @Pas { otherwise }
+//1vx @Code packed 	|2.5ct @Pas { packed }
+//1vx @Code procedure 	|2.5ct @Pas { procedure }
+//1vx @Code program 	|2.5ct @Pas { program }
+//1vx @Code record 	|2.5ct @Pas { record }
+//1vx @Code repeat 	|2.5ct @Pas { repeat }
+//1vx @Code set 	|2.5ct @Pas { set }
+//1vx @Code then 	|2.5ct @Pas { then }
+//1vx @Code to 		|2.5ct @Pas { to }
+//1vx @Code type 	|2.5ct @Pas { type }
+//1vx @Code until 	|2.5ct @Pas { until }
+//1vx @Code var 	|2.5ct @Pas { var }
+//1vx @Code while 	|2.5ct @Pas { while }
+//1vx @Code with 	|2.5ct @Pas { with }
+} | 7c @Wide {
+      @Code "0"		|2.5ct @Pas { 0 }
+//1vx @Code "1"		|2.5ct @Pas { 1 }
+//1vx @Code "2"		|2.5ct @Pas { 2 }
+//1vx @Code "3"		|2.5ct @Pas { 3 }
+//1vx @Code "4"		|2.5ct @Pas { 4 }
+//1vx @Code "5"		|2.5ct @Pas { 5 }
+//1vx @Code "6"		|2.5ct @Pas { 6 }
+//1vx @Code "7"		|2.5ct @Pas { 7 }
+//1vx @Code "8"		|2.5ct @Pas { 8 }
+//1vx @Code "9"		|2.5ct @Pas { 9 }
+//1vx @Code "."		|2.5ct @Pas { . }
+//1vx @Code ","		|2.5ct @Pas { , }
+//1vx @Code ":"		|2.5ct @Pas { : }
+//1vx @Code ";"		|2.5ct @Pas { ; }
+//1vx @Code "'"		|2.5ct @Pas { ' }
+//1vx @Code "`"		|2.5ct @Pas { ` }
+//1vx @Code "+"		|2.5ct @Pas { + }
+//1vx @Code "-"		|2.5ct @Pas { - }
+//1vx @Code "*"		|2.5ct @Pas { * }
+//1vx @Code "/"		|2.5ct @Pas { / }
+//1vx @Code "("		|2.5ct @Pas { ( }
+//1vx @Code ")"		|2.5ct @Pas { ) }
+//1vx @Code "["		|2.5ct @Pas { [ }
+//1vx @Code "]"		|2.5ct @Pas { ] }
+//1vx @Code "^"		|2.5ct @Pas { ^ }
+//1vx @Code ".."	|2.5ct @Pas { .. }
+//1vx @Code "="		|2.5ct @Pas { = }
+//1vx @Code "<"		|2.5ct @Pas { < }
+//1vx @Code ">"		|2.5ct @Pas { > }
+//1vx @Code "<>"	|2.5ct @Pas { <> }
+//1vx @Code "<="	|2.5ct @Pas { <= }
+//1vx @Code ">="	|2.5ct @Pas { >= }
+//1vx @Code ":="	|2.5ct @Pas { := }
+}
+}
+Anything not mentioned here will appear in italic font.
+@PP
+Unlike the @Code "@CP" symbol from the previous chapter, the @Code "@Pas"
+symbol is a quick-and-dirty production which does not offer you any options,
+or indeed attempt to solve every problem of Pascal formatting.  In
+particular, Pascal strings need attention before formatting by
+{@Code "@Pas"}.  Their interiors are best enclosed in double quotes to
+prevent the above transformations from occurring inside them.  Any
+@Code "\\" or @Code "\"" characters inside strings will need to be
+replaced by @Code "\\\\" and @Code "\\\"" respectively, and the opening
+quote should be replaced by {@Code "`"}.
+@PP
+Similar remarks apply to Pascal comments; don't forget that @Code "{"
+and @Code "}" must be enclosed in double quotes.  Alternatively, a
+@Code "@Com" symbol can be placed in front of a comment enclosed
+in braces.  It will add literal braces:
+@ID @Code {
+"@Com { A Pascal comment }"
+}
+has result
+@ID @Pas {
+@Com { A Pascal comment }
+}
+It may still be necessary to enclose the interior in double quotes.
+@PP
+There is a @Code "@Modula" symbol which allows you to format Modula-2
+programs in the same way as @Code "@Pas" does for Pascal.  You get it
+via {@Code "@SysInclude { modula }"}, and once again it is a quick-and-dirty
+production.
+@End @Chapter
diff --git a/doc/user/preface b/doc/user/preface
new file mode 100644
index 0000000..eada554
--- /dev/null
+++ b/doc/user/preface
@@ -0,0 +1,66 @@
+@Preface @Begin
+@LP
+This User's Guide brings together in one document everything needed
+for the day-to-day use of Version 3 of the Lout document formatting
+system.
+@IndexBlanks
+@PP
+There are three other documents describing Lout:  the Expert's Guide
+@Cite { $kingston1995lout.expert }, which you need if you want to add
+new features to Lout; a journal paper on the design and implementation
+of Lout @Cite { $kingston1993lout.design }; and a set of overhead
+transparencies @Cite { $kingston1994lout.overheads } that cover much
+the same ground as this Guide.  These documents are all distributed
+with the software.
+@PP
+Lout is distributed free of charge under the GNU Public License.  The
+gnu. @Index { GNU Public License }
+primary source is directory
+@ID @Code "ftp://ftp.cs.su.oz.au/jeff/lout"
+in which may be found a gzipped tar file containing the main distribution
+(currently {@Code "lout-3.17.tar.gz"}), and various other things including
+a PostScript version of this guide.  The distribution contains source code,
+libraries, documentation, license, and installation instructions.
+@PP
+A mailing list has been set up for discussion of all topics related to
+Lout.  To subscribe, send email to @Code "lout-request@ptc.spbu.ru"
+containing the word @Code "subscribe" in the Subject line.  To post an
+item, send email to {@Code "lout@ptc.spbu.ru"}; it will be forwarded to
+all subscribers via email.  To unsubscribe, send email to
+@Code "lout-request@ptc.spbu.ru" containing the word @Code "unsubscribe"
+in the Subject line.
+@PP
+Lout began in 1984 as a research project into the design of a high-level
+language for document formatting.  At that time my name for the subject
+was `document layout,' and this terminology survives in the name
+`Lout'.  The initial design
+was strongly influenced by Brian W. Kernighan and Lorinda L. Cherry's eqn
+kernighan @Index { Kernighan, Brian W. }
+cherry.l @Index { Cherry, Lorinda L.}
+eqn. @Index { @Code eqn equation formatter }
+equation formatter @Cite { $kernighan1975eqn }, and also by Brian K. Reid's
+Scribe system @Cite { $reid1980scribe }.  That
+scribe.influence @SubIndex { influence on Lout }
+reid.b @Index { Reid, Brian K. }
+research phase ended in October 1991 with the first public release of Lout.
+@PP
+Since then the system has been steadily improved and extended.  Optimal
+paragraph breaking and automatic hyphenation were copied from Donald
+knuth @Index { Knuth, D. E. }
+tex. @Index { @TeX }
+E. Knuth's @TeX system @Cite { $knuth1984tex }, and the optimal paragraph
+breaking algorithm was applied to the problem of producing optimal page
+breaks.  The first implementations of horizontal galleys and optimal
+page breaking were by my student Gabor Inokai.  Vincent Tan contributed
+the PDF back end.  The strongest influence during this period has come from
+Lout's users; indeed the number of people who have offered comments and
+suggestions is so great that it is quite out of my power to acknowledge them
+individually.  I hope that seeing their ideas adopted will be thanks enough.
+@DP
+@RLD lines @Break {
+Jeffrey H. Kingston
+Basser Department of Computer Science
+The University of Sydney 2006, Australia
+@Code "jeff@cs.usyd.edu.au"
+}
+@End @Preface
diff --git a/doc/user/ref b/doc/user/ref
new file mode 100644
index 0000000..6ea5782
--- /dev/null
+++ b/doc/user/ref
@@ -0,0 +1,31 @@
+@Chapter
+    @Title { References }
+    @Tag { biblio }
+@Begin
+@LP
+The simple way to make a list of references is to put them in a numbered
+references. @Index { references }
+or tagged list at the end of your document.  If you use references only
+rarely, that is probably the best way, but if you use them frequently this
+chapter will save you hours of work in the long run.
+@PP
+Some good general principles and many examples have been given by van Leunen
+van.leunen. @Index { van Leunen, Mary-Claire }
+@Cite { $vanleunen1992handbook }.  Broadly speaking Lout follows her
+recommendations, with some unification and scaling back as is inevitable
+with software.  Scribe @Cite { $reid1980scribe }
+latex. @Index @LaTeX
+scribe. @RawIndex Scribe
+scribe.reference @SubIndex { reference formatting }
+and @LaTeX @Cite { $lamport1986latex } followed the first edition of the
+same source, so translation from Scribe and @LaTeX references is
+fairly straightforward.
+@BeginSections
+@Include { ref_sett }
+@Include { ref_cite }
+@Include { ref_labe }
+@Include { ref_entr }
+@Include { ref_chan }
+@Include { ref_crea }
+@EndSections
+@End @Chapter
diff --git a/doc/user/ref_chan b/doc/user/ref_chan
new file mode 100644
index 0000000..f7114fb
--- /dev/null
+++ b/doc/user/ref_chan
@@ -0,0 +1,200 @@
+@Section
+    @Title { Changing the appearance of citations and the reference list }
+    @Tag { changeref }
+@Begin
+@PP
+By default, citations appear like this @Cite { $kingston1995lout.expert },
+and the reference list appears like the one at the end of this
+document, with the entries numbered, and sorted by their @Code "@Tag"
+options.  This section explains how to change all this, by setting
+options in the setup file.
+@PP
+For a general introduction to setup files and their options, see
+Section {@NumberOf setup}.  Here we just describe the setup
+file options that relate to references.  Here they are, with their
+default values:
+@ID @OneRow @Code {
+"@MakeReferences { Yes }"
+"@RefCiteStyle { [cite] }"
+"@RefCiteLabels { @RefNum }"
+"@RefNumbers { Arabic }"
+"@RefListFormat { Labels }"
+"@RefListLabels { [@RefNum] }"
+"@RefListTitle { references }"
+"@ChapRefListTitle { references }"
+"@RefListIndent { 0c }"
+"@RefListRightIndent { 0c }"
+"@RefListGap { 1.00v }"
+"@RefListFont { }"
+"@RefListBreak { }"
+"@RefListLabelWidth { 2.00f }"
+"@RefListSortKey { @Tag }"
+}
+makereferences.sym @Index { @Code "@MakeReferences" }
+Setting @Code "@MakeReferences" to @Code "No" will cause Lout to ignore
+all citation symbols and omit all reference lists.
+@PP
+@Code "@RefCiteStyle" and @Code "@RefCiteLabels" combine to
+refcitestyle.sym @Index { @Code "@RefCiteStyle" }
+determine the appearance of citations.  The result of each @Code "@Cite"
+symbol is the value of @Code "@RefCiteStyle" with the @Code "cite"
+symbol replaced by the object following the @Code "@Cite" symbol.  For
+example, the default value shown above encloses each citation in
+brackets.  The @Code "cite" symbol must appear exactly once within
+{@Code "@RefCiteStyle"}.
+@PP
+@Code "@RefCiteLabels" determines the appearance of each label within
+refcitelabels.sym @Index { @Code "@RefCiteLabels" }
+the citation.  Within it, the @Code "@RefNum" symbol will produce the
+number of the reference, and you may also use any of the options of the
+@Code "@Reference" symbol listed at the beginning of Section
+{@NumberOf entries}:
+@ID @OneRow @Tab
+    @Fmta { @Col @Code A ! @Col B }
+{
+@Rowa
+    A { "@RefCiteLabels { @RefNum }" }
+    B { [3] }
+@Rowa
+    A { "@RefCiteLabels { @Label }" }
+    B { [Kin93] }
+@Rowa
+    A { "@RefCiteLabels { @Author, @Year }" }
+    B { [Jeffrey H. Kingston, 1993] }
+}
+The value of @Code "@RefCiteLabels" may be any object.  The @Code "@Label"
+symbol will produce the @Code "label" option of @Code "$" or @Code "@Ref"
+if there is one, rather than the @Code "@Label" option of the reference;
+this @Code "label" option is explained in Section {@NumberOf labelled}.
+@PP
+@Code "@RefNumbers" determines the kind of numbering produced by the
+refnumbers.sym @Index { @Code "@RefNumbers" }
+@Code "@RefNum" symbol used within @Code "@RefCiteLabels" above and
+@Code "@RefListLabels" below.  Its value may be {@Code Arabic},
+{@Code Roman}, {@Code UCRoman}, {@Code Alpha}, or {@Code UCAlpha}, as
+usual for numbering in Lout.  If you don't use {@Code "@RefNum"},
+@Code "@RefNumbers" has no effect.
+@PP
+The remaining eleven setup file options are all concerned with the
+appearance of the reference list.  The first, {@Code "@RefListFormat"},
+reflistformat.sym @Index { @Code "@RefListFormat" }
+determines the overall format of the list.  Here is what its four
+@NoCite { $strunk1979style } possible values do:
+@ID @Tab
+    @Fmta { @Col @Code A ! @Col @OneCol B }
+    vmargin { 0.3v }
+{
+@Rowa
+    A { "@RefListFormat { NoLabels }" }
+    B {  @RefPrint strunk1979style }
+@Rowa
+@Rowa
+    A { "@RefListFormat { Labels }" }
+    B {  2f @Wide {{@NumberOf strunk1979style}.} | @RefPrint strunk1979style }
+@Rowa
+@Rowa
+    A { "@RefListFormat { DropLabels }" }
+    B {  {@NumberOf strunk1979style}. //1vx
+	 2f @Wide {} | @RefPrint strunk1979style
+      }
+@Rowa
+@Rowa
+    A { "@RefListFormat { InLabels }" }
+    B {  {@NumberOf strunk1979style}. &2s @RefPrint strunk1979style }
+}
+@Code "@RefListFormat" is not concerned with the appearance of the
+labels and references, only with where they appear.
+@PP
+@Code "@RefListLabels" determines the appearance of the labels in the
+reflistlabels.sym @Index { @Code "@RefListLabels" }
+reference list (and so has no effect if @Code "@RefListFormat" is
+{@Code "NoLabels"}).  It is a combination of @Code "@RefCiteStyle"
+and {@Code "@RefCiteLabels"}; you can use @Code "@RefNum" and all the
+options of @Code "@Reference" within it.  The default value,
+@ID @Code "@RefListLabels { @RefNum. }"
+produces a numbered reference list in the style of
+{@Code "@NumberedList"}.  Another useful value is
+@ID @Code "@RefListLabels { [@Label] }"
+which produces the @Code "@Label" option of the reference, or the
+@Code "label" option of the citation if there is one, enclosed in
+brackets.  If you do switch to non-numeric labels you will need to
+either use @Code "DropLabels" or else increase the
+@Code "@RefListLabelWidth" option described below.
+@PP
+@Code "@RefListTitle" determines the heading placed just before the
+reflisttitle.sym @Index { @Code "@RefListTitle" }
+reference list at the end of the document:
+@ID @Code "@RefListTitle { Further Reading }"
+Two special values, @Code "references" and {@Code "bibliography"},
+produce References and Bibliography in English and their equivalents
+in other languages.  @Code "@ChapRefListTitle" is the same as
+chapreflisttitle.sym @Index { @Code "@ChapRefListTitle" }
+{@Code "@RefListTitle"}, but applied to the reference list at the end
+of each chapter of a book when @Code "@ChapCite" is used.
+@PP
+{@Code "@RefListIndent"}, {@Code "@RefListRightIndent"}, and
+reflistindent.sym @Index { @Code "@RefListIndent" }
+reflistrightindent.sym @Index { @Code "@RefListRightIndent" }
+reflistgap.sym @Index { @Code "@RefListGap" }
+{@Code "@RefListGap"} determine the left indent, right indent, and gap
+between reference list items, analogously to the {@Code "indent"},
+{@Code "rightindent"}, and {@Code "gap"} options of the @Code "@List"
+symbol (Section {@NumberOf lists}).  @Code "@RefListFont" and
+@Code "@RefListBreak" determine the font and
+reflistfont.sym @Index { @Code "@RefListFont" }
+reflistbreak.sym @Index { @Code "@RefListBreak" }
+paragraph breaking style of the reference list.  For example,
+@ID @OneRow @Code {
+"@RefListFont { -2p }"
+"@RefListBreak { 1.2fx outdent }"
+}
+switches to a smaller size with outdented paragraphs (these work well
+with {@Code NoLabels}).  The empty default values produce the same
+font and break style as in the document as a whole.
+@PP
+@Code "@RefListLabelWidth" determines the distance from the left
+reflistlabelwidth.sym @Index { @Code "@RefListLabelWidth" }
+edge of the labels to the left edge of the references, when
+@Code "@RefListFormat" is @Code Labels or {@Code DropLabels} (it
+has no effect when @Code "@RefListFormat" is @Code NoLabels or
+{@Code "InLabels"}).  This is different to {@Code "@RefListIndent"},
+which determines the distance from the edge of the column to the
+left edge of the item.
+@PP
+Particular care is needed when @Code "@RefListFormat"
+is @Code Labels and the labels are non-numeric, for then if the
+labels are too wide they will overstrike the references.  The default
+value, {@Code 2.00f}, is twice the current font size.  It may be
+changed to any length (Section {@NumberOf objects}).  Regrettably,
+Lout is not clever enough to choose a good value by itself.
+@PP
+Finally, @Code "@RefListSortKey" determines the sorting key used when
+sort.ref @Index { sorting of reference lists }
+reflistsortkey.sym @Index { @Code "@RefListSortKey" }
+ordering the reference list.  The default value,
+@ID @Code "@RefListSortKey { @Tag }"
+sorts by tag; the other popular possibility is to sort by the
+@Code "@Label" option:
+@ID @Code "@RefListSortKey { @Label }"
+As usual @Code "@Label" will use the value of a @Code "label" option
+to the citation if there is one.  There is no way to sort by order of
+first appearance in the document.
+@PP
+@Code "@RefListSortKey" may be any sequence of words
+and options from the @Code "@Reference" symbol, but not @Code "@RefNum"
+for obvious reasons.  A possible more elaborate sorting key is
+@ID @Code "@RefListSortKey { @Author:@Year:@Tag }"
+sorting first by author, then by year within each author, and finally
+by tag.  However you
+are supposed to choose tags which have this effect, and that is more
+reliable since the modern practice is to put the authors' surnames
+after their given names.  There seems to be little practical use for
+sorting keys other than {@Code "@Tag"} and {@Code "@Label"}.
+@PP
+A colon within the @Code "@RefListSortKey" option is converted by Lout
+into a character smaller than any printable character, which ensures that
+the sorting is carried out separately on the three fields.  It is essential
+that the sort key uniquely identify the reference, because if two sort
+keys are equal only one of the references will be printed.  The easiest
+way to ensure this is to always include @Code "@Tag" in the sort key.
+@End @Section
diff --git a/doc/user/ref_cite b/doc/user/ref_cite
new file mode 100644
index 0000000..89958b9
--- /dev/null
+++ b/doc/user/ref_cite
@@ -0,0 +1,90 @@
+@Section
+    @Title { Citation }
+    @Tag { citation }
+@Begin
+@PP
+To cite one or more references, use the @Code "@Cite" symbol like this:
+citing @Index { citing references }
+cite. @Index @Code "@Cite"
+@ID @Code {
+"This feature is beyond our scope @Cite { $kingston1995lout.expert, page 97 }."
+}
+The following object must be enclosed in braces.  It may be an arbitrary
+object as usual.  Within it the @Code "$" character is a symbol with a
+special meaning:  it causes a citation to be made of the reference whose
+@Code "@Tag" option is the word following the @Code "$" symbol:
+@ID {
+This feature is beyond our scope @Cite { $kingston1995lout.expert, page 97 }.
+}
+The reference itself will appear automatically in a reference list at
+the end of the document, and the citation(s) will be enclosed in brackets
+as shown.  There is no need to write @Code "${kingston1995lout.expert},"
+as would normally be the case, because within @Code "@Cite" special
+arrangements are made to prevent commas and semicolons from being a
+nuisance.
+@PP
+A reference may be cited many times, but it will appear in the
+reference list only once.  The references will ordinarily be sorted by
+tag and labelled with Arabic numbers, although this can be changed by
+setting options in the setup file (Section {@NumberOf changeref}).
+@PP
+If you are making a book, there is a @Code "@ChapCite" symbol which is
+chap.cite @Index @Code "@ChapCite"
+the same as @Code "@Cite" except that its references come out at the
+end of the current preface, introduction, chapter, or appendix, rather
+than at the end of the document.
+@PP
+It is quite all right to cite a reference from within a footnote, figure,
+table, or index entry.  The reference will appear in the closest
+reference list following the citation point in the final printed document,
+or if there is no such list, the closest preceding reference list.  This
+is fine in documents with just one reference list; but when using
+@Code "@ChapCite" in books, if the citation point appears after the intended
+reference list (because the footnote or figure has floated past the reference
+list at the end of the chapter), the reference will come out in the wrong list.
+@PP
+Although it is frowned upon by the authorities, some people include
+references which are not cited anywhere in the body of their document.  For
+this there is {@Code "@NoCite"}:
+no.cite @Index @Code "@NoCite"
+@ID @Code {
+"... our scope @NoCite { $kingston1995lout.expert, $kingston1993lout.design }."
+}
+produces
+@ID {
+... our scope @NoCite { $kingston1995lout.expert, $kingston1993lout.design }.
+}
+with the @Code "@NoCite" symbol and any preceding space removed.  The
+references will nevertheless appear in the reference list as usual.  There
+is a @Code "@NoChapCite" symbol that combines @Code "@NoCite" and
+no.chap.cite @Index @Code "@NoChapCite"
+{@Code "@ChapCite"}.  For compatibility with previous versions of Lout,
+there is a @Code "@Ref" symbol:
+ref. @Index @Code "@Ref"
+@ID @Code "@Ref kingston1995lout.expert"
+is the same as @Code "@Cite { $kingston1995lout.expert }" without the
+brackets.  There are analogous {@Code "@ChapRef"}, {@Code "@NoRef"},
+and {@Code "@NoChapRef"}
+chap.ref @Index @Code "@ChapRef"
+no.ref @Index @Code "@NoRef"
+no.chap.ref @Index @Code "@NoChapRef"
+symbols, which are not recommended.
+@PP
+The @Code "@RefPrint" symbol will print a reference on the spot:
+ref.print @Index @Code "@RefPrint"
+resume. @Index { resumes }
+curriculum. @Index { curriculum vitae }
+@ID @Code "@RefPrint kingston1995lout.expert"
+has result
+@ID @RefPrint kingston1995lout.expert
+unrelated to any reference list.  For example,
+@ID @OneRow @Code {
+"@Heading { Journal Articles }"
+"@NumberedList"
+"@LI @RefPrint kingston1985tree"
+"..."
+"@LI @RefPrint kingston1993lout.design"
+"@EndList"
+}
+might appear in someone's resume.
+@End @Section
diff --git a/doc/user/ref_crea b/doc/user/ref_crea
new file mode 100644
index 0000000..994f8d3
--- /dev/null
+++ b/doc/user/ref_crea
@@ -0,0 +1,139 @@
+@Section
+    @Title { Creating your own entry types and formats }
+    @Tag { refstyles }
+@Begin
+@PP
+Although the set of options to the @Code "@Reference" symbol
+({@Code "@Tag"}, {@Code "@Type"}, {@Code "@Author"}, etc.) is fixed, you
+can add your own reference types and change the formatting of existing types.
+@PP
+To do this you must be using your own setup file, as explained in
+Section {@NumberOf setup}.  At the end of the setup file you will find
+this line:
+reference.print @Index { reference printing style }
+ref.style @Index @Code "@RefStyle"
+@ID @Code "@SysDatabase @RefStyle { refstyle }"
+This tells Lout to consult a database file of reference styles called
+{@Code "refstyle.ld"}.  These are not references, they are formatting
+styles, one for each reference type.  The @Code "Sys" in @Code "@SysDatabase"
+sys.database @Index @Code "@SysDatabase"
+means that this file is stored in the @I { Lout system database directory },
+system.database.dir @Index { system database directory }
+refstyle.ld.file @Index { @Code "refstyle.ld" file}
+which is where all the standard databases are kept.  To change the
+formatting of a reference type, or to add your own types, you need to
+create your own reference styles database file by copying and modifying
+{@Code "refstyle.ld"}.
+@PP
+To find out the name of the Lout system database directory, type the
+Unix command
+@ID @Code "lout -V"
+Then, supposing that the Lout system database directory is
+{@Code "/usr/lout/data"}, type
+@ID @Code "cp /usr/lout/data/refstyle.ld mystyle.ld"
+to place a copy of the @Code "refstyle.ld" database file in your
+mystyle.ld.file @Index { @Code "mystyle.ld" file}
+directory, renaming it {@Code "mystyle.ld"}.  Since @Code "refstyle.ld"
+is read-only, you may also need to change the mode of @Code "mystyle.ld"
+to be writable (by @Code "chmod +w mystyle.ld" in Unix).  Now replace
+@ID @Code "@SysDatabase @RefStyle { refstyle }"
+at the end of your setup file by
+@ID @Code "@Database @RefStyle { mystyle }"
+and Lout will read its reference styles from @Code "mystyle.ld" instead
+of {@Code "refstyle.ld"}.  Since the two are at
+present identical, this has changed nothing so far; but now any changes
+you make to @Code "mystyle.ld" will affect your document.  Changing
+@Code "@SysDatabase" to @Code "@Database" makes Lout search your
+current directory for {@Code "mystyle.ld"}, whereas @Code "@SysDatabase"
+searches only the system directory.
+@PP
+In practice you will probably want to store your database of reference
+styles in some library directory, so that it can be used by
+many documents.  A Unix pathname is appropriate for this:
+@ID @Code "@Database @RefStyle { \"/usr/jeff/lib/mystyle\" }"
+Quotes are needed because of the @Code "/" characters.
+@PP
+The database entries within @Code "refstyle.ld" and @Code "mystyle.ld"
+might look something like this:
+@ID @OneRow @Code {
+"{ Book @RefStyle @Style"
+"  {  @Reference&&reftag @Open"
+"     {"
+"        @Author.  @I @Title.  @Publisher, @Year."
+"     }"
+"  }"
+"}"
+}
+The meaning of the first two lines is beyond our scope, except that
+@Code "Book" on the first line means that this is the entry which
+defines how references of type @Code Book will be printed.  Fortunately,
+apart from this one word these two lines are the same in every
+reference style entry so you don't need to understand them.  The
+important part is in the middle:
+@ID @Code "@Author.  @I @Title.  @Publisher, @Year."
+The meaning should be clear:  first print the author option and a full
+stop, then the title option and another full stop in italics, and so
+on.  To change the formatting of books, change this object.  To create
+a new reference type, copy the entire database entry, change @Code Book
+to a new name of your choice, and change the middle part.  Don't forget
+to delete the index file @Code "mystyle.li" afterwards, if there is one,
+so that Lout knows to generate it afresh.
+@PP
+Although the entry shown above is perfectly viable, the real entry for
+@Code Book is much more complicated, in part because there are more
+options than those basic four, but mainly because the real entry goes
+to great lengths to do the right thing when options are omitted:
+@ID @Tab
+    vmargin { 0.45vx }
+    @Fmta { @Col @Code A ! @Col @Code B }
+{
+@Rowa A { "{ Book @RefStyle @Style" }
+@Rowa A { "  {  @Reference&&reftag @Open" }
+@Rowa A { "     {" }
+@Rowa A { "        {  @Author.  {}" }		B { "}  @If  @Author" }
+@Rowa A { "        {  @I @Title" }		B { "}  @If  @Title" }
+@Rowa A { "        {  @Word&&notitle" }		B { "}  @If  @Not @Title" }
+@Rowa A { "        {  , @Pinpoint" }		B { "}  @If  @Pinpoint" }
+@Rowa A { "        {  , @Word&&pages @NumSep @Pages" }	B { "}  @If  @Pages" }
+@Rowa A { "        {  , @Word&&page @NumSep @Page" }	B { "}  @If  @Page" }
+@Rowa A { "        {  .  @TitleNote" }		B { "}  @If  @TitleNote" }
+@Rowa A { "        {  .  @HowPublished" }	B { "}  @If  @HowPublished" }
+@Rowa A { "        {  .  @Publisher" }		B { "}  @If  @Publisher" }
+@Rowa A { "        {  .  @Organization" }	B { "}  @If  @Organization" }
+@Rowa A { "        {  .  @Institution" }	B { "}  @If  @Institution" }
+@Rowa A { "        {  , @Address" }		B { "}  @If  @Address" }
+@Rowa A { "        {  .  @Edition" }		B { "}  @If  @Edition" }
+@Rowa A { "        {  , @Month @Year" }	B { "}  @If  @Year @And @Month" }
+@Rowa A { "        {  , @Year " }	B { "}  @If  @Year @And @Not @Month" }
+@Rowa A { "        {  ." }		B { "}  @If  @True" }
+@Rowa A { "        {  {}  URL @URL." }	B { "}  @If  @URL" }
+@Rowa A { "        {  {}  @Note" }	B { "}  @If  @Note" }
+@Rowa A { "     }" }
+@Rowa A { "  }" }
+@Rowa A { "}" }
+}
+The meaning is that each object to the left of an @Code "@If" will be
+if. @Index @Code "@If"
+printed only if the condition to the right of the @Code "@If" is
+true.  The condition may contain options, which are considered to be
+true if they are not omitted (non-empty), and it may contain {@Code "@And"},
+and. @Index @Code "@And"
+or. @Index @Code "@Or"
+not. @Index @Code "@Not"
+true. @Index @Code "@True"
+{@Code "@Or"}, {@Code "@Not"}, and @Code "@True" with the usual precedence
+and meaning.  Sub-conditions may be enclosed in braces if desired, although
+it is best to keep the conditions as simple as possible given the
+complexity of the whole setup.
+@PP
+The objects subject to @Code "@If" are printed with no space preceding
+them; any space in the final print will be the result of space within
+them, not between them.  This is why @Code "@If @True" is not redundant.
+@PP
+The object @Code "@Word&&notitle" produces @Code "No title" in the
+current language; @Code "@Word&&pages" produces {@Code pages} in the
+current language, and so on.  Consult database @Code "standard.ld" for
+standard.ld.file @Index { @Code "standard.ld" file }
+other standard words and phrases, and page {@PageOf numsep} for
+{@Code "@NumSep"}.
+@End @Section
diff --git a/doc/user/ref_entr b/doc/user/ref_entr
new file mode 100644
index 0000000..63516b2
--- /dev/null
+++ b/doc/user/ref_entr
@@ -0,0 +1,293 @@
+@Section
+    @Title { Constructing database entries }
+    @Tag { entries }
+@Begin
+@PP
+Here is the complete, fixed list of options that you may give to the
+@Code "@Reference" symbol:
+@ID @Tab
+   vmargin { 0.5vx }
+   @Fmta { @Col @Code A ! @Col B }
+{
+@Rowa
+    A { "{ @Reference" }
+@Rowa
+    A { "    @Tag  {}" }
+    B { Used to cite this reference }
+@Rowa
+    A { "    @Type  {}" }
+    B { The type of reference, for example {@Code Book}, {@Code Article} }
+@Rowa
+    A { "    @Abstract  {}" }
+    B { Not used, intended to hold an abstract }
+@Rowa
+    A { "    @Address  {}" }
+    B { The address of a publisher, organization, or institution }
+@Rowa
+    A { "    @Annote  {}" }
+    B { Not used, intended for annotations }
+@Rowa
+    A { "    @Author  {}" }
+    B { The author(s) or editor(s) }
+@Rowa
+    A { "    @Day  {}" }
+    B { The day of the month, for newspaper articles }
+@Rowa
+    A { "    @Edition  {}" }
+    B { The edition, for example @Code "Second Edition" }
+@Rowa
+    A { "    @HowPublished  {}" }
+    B { How something strange has been published }
+@Rowa
+    A { "    @InAuthor  {}" }
+    B { The author of the work that the cited work appears within }
+@Rowa
+    A { "    @InTitle  {}" }
+    B { The title of the work that the cited work appears within }
+@Rowa
+    A { "    @Institution  {}" }
+    B { The institution or school }
+@Rowa
+    A { "    @Journal  {}" }
+    B { The journal name }
+@Rowa
+    A { "    @Keywords  {}" }
+    B { Not used, intended to hold keywords }
+@Rowa
+    A { "    @Label  {}" }
+    B { The label of a labelled reference }
+@Rowa
+    A { "    @Month  {}" }
+    B { The month of publication or writing  }
+@Rowa
+    A { "    @Note  {}" }
+    B { Any additional helpful information }
+@Rowa
+    A { "    @Number  {}" }
+    B { The number of a technical report }
+@Rowa
+    A { "    @Organization  {}" }
+    B { The organization sponsoring the work }
+@Rowa
+    A { "    @Page  {}" }
+    B { Page number if only one, for example @Code "23" }
+@Rowa
+    A { "    @Pages  {}" }
+    B { Page numbers if more than one, for example @Code "23--47" }
+@Rowa
+    A { "    @Pinpoint  {}" }
+    B { A point or part of the work, for example @Code "Chapter VI" }
+@Rowa
+    A { "    @Publisher  {}" }
+    B { The publisher of the work }
+@Rowa
+    A { "    @Title  {}" }
+    B { The title of the work }
+@Rowa
+    A { "    @TitleNote  {}" }
+    B { Additional title information (series, editor, etc.) }
+@Rowa
+    A { "    @TRType  {}" }
+    B { The type of a technical report, for example @Code "Research Note" }
+@Rowa
+    A { "    @URL  {}" }
+    B { The URL of the reference }
+@Rowa
+    A { "    @Volume  {}" }
+    B { The volume of a journal }
+@Rowa
+    A { "    @Year  {}" }
+    B { The year of publication or writing }
+@Rowa
+    A { "}" }
+}
+Every reference may contain any of these options, although, depending
+on the {@Code "@Type"} option, only some will be printed.  You can't give
+an option twice; in particular, multiple authors must be placed
+within one @Code "@Author" option, arranged as you want them to appear.  Here
+is the complete set of values that you may give to the @Code "@Type" option:
+@ID @Tab
+    vmargin { 0.5vx }
+    @Fmta { @Col @Code A ! @Col @Code B ! @Col @Code C ! @Col @Code D }
+{
+ @Rowa
+    A { Book }
+    B { TechReport }
+    C { Article }
+    D { InBook }
+ @Rowa
+    A { Proceedings }
+    B { MastersThesis }
+    C {}
+    D { InProceedings }
+ @Rowa
+    A { PhDThesis }
+    B { Misc }
+    C {}
+    D {}
+}
+Each column represents one broad category of reference type:  the first
+contains large works; the second contains small works not appearing
+within anything else (although possibly part of a series); the third
+contains small works appearing within an ongoing forum for such works;
+and the fourth contains small works appearing within large works.  In each
+case, the reference may be to the work as a whole, or to one point or part
+of it (known as pinpointing).
+@PP
+Some care is needed when choosing the @Code "@Tag" option, since references
+are both cited and sorted by tag.  It is best to choose a three-part
+tag consisting of the first author's surname and possibly initial, the
+year of publication, and a brief reminder of the contents:
+@ID @Code "@Tag { kingston1995lout.expert }"
+Keep to lower-case letters, since mixed cases confuse the sorting, and
+give the full four digits of the year to avoid trouble in the year
+2000.  Multi-word tags are possible but not recommended.
+@PP
+Unusually for Lout, you can have unquoted @Code "/" and @Code "~"
+characters inside the @Code "@URL" option:
+@ID @Code "@URL { ftp://ftp.cs.su.oz.au/jeff/lout }"
+In fact it is better not to use quotes because then Lout will
+be able to break lines at @Code "/" characters, which is very useful
+since URLs tend to be long and prone to causing bad line breaks.
+@PP
+Since the types within each broad category are similar, our plan is to
+give one example of each and briefly note how the others differ.  Here
+is a @Code Book entry showing all its options:
+book.ref.type @Index { @Code Book reference type }
+@ID @OneRow @Code {
+"{ @Reference"
+"     @Tag { homer.odyssey }"
+"     @Type { Book }"
+"     @Author { Homer }"
+"     @Title { The Odyssey }"
+"     @TitleNote { Translated by E. V. Rieu }"
+"     @Pinpoint { Chapter VI }"
+"     @Pages { 102--111 }"
+"     @Page { 102 }"
+"     @Publisher { Penguin Books }"
+"     @Address { Harmondsworth, Middlesex }"
+"     @Edition { Penguin Classics Edition }"
+"     @Month { August }"
+"     @Year { 1942 }"
+"     @Note { The date of composition is unknown,"
+"but is thought to be about the tenth century BC. }"
+"}"
+}
+And here is what it produces:
+@ID @RefPrint homer.odyssey
+The only compulsory options are {@Code "@Tag"}, {@Code "@Type"}, and
+{@Code "@Title"}, and Lout will carefully adjust the formatting to the
+right thing when you omit others.  A basic book would have just
+{@Code "@Tag"}, {@Code "@Type"}, {@Code "@Author"}, {@Code "@Title"},
+{@Code "@Publisher"}, and {@Code "@Year"} options.
+@PP
+@Code Proceedings is similar, except you
+proceedings.ref.type @Index { @Code Proceedings reference type }
+may have an @Code "@Organization" or @Code "@Institution" option for
+the sponsoring organization if you wish, and the author will either be
+absent or an editor:
+@ID @Code "@Author { P. W. Lamb, editor }"
+There is no option specifically for editors, translators, and so forth.
+@PP
+@Code PhDThesis is very similar again, with @Code "@Institution"
+phdthesis.ref.type @Index { @Code PhDThesis reference type }
+instead of {@Code "@Publisher"}, and the phrase `Ph.D. thesis'
+appearing by magic in the right spot.  Like all words and phrases
+introduced automatically by Lout, it will be translated into the current
+language if this is not English.
+@PP
+Moving now to the second broad category, here is a typical {@Code TechReport}:
+techreport.ref.type @Index { @Code TechReport reference type }
+@ID @OneRow @Code {
+"{ @Reference"
+"     @Tag { christofides1976tsp }"
+"     @Type { TechReport }"
+"     @Author { Christofides, N. }"
+"     @Title { Worst-case analysis of a new heuristic"
+"for the travelling salesman problem }"
+"     @Number { 388 }"
+"     @Institution { Graduate School of Industrial"
+"Administration, Carnegie-Mellon University }"
+"     @Address { Pittsburgh, PA }"
+"     @Year { 1976 }"
+"}"
+}
+Here is the result:
+@ID @RefPrint christofides1976tsp
+The two novelties here are the @Code "@Number" option, which is the
+number of the report, and the `Tech. Rep.' phrase.  If you
+need some other phrase instead, use the @Code "@TRType" option:
+@ID @Code "@TRType { Programmer's Manual }"
+or whatever.  The phrase will be `Master's Thesis' in the
+current language for type {@Code MastersThesis}, and absent in type
+mastersthesis.ref.type @Index { @Code MastersThesis reference type }
+misc.ref.type @Index { @Code Misc reference type }
+{@Code Misc}.  You may use the pinpointing options ({@Code "@Pinpoint"},
+{@Code "@Page"}, and {@Code "@Pages"}) and {@Code "@TitleNote"},
+{@Code "@Month"}, and {@Code "@Note"} in the same way as for books.
+@PP
+Journal articles are referenced by journal name, volume, number, and
+page(s):
+article.ref.type @Index { @Code Article reference type }
+@ID @OneRow @Code {
+"{ @Reference"
+"     @Tag { kingston1993lout.design }"
+"     @Type { Article }"
+"     @Author { Jeffrey H. Kingston }"
+"     @Title { The design and implementation of the"
+"Lout document formatting language }"
+"     @Journal { Software---Practice and Experience }"
+"     @Volume { 23 }"
+"     @Pages { 1001--1041 }"
+"     @Year { 1993 }"
+"}"
+}
+The result of this is
+@ID @RefPrint kingston1993lout.design
+All are optional, as usual.  Notice that @Code "@Pages" and @Code "@Page"
+refer to the whole article so are not available for pinpointing here,
+but you may still use {@Code "@Pinpoint"}.
+@PP
+Finally, small works that appear within large works have @Code "@Author"
+inbook.ref.type @Index { @Code InBook reference type }
+and @Code "@Title" options for the work itself, and @Code "@InAuthor" and
+@Code "@InTitle" for the work that it appears within:
+@ID @OneRow @Code {
+"{ @Reference"
+"     @Tag { rieu1942intro }"
+"     @Type { InBook }"
+"     @Author { E. V. Rieu }"
+"     @Title { Introduction to @I { The Odyssey } }"
+"     @InAuthor { Homer }"
+"     @InTitle { The Odyssey }"
+"     @Publisher { Penguin }"
+"     @Year { 1942 }"
+"}"
+}
+@Code "@InAuthor" would often be absent or an editor.  The result is
+@ID @RefPrint rieu1942intro
+The other options are as for large works.  Type @Code InProceedings is
+inproceedings.ref.type @Index { @Code InProceedings reference type }
+similar to {@Code InBook}.
+@PP
+A database usually has a long life, and some day it might find itself
+used in a document whose language is not the one its original compiler
+had in mind.  For this reason, a truly meticulous compiler of database
+entries would enclose @I all language-specific options in
+@Code "@Language" symbols:
+@ID @OneRow @Code {
+"{ @Reference"
+"    @Tag { zimand1986size.sets.strings }"
+"    @Type { Article }"
+"    @Author { French @Language { M. Zimand } }"
+"    @Title { English @Language { On the topological size of sets of random strings } }"
+"    @Journal { German @Language { Zeitschr. f. math. Logik und Grundlagen d. Math. } }"
+"    @Volume { 32 }"
+"    @Pages { 81--88 }"
+"    @Year { 1986 }"
+"}"
+}
+(My apologies to M. Zimand if he or she is not French.)  This ensures
+correct hyphenation whatever the language of the document in which the
+reference appears.
+@End @Section
diff --git a/doc/user/ref_labe b/doc/user/ref_labe
new file mode 100644
index 0000000..1b8cc54
--- /dev/null
+++ b/doc/user/ref_labe
@@ -0,0 +1,65 @@
+@Section
+    @Title { Labelled (as opposed to numbered) references }
+    @RunningTitle { Labelled references }
+    @Tag { labelled }
+@Begin
+@PP
+Lout ordinarily assigns a number to each reference, and prints this
+labelled.refs @Index { labelled references }
+number beside the reference in the reference list and at the point(s)
+of citation.  There is a way to make Lout use a label of your choice
+instead of a number for each reference.  First change the following
+setup file options to the values shown (these options are explained
+in Section {@NumberOf changeref}):
+@ID @OneRow @Code {
+"@RefCiteLabels { @Label }"
+"@RefListLabels { @Label. }"
+"@RefListLabelWidth { 4.00f }"
+"@RefListSortKey { @Label }"
+}
+Then make sure that every reference you cite has a {@Code "@Label"} option:
+@ID @OneRow @Code {
+"{ @Reference"
+"    @Tag { kingston1995lout.expert }"
+"    @Type { TechReport }"
+"    @Label { Kin94 }"
+"    ..."
+"}"
+}
+@Code "@Label" may contain several words, and even font changes, but not
+an arbitrary object.
+@PP
+The effect of these changes is that your references will now be labelled
+with their @Code "@Label" options instead of with numbers, and they will
+be sorted by label instead of by tag.  However, tags are still used when
+citing.
+@PP
+The big problem with labels is that they vary from document to
+document, either because of a change of style or because the usual
+first few letters of the authors' names plus year has to be augmented
+with {@Code a}, {@Code b}, {@Code c} etc. to distinguish publications
+by the same authors in the same year.  To help you overcome these
+problems, the @Code "$" symbol has a @Code "label" option:
+@ID @Code {
+"@Cite { $ label { Kin94a } kingston1995lout.expert, ... }"
+}
+The @Code "@Ref" and @Code "@ChapRef" symbols also have a @Code label
+option.  If you use this option, it will be used to label the reference
+instead of the @Code "@Label" option from the @Code "@Reference" symbol
+(indeed, the @Code "@Reference" symbol need have no @Code "@Label" option
+in this case).  But note that using @Code "label" does not itself give
+you labelled references; you get them with the setup file options as
+explained above.
+@PP
+If your labels turn out to be too wide for the space allowed for them
+in the reference list, you have two alternatives.  One is to increase
+the @Code "@RefListLabelWidth" setup file option shown above, since it
+determines this space.  The other is to change the @Code "@RefListFormat"
+setup file option to {@Code "DropLabels"}, which produces drop items:
+@ID @OneRow {
+@RawTaggedList
+@DTI { Kin94a. } @RefPrint kingston1995lout.expert
+@RawEndList
+}
+Then it won't matter how wide your labels are.
+@End @Section
diff --git a/doc/user/ref_sett b/doc/user/ref_sett
new file mode 100644
index 0000000..283cb11
--- /dev/null
+++ b/doc/user/ref_sett
@@ -0,0 +1,95 @@
+@Section
+    @Title { Setting up a bibliographic database }
+    @Tag { databases }
+@Begin
+@PP
+The basic idea is to store your references in a separate
+database.file @Index { database file }
+@I { database file }, in a form which does not include formatting
+details such as font changes.  This makes it easy to use the same
+references in many documents, and it leaves the formatting to Lout.  Here
+is an example of a reference as it would appear in a database file:
+@ID @OneRow @Code {
+"{ @Reference"
+"    @Tag { vanleunen1992 }"
+"    @Type { Book }"
+"    @Author { Mary-Claire van Leunen }"
+"    @Title { A Handbook for Scholars }"
+"    @Publisher { Oxford }"
+"    @Edition { Revised Edition }"
+"    @Year { 1992 }"
+"}"
+}
+reference. @Index @Code "@Reference"
+@Code "@Reference" is a symbol, and {@Code "@Tag"}, {@Code "@Type"},
+{@Code "@Author"}, and so on are its options.  The database file as
+a whole consists of a sequence of references, each enclosed in braces
+as shown.
+@PP
+The @Code "@Tag" option is compulsory:  since you cite a reference by
+giving its tag, there must be one.  The @Code "@Type" option is also
+type. @Index { @Code "@Type" option }
+compulsory, since it says whether the reference is to a book, a journal
+article, or whatever, and this determines what other options are
+required.  Section {@NumberOf entries} describes all the types provided
+by Lout, and Section {@NumberOf refstyles} explains how to add your own.
+@PP
+Lout database file names must end in {@Code ".ld"}, so now suppose that
+you have made one called
+ld.file @Index { @Code ".ld" file }
+refs.ld.file @Index { @Code "refs.ld" file }
+@Code "refs.ld" and put it in the same directory as your document.  Next,
+place
+@ID @Code "@Database @Reference { refs }"
+database. @Index @Code "@Database"
+at the start of your document, just before {@Code "@Doc"},
+{@Code "@Document"}, {@Code "@Report"}, or whatever.  Alternatively,
+you may place it at the end of your setup file.  It informs Lout that
+you might be referring to @Code "@Reference" symbols in database
+@Code "refs" (that is, in file {@Code "refs.ld"}).
+@PP
+If you want to maintain a central database, used by many documents, you
+won't want it in the same directory as any one of them.  A Unix
+pathname will be more appropriate:
+@ID @Code "@Database @Reference { \"/usr/jeff/lib/refs\" }"
+or whatever.  Quotes are needed because of the @Code "/" characters.
+@PP
+With the database file created and the @Code "@Database" line in place,
+you are ready to start citing references.  The first time that the
+database.index.file @Index { database index file }
+index.file @Index { index file }
+database is used, Lout will create an @I { index file } whose purpose
+is to speed up the retrieval of your references.  Thanks to this file
+you can have hundreds or even thousands of references in your database,
+without slowing Lout down very much.  However, whenever you change your
+database file @I { you must remove its corresponding index file }, so
+that Lout knows to create it afresh.
+@FootNote {
+Depending on how it was installed on your system, Lout may be able to
+use the time of last modification of the database file and its index
+file to determine automatically whether the index file needs to be
+created afresh, thus saving you the trouble of removing it.  You can
+find out whether this is true of your system by typing the command
+{@Code "lout -V"}.
+}
+ The index file is stored in the
+same directory as the database file, and it has the same name except
+that it ends in @Code ".li" rather than @Code ".ld" (e.g.
+li.file @Index { @Code ".li" file }
+{@Code "refs.li"}).
+@PP
+If a separate database file is not convenient for some reason, perhaps
+because you need a self-contained document in a single file, the
+@Code "@Reference" symbols may be incorporated into the document
+itself, anywhere that ordinary text may appear.  Nothing will appear
+where they are typed in, but Lout will notice them and treat them as if
+they had come from a database file.  In this case no @Code "@Database"
+symbol is needed unless you are referring to a database as well.
+@PP
+You may have multiple databases, like this:
+@ID @OneRow @Code {
+"@Database @Reference { myrefs }"
+"@Database @Reference { \"/usr/pub/refs/theoryrefs\" }"
+}
+Lout will search the databases in the order you list them.
+@End @Section
diff --git a/doc/user/str b/doc/user/str
new file mode 100644
index 0000000..0312dfb
--- /dev/null
+++ b/doc/user/str
@@ -0,0 +1,19 @@
+@Chapter
+    @Title { Adding Structure to Documents }
+    @Tag { structure }
+@Begin
+@BeginSections
+@Include { str_disp }
+@Include { str_list }
+@Include { str_foot }
+@Include { str_marg }
+@Include { str_theo }
+@Include { str_figs }
+@Include { str_larg }
+@Include { str_cros }
+@Include { str_cont }
+@Include { str_indx }
+@Include { str_colu }
+@Include { str_defs }
+@EndSections
+@End @Chapter
diff --git a/doc/user/str_colu b/doc/user/str_colu
new file mode 100644
index 0000000..b54a404
--- /dev/null
+++ b/doc/user/str_colu
@@ -0,0 +1,40 @@
+@Section
+   @Title { Multiple columns }
+   @Tag { columns }
+@Begin
+@PP
+You can change the number of columns of text per page, and the width of
+columns. @Index columns
+multiple.columns @Index { multiple columns }
+the gap between the columns, by changing these two setup file options:
+columnnumber. @Index @Code "@ColumnNumber"
+columngap. @Index @Code "@ColumnGap"
+@ID @OneRow @Code {
+"@ColumnNumber { 1 }"
+"@ColumnGap { 1.00c }"
+}
+If you are using your own setup file (Section {@NumberOf setup}), you can
+find and change them there.  If not, @Code "@ColumnNumber" may be changed
+at the beginning of your document (Section {@NumberOf ordinary}).
+@PP
+@Code "@ColumnNumber" may be any number between 1 and 10, with default
+value 1 as shown, and @Code "@ColumnGap" may be any length (Section
+{@NumberOf objects}).  The column width is derived from these options
+column.width @RawIndex { column width }
+column.width.pages @SubIndex { on pages }
+using the obvious formula
+@ID @Eq { columnwidth = { pagewidth - margins -
+({@Code "@ColumnNumber"} - 1) times {@Code "@ColumnGap"} }
+over @Code "@ColumnNumber"
+}
+You must ensure that this comes to something reasonable.
+@PP
+These two options do not apply to pages containing an index.  For them
+there are similar setup file options called @Code "@IndexColumnNumber"
+and @Code "@IndexColumnGap" (Section {@NumberOf indexes}).
+@PP
+Most document types permit you to have multiple columns, but certain
+things will be kept full width regardless of the @Code "@ColumnNumber"
+option:  figures and tables, chapter headings, and so on.  The details
+vary with the document type, so are deferred to Chapter {@NumberOf types}.
+@End @Section
diff --git a/doc/user/str_cont b/doc/user/str_cont
new file mode 100644
index 0000000..148447e
--- /dev/null
+++ b/doc/user/str_cont
@@ -0,0 +1,83 @@
+@Section
+   @Title { Tables of contents }
+   @Tag { contents }
+@Begin
+@PP
+Lout takes note of the titles of all your large-scale structure symbols
+contents. @Index { contents, tables of }
+tables.of.contents. @Index { tables of contents }
+(Section {@NumberOf largescale}) and what pages they begin on, and it
+uses this information to produce a table of contents like the one at
+the start of the present document.  It is totally automatic; you do
+nothing.
+@PP
+Some details of the appearance of the table of contents, including
+whether to make one or not, are controlled by options in the setup
+file.  The default setting is to make one in books but not to in
+other types of documents, but by changing the setup file you can have
+a table of contents in any type of document.
+@PP
+Section @NumberOf setup describes setup files in general and how to
+change the options within them.  The options relevant to tables of
+contents and their default values are:
+@ID @OneRow @Code {
+"@MakeContents { No }"
+"@ContentsGap { 0.20v }"
+"@ContentsGapAbove { 0.80v }"
+"@ContentsGapBelow { 0.00v }"
+"@ContentsLeader { .. }"
+"@ContentsLeaderGap { 4s }"
+"@ContentsRightWidth { 3f }"
+}
+The @Code "@MakeContents" option may be @Code Yes or {@Code No}, and
+makecontents. @Index @Code "@MakeContents"
+determines whether a table of contents is made or not.  Its default
+value is @Code No but it is set to @Code Yes in the @Code book setup
+file.
+@PP
+@Code "@ContentsGap" determines how much vertical space to leave
+contentsgap. @Index @Code "@ContentsGap"
+above each line of the table of contents, in addition to the usual
+single line spacing; its value may be any length (Section
+{@NumberOf objects}).  The default value, {@Code "0.20v"}, is twenty
+percent of the current inter-line spacing.
+@PP
+Some entries, such as those for chapters and appendices in books, are
+more important than others.  @Code "@ContentsGap" does not apply to these
+entries; instead, @Code "@ContentsGapAbove" and @Code "@ContentsGapBelow"
+contentsgapabove. @Index @Code "@ContentsGapAbove"
+contentsgapbelow. @Index @Code "@ContentsGapBelow"
+are used above and below each of them, again in addition to the usual
+single line spacing.
+@PP
+@Code "@ContentsLeader" is the object which is repeated across the page
+contentsleader. @Index @Code "@ContentsLeader"
+to connect each entry with its page number; popular values are @Code ".."
+and @Code "." and the empty object.  @Code "@ContentsLeaderGap" determines
+contentsleadergap. @Index @Code "@ContentsLeaderGap"
+how far apart these objects are; the default value, {@Code "4s"}, is
+four times the width of a space character.  @Code "@ContentsLeaderGap"
+may be {@Code "0s"}, but only if @Code "@ContentsLeader" is non-empty.
+@PP
+@Code "@ContentsRightWidth" reserves some
+contentsrightwidth. @Index @Code "@ContentsRightWidth"
+space at the far right for page numbers.  Any entry wide enough to
+intrude into this space is broken into two or more lines to keep it
+clear.
+@PP
+In addition to these options, each document type has options that
+determine which large-scale structure symbols will be listed in the
+table of contents.  For example, among the options to the
+@Code "@BookSetup" symbol in the @Code book setup file are these:
+@ID @OneRow @Code {
+"@ChapterInContents { Yes }"
+"@SectionInContents { Yes }"
+"@SubSectionInContents { Yes }"
+"@SubSubSectionInContents { No }"
+"@AppendixInContents { Yes }"
+"@SubAppendixInContents { Yes }"
+"@SubSubAppendixInContents { No }"
+}
+Each may be either {@Code "Yes"} or {@Code "No"}; these default values
+produce entries for everything except sub-subsections and sub-subappendices.
+@End @Section
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
diff --git a/doc/user/str_defs b/doc/user/str_defs
new file mode 100644
index 0000000..71bd71e
--- /dev/null
+++ b/doc/user/str_defs
@@ -0,0 +1,134 @@
+@Section
+   @Title { Defining new symbols }
+   @Tag { definitions }
+@Begin
+@PP
+Whenever you find yourself typing the same thing repeatedly, you can
+definitions. @Index definitions
+save a lot of time by defining your own personal symbol to stand for that
+thing.  For example, suppose you type your company's name, @Batlow,
+frequently.  You can define your own symbol, {@Code "@Batlow"} say,
+so that
+@ID @Code {
+"Concerning your crate supply contract with @Batlow, @Batlow wishes to ..."
+}
+produces
+@ID {
+Concerning your crate supply contract with @Batlow, @Batlow wishes to ...
+}
+You will never have to type @Batlow again.
+@PP
+The method is to create a file called @Code "mydefs" in your current
+mydefs.file @Index { @Code mydefs file }
+directory, containing definitions like this:
+@ID @OneRow @Code {
+"import @BasicSetup"
+"def @Batlow { Batlow Food Distributors Pty. Ltd. }"
+}
+The meaning of the first line, {@Code "import @BasicSetup"}, will
+be explained shortly.  After that comes @Code "def" for `define,'
+then the name of the symbol being defined, then its value between
+braces.  So this example defines a symbol called @Code "@Batlow" to
+stand for the object following it between braces.  Lout will read this
+file during its setup phase (Section {@NumberOf setup}).
+@PP
+Your symbols may have any names you wish made from letters and
+{@Code "@"}.  However, it is good practice to have exactly one
+{@Code "@"}, at the start, and to choose distinctive names that
+have no chance of being the same as the name of any existing
+symbol.  @Code "@Batlow" is a good choice, for example.
+@PP
+The object between braces is quite arbitrary; in particular, it may
+contain symbols.  For example, suppose you frequently need a small grey box:
+@ID @OneRow @Code {
+"import @BasicSetup"
+"def @GreyBox { @Box paint { lightgrey } {} }"
+}
+This defines a @Code "@GreyBox" symbol that produces {@GreyBox}.  Most
+of the symbols in this guide are from the @I {BasicSetup package},
+import. @Index @Code import
+which is why @Code "import @BasicSetup" is required:  it makes
+these symbols available to the definition, and can actually be omitted
+before definitions like the one for @Code "@Batlow" which do not use
+any symbols.  However it does no harm, so we place it in front of every
+definition as a matter of course.
+@FootNote {
+Later chapters of this guide introduce specialized symbols for producing
+tables, equations, diagrams, graphs, and computer programs.  You need a
+different @Code "import" clause when using those symbols within a
+definition, because they are not from the BasicSetup package.  Examples
+may be found in the chapters concerned.
+}
+@PP
+Now suppose you frequently need a grey box, but enclosing different
+things:  @GreyBox ENTRY one moment, @GreyBox EXIT the next.  You could
+try omitting the @Code "{}" from the definition above, but that does
+not work, because Lout notices the missing object while reading the
+definition, and inserts an empty object in the usual way (Section
+{@NumberOf empty}).
+@PP
+However, there is a way to define a @Code "@GreyBox" symbol so that
+@Code "@GreyBox ENTRY" produces {@GreyBox ENTRY}, @Code "@GreyBox EXIT"
+produces {@GreyBox EXIT}, and so on:
+@ID @OneRow @Code {
+"import @BasicSetup"
+"def @GreyBox right x { @Box paint { lightgrey } x }"
+}
+The addition of @Code "right x" immediately after the symbol's name
+places @Code "@GreyBox" into that class of symbols, like {@Code "@I"}
+and @Code {"@Box"}, which consume and transform the object to their
+right.  The @Code "x" in @Code "right x" means that the object to the
+right will be referred to as @Code "x" within the definition.  So in
+@ID @Code "@GreyBox { Hello world }"
+@Code "@GreyBox" consumes the following object, which becomes
+{@Code "x"}, so that the value is
+@ID @Code "@Box paint { lightgrey } { Hello world }"
+which produces @GreyBox { Hello world }.
+@PP
+It is a good principle to choose symbol names that refer to what the symbol
+is for, rather than how it does what it does.  Here is a good example:
+@ID @OneRow @Code {
+"import @BasicSetup"
+"def @Poetry right x { lines @Break @I x }"
+}
+This kind of name is very pleasant to use, since it allows you to
+forget about what is going on behind the scenes:
+@ID @OneRow @Code {
+"@IndentedDisplay @Poetry {"
+"Teach me to hear Mermaides singing,"
+"Or to keep off envies stinging,"
+"     And finde"
+"     What winde"
+"Serves to'advance an honest minde."
+"}"
+}
+Most of Lout's symbols follow this principle.
+@PP
+You can define symbols that consume the object to their left as well
+as the object to their right, as the {@Code "@Font"}, {@Code "@Break"},
+and {@Code "@Colour"} symbols do:
+@ID @OneRow @Code {
+"import @BasicSetup"
+"def @HeadingBox left x right y"
+"{  @Box { @CentredDisplay @Heading x y }"
+"}"
+}
+This definition occupies several lines only because it is long; as
+usual, end of line is the same as one space.  Now
+@ID @OneRow @Code {
+"Cheating @HeadingBox {"
+"The Department uses assignments ... of that student alone."
+"}"
+}
+is much easier to type than the equivalent example in Section
+{@NumberOf boxes}.  The result is the same:
+@QD Cheating @HeadingBox {
+The Department uses assignments both as a teaching device and as a
+major component of its assessment of each student.  It therefore
+requires that all programs, exercises etc. handed in bearing an
+individual student's name be the work of that student alone.
+}
+Do not use a paragraph, display, or list symbol at the beginning or end
+of a definition, since the result is not what people who do it are
+hoping for.
+@End @Section
diff --git a/doc/user/str_disp b/doc/user/str_disp
new file mode 100644
index 0000000..4634103
--- /dev/null
+++ b/doc/user/str_disp
@@ -0,0 +1,94 @@
+@Section
+   @Title { Displays }
+   @Tag { displays }
+@Begin
+@PP
+The @Code "@Display" symbol displays the following object in the centre
+displays. @Index displays
+display. @Index @Code "@Display"
+of the page or column:
+@ID @Code "@Display @I { Invitation to Afternoon Tea }"
+has result
+@Display @I { Invitation to Afternoon Tea }
+Space is inserted automatically above and below the display; no
+paragraph symbols are needed.
+@PP
+To make the display appear at the left margin instead of centred, use
+leftdisplay. @Index @Code "@LeftDisplay"
+{@Code "@LeftDisplay"} instead of {@Code "@Display"}.  To make an indented
+display, use {@Code "@IndentedDisplay"} or {@Code "@QuotedDisplay"};
+indenteddisplay. @Index @Code "@IndentedDisplay"
+quoteddisplay. @Index @Code "@QuotedDisplay"
+the latter indents at the right margin as well as at the left. There are
+also @Code "@CentredDisplay" and @Code "@CenteredDisplay" symbols which
+centreddisplay. @Index @Code "@CentredDisplay"
+centereddisplay. @Index @Code "@CenteredDisplay"
+centre the display just like {@Code "@Display"} does, and
+rightdisplay. @Index @Code "@RightDisplay"
+@Code "@RightDisplay" which right-justifies the display.
+@PP
+If you use displays frequently you might prefer abbreviated forms of
+their names.  These are made from @Code "@" and the capital letters of
+d. @Index @Code "@D"
+ld. @Index @Code "@LD"
+id. @Index @Code "@ID"
+qd. @Index @Code "@QD"
+cd. @Index @Code "@CD"
+the full name:  {@Code "@D"}, {@Code "@LD"}, {@Code "@ID"}, {@Code "@QD"},
+and {@Code "@CD"}.  Owing to a clash with the name of another symbol,
+{@Code "@RightDisplay"} has no abbreviation.
+@PP
+Displays often need to be set using a different font, paragraph
+breaking style, and so on to the surrounding text.  It's best to set
+out such displays like this:
+@ID @OneRow @Code {
+"@CentredDisplay @I clines @Break {"
+"Invitation to Afternoon Tea"
+"with"
+"Mr. and Mrs. Gilbert Newington-Smith"
+"}"
+}
+You can have as many of these symbols as you like, including specialized
+ones like {@Code "@CurveBox"} and {@Code "@Tbl"}.  The only rule is that
+the display symbol must come first:  @Code "@I @Display ..." is wrong.
+@PP
+It's not a good idea to have one display immediately followed by
+another one, because there will be too much vertical space between
+them.  Use a list instead (Section {@NumberOf lists}).  Displays
+at the ends of paragraphs look awkward and are best avoided.
+@PP
+A display may come out partly on one page or column and partly on
+the next, if it has places where it obviously can be broken in two.  For
+example, a display which is an ordinary paragraph of text might be
+broken in two between any two lines.  To force a display to keep
+together on one page or column, use the @Code "@OneRow" symbol like
+this:  @Code "@Display @OneRow { ... }".
+@PP
+Other display symbols produce aligned and numbered displays, and raw
+displays (i.e.  without vertical space).  Although these can display any
+object as usual, in practice they are used for mathematics, so they are
+described in Section {@NumberOf mathdisplays}.
+@PP
+Three setup file options control the appearance of displays.  (For a
+general introduction to setup files and their options, consult
+Section {@NumberOf setup}.)  Here they are with their default values:
+@ID @OneRow @Code {
+"@DisplayGap { 1.00v }"
+"@DefaultIndent { 0.5rt }"
+"@DisplayIndent { 2.00f }"
+}
+@Code "@DisplayGap" is the amount of vertical space inserted before and
+display.gap. @Index @Code "@DisplayGap"
+after displays, and may be any length (Section {@NumberOf objects}).  The
+default value, @Code {"1.00v"}, is equal to the current inter-line spacing.
+@PP
+@Code "@DefaultIndent" is the indent produced by
+default.indent @Index @Code "@DefaultIndent"
+{@Code "@Display"}; {@Code "0.5rt"} produces centring, although why it does
+so is beyond our scope
+@Cite { $kingston1995lout.expert }.  @Code "@DisplayIndent" is the
+display.indent. @Index @Code "@DisplayIndent"
+indent for {@Code "@IndentedDisplay"}, and used at both margins by
+{@Code "@QuotedDisplay"}.  Its default value, {@Code "2.00f"}, is twice
+the current font size.
+@End @Section
diff --git a/doc/user/str_figs b/doc/user/str_figs
new file mode 100644
index 0000000..285e097
--- /dev/null
+++ b/doc/user/str_figs
@@ -0,0 +1,270 @@
+@Section
+   @Title { Figures and tables }
+   @Tag { figures }
+@Begin
+@PP
+Figures are created in a similar way to footnotes:
+figures. @Index { figures }
+@ID @OneRow @Code {
+"@Figure"
+"    @Caption { Basser Lout }"
+"@Diag vstrut { yes } treehsep { 1c } {"
+"    @HTree { @Box Lout @FirstSub arrow { yes } @Box PostScript }"
+"}"
+}
+The @Code "@Figure" symbol places the following object (which in this example is
+figure. @Index @Code "@Figure"
+created using the advanced graphics features of Chapter {@NumberOf diagrams})
+at the top of the following column or page,
+@Figure
+    @Tag { figex }
+    @Caption { Basser Lout }
+@Diag vstrut { yes } treehsep { 1c } {
+    @HTree { @Box Lout @FirstSub arrow { yes } @Box PostScript }
+}
+labelled by the @Code "@Caption" option and automatically numbered.  You
+captions. @RawIndex { captions }
+captions.figures @SubIndex { in @Code "@Figure" and @Code "@Table" }
+can see this example at the top of page {@PageOf figex}.  Tables are
+table. @Index @Code "@Table"
+obtained in the same way using {@Code "@Table"} instead of {@Code "@Figure"}.
+@PP
+@Code "@Figure" and @Code "@Table" each have an @Code "@InitialLanguage"
+option which determines the language of the figure or table.  If this is
+omitted, the language of the document as a whole will be used, not the
+language where the figure or table occurs.
+@PP
+The two symbols also have a @Code "@CaptionPos" option, which determines
+whether the caption appears above or below the figure or table.  The
+default is {@Code "Below"}, the alternative is {@Code "Above"}.
+@PP
+The question of what is a suitable running header to print on pages
+containing figures and tables (possibly from different sections) is a
+rather awkward one.  On any page with a figure or table at the top, Lout
+uses whatever running header was appropriate for the text on the previous
+page.  In practice it seems to work quite well.
+@PP
+If your document contains many figures, large figures, or multi-page
+figures, you are likely to encounter cases where Lout's assignment of
+figures to pages is not pleasing.  In that case, you can improve things
+by moving the figures around within the body text, and by using the
+@Code "@Location" option of the @Code "@Figure" symbol, which determines
+location. @Index @Code "@Location"
+where the figure will appear.  Its possible values are
+@DP @Tab
+    @Fmta { @Col @Code A ! @Col B }
+{
+@FirstRowa
+    A { PageTop }
+    B { The figure will appear at the top of the following page, occupying
+the full page width; or, if there is insufficient space there (owing to other
+figures already present), at the top of the first subsequent page with
+sufficient space. }
+@Rowa
+    A { EvenPageTop }
+    B { Like @Code PageTop except that the first page of the figure
+or table will be an even-numbered (left-hand or verso) page -- useful
+for double-pace spreads.  }
+@Rowa
+    A { FullPage }
+    B { Like {@Code PageTop} except that nothing else will appear on the
+same page as the figure except the usual running headers and footers, and
+possibly other @Code FullPage figures and tables.
+@FootNote { This location replaces the @Code "@FullPage" option of
+earlier versions of Lout, which has been withdrawn. }
+}
+@Rowa
+    A { EvenFullPage }
+    B { Like {@Code FullPage} except that the first page of the figure
+or table will be an even-numbered (left-hand or verso) page, like
+{@Code EvenPageTop}.
+}
+@Rowa
+    A { PageFoot }
+    B { The figure will appear at the foot of the current page, occupying
+the full page width; or, if there is insufficient space there, at the top
+of the following page and so on as for {@Code PageTop}. }
+@Rowa
+    A { ColTop }
+    B { The figure will appear at the top of the following column,
+occupying the column width; or, if there is insufficient space there,
+at the top of the first subsequent column with sufficient space.  This
+is different from @Code PageTop only in multi-column documents. }
+@Rowa
+    A { ColFoot }
+    B { The figure will appear at the foot of the current column,
+occupying the column width; or, if there is insufficient space there, at
+the top of the following column as for {@Code ColTop}.  This differs
+from @Code PageFoot only in multi-column documents. }
+@Rowa
+    A { ColEnd }
+    B { The figure will appear in a column at the end of the document
+(or chapter, appendix etc. in the case of books).  There is no
+@Code PageEnd value corresponding to {@Code ColEnd}. }
+@Rowa
+    A { AfterLine }
+    B { The figure will appear as a column-width display immediately after
+the line in the final printed document in which it occurs. }
+@Rowa
+    A { TryAfterLine }
+    B { The same as @Code {AfterLine} unless there is insufficient space
+in the current column to hold the displayed figure, in which case it
+switches to @Code {ColTop} instead. }
+@Rowa
+    A { Display }
+    B { The figure will appear as a display at the point it occurs.  There
+is no @Code TryDisplay value corresponding to {@Code Display}. }
+@Rowa
+    A { Raw }
+    B { The figure will appear as an object, with no extra spacing, at
+the point it occurs.  This is useful, for example, for getting two figures
+side by side in one display:  use a displayed table containing two raw
+figures. }
+}
+@DP
+The @Code "@Table" symbol also has this option.  The default location is
+{@Code "PageTop"}, but this can be changed by changing the
+figurelocation. @Index @Code "@FigureLocation"
+tablelocation. @Index @Code "@TableLocation"
+@Code "@FigureLocation" and @Code "@TableLocation" setup file options.
+@PP
+The numbers assigned to figures and tables, and their ordering in any list
+of figures or tables, is based on where they appear in the final printed
+document, not on where they appear in the source files.  This is better for
+the reader in the unusual case of a fixed figure being overtaken by a
+floating one.  If a section number is printed as part of a figure number,
+and the figure floats forward from one section into another, the figure
+number will reflect the later section, not the earlier one as it should.
+You can fix this problem by moving the figure to an earlier point in
+the section, or by not having section numbers in figures (see below).
+@PP
+@Code "@Figure" and @Code "@Table" each have a @Code "@OnePage" option,
+whose value may be @Code "Yes" or {@Code No}.  Setting @Code "@OnePage"
+to @Code Yes causes the figure or table and its caption to be kept
+together on one page or column (enclosing the body of the figure or table
+in @Code "@OneRow" would have the same effect except that it would not
+incorporate the caption, hence the need for this option).  You need to be
+certain that the whole assembly will fit on one page when setting
+@Code "@OnePage" to {@Code "Yes"}.
+@PP
+The @I default value of the @Code "@OnePage" option for each figure or
+table depends on the value of its @Code "@Location" option as follows:
+@ID @Tab
+    @Fmta { @Col @Code A ! @Col ! @Col @Code B }
+{
+@Rowa
+    A { No }
+    B { PageTop  ColTop  ColEnd  Raw }
+@Rowa
+    A { Yes }
+    B { PageFoot  ColFoot  Display  AfterLine  TryAfterLine }
+}
+These choices represent a guess that figures that the user is happy to
+see at the page foot or in a display are probably going to be small enough
+to keep on one page, but that other figures may not be.  In any case, these
+are only default values and you may set @Code "@OnePage" as you wish.
+@PP
+By default, the body of the figure will be centred, and this usually looks
+best, at least for small figures.  @Code "@Figure" and @Code "@Table" each
+have a @Code "@Format" option which controls this format:
+@ID @Code {
+"@Figure"
+"    @Format { @CurveBox @HExpand @CC @Body }"
+}
+Within the @Code "@Format" option, the @Code "@Body" symbol stands for the
+body of the figure or table; it must appear exactly once.  Display symbols
+such as @Code "@CentredDisplay" may not be applied to the {@Code "@Body"}
+symbol; instead, there are {@Code "@II"}, {@Code "@QQ"}, {@Code "@CC"}, and
+{@Code "@RR"}, which indent, quote, centre, or right-justify the following
+object.  The example just given centres the figure inside a @Code "@CurveBox"
+which is horizontally expanded (by the @Code "@HExpand" symbol, which is not
+specific to figures) to occupy the full width of the page or column, rather
+than fitting snugly around the figure.
+@PP
+The @Code "@Format" option applies to just the body of the figure, not to
+its caption.  It applies to each page or column of a multi-page or
+multi-column figure; for example, the above format will draw a box around
+each page of a multi-page figure, and each page will be separately centred.
+@Code "ColEnd" and @Code "Raw" figures are exceptions to this rule:  they
+always apply the format to the figure as a whole.  This means that you cannot
+box multi-page figures of these two types, since the result would be an
+unbreakable object too large to fit on one page.
+@PP
+There are setup file options for controlling the appearance of figures and
+tables.  Only those for figures will be given here, since the ones for tables
+are identical except that @Code Table replaces @Code Figure in their
+names.  Here they all are:
+@FootNote { These are as of Version 3.15 and above.  Prior to that
+there were {@Code "@CaptionFont"}, {@Code "@CaptionBreak"}, and
+{@Code "@CaptionFormat"} options, and {@Code "@CaptionFormat"}
+took values that did not include the @Code "caption" symbol. }
+@ID @OneCol @Code {
+"@FigureLocation { PageTop }"
+"@FigureFormat { @CC @Body }"
+"@FigureWord { figure }"
+"@FigureNumbers { Arabic }"
+"@FigureCaptionPos { Below }"
+"@FigureCaptionFont { }"
+"@FigureCaptionBreak { }"
+"@FigureCaptionFormat { @B { word @NumSep number. &2s } @Insert caption }"
+"@MakeFigureContents { No }"
+"@FigureListWord { figurelist }"
+}
+@Code "@FigureLocation" is the default value of the @Code "@Location"
+option of figures.  Changing it, for example to
+{@Code "FullPage"}, changes the location of all figures at
+once.  You may still override this location for any individual figure,
+however, by giving that figure a @Code "@Location" option.  In a similar way,
+figureformat. @Index @Code "@FigureFormat"
+tableformat. @Index @Code "@TableFormat"
+@Code "@FigureFormat" is the default value of the @Code "@Format"
+option (this shows why figures are centred by default) and
+figurecaptionpos. @Index @Code "@FigureCaptionPos"
+tablecaptionpos. @Index @Code "@TableCaptionPos"
+@Code "@FigureCaptionPos" is the default value of {@Code "@CaptionPos"}.
+@PP
+@Code "@FigureWord" determines the word that is part of the figure
+number.  The default value, {@Code figure}, produces `Figure' or its
+equivalent in the current language; any other value produces itself.
+@PP
+@Code "@FigureNumbers"
+figurenumbers. @Index @Code "@FigureNumbers"
+tablenumbers. @Index @Code "@TableNumbers"
+determines whether figures are
+numbered automatically or not; the choices are
+{@Code "None"}, {@Code "Arabic"}, {@Code "Roman"}, {@Code "UCRoman"},
+{@Code "Alpha"}, and {@Code "UCAlpha"}.  Depending on the document
+type and where the figure or table occurs, the number might include
+a chapter number as well.  This is determined by options in the
+setup file for your document type; for example, 
+@ID @Code "@SectionNumInFigures { No }"
+appears in the @Code "report" setup file, and means that a section
+number will not appear in the figure number (unless you change the
+option to {@Code Yes}).
+@PP
+@Code "@FigureCaptionFont" and @Code "@FigureCaptionBreak" determine the
+font and paragraph breaking style used in the captions of figures.  Their
+default values are empty, meaning to use the initial font and break styles;
+but, for example, you could have
+@ID @Code "@FigureCaptionFont { -2p }"
+in your setup file to get a smaller font size in your captions.
+@PP
+The @Code "@FigureCaptionFormat" option determines the format of the
+caption.  Within it, the symbol @Code word stands for the `Figure'
+word as defined by {@Code "@FigureWord"}); the @Code number
+symbol stands for the number of the figure; and @Code caption stands
+for the body of the caption.  The default value shown above prints
+the word and number and a period in bold, inserted together with a
+gap of two spaces into the first paragraph of the caption.  If you
+don't use the @Code "@Insert" symbol you'll run into problems with
+multi-paragraph captions.
+@PP
+You can get a list of figures at the start of your document by setting
+the @Code "@MakeFigureContents" setup file option to {@Code Yes}.  The
+format of these lists will follow the format of tables of contents.  These
+lists are only available in books (Section {@NumberOf books}).  The
+title printed above the list of figures is determined by the
+@Code "@FigureListWord" option; the default value, {@Code "figurelist"},
+produces `List of Figures' or its equivalent in the current language; any
+other value produces itself.
+@End @Section
diff --git a/doc/user/str_foot b/doc/user/str_foot
new file mode 100644
index 0000000..70e50a2
--- /dev/null
+++ b/doc/user/str_foot
@@ -0,0 +1,150 @@
+@Section
+   @Title { Footnotes and endnotes }
+   @Tag { footnotes }
+@Begin
+@PP
+A footnote is created by typing
+footnote. @Index @Code "@FootNote"
+@ID @Code "@FootNote { Like this. }"
+after the word that the footnote refers to.  It will be numbered
+automatically and placed at the foot of the page or column;
+@FootNote { Like this. }
+or, if space there is insufficient, it may start on or run onto the
+following page or column.  The footnote must be enclosed in braces.
+@PP
+The @Code "@FootNote" symbol has a @Code "@Location" option which
+determines where it goes:
+@ID @Code {
+"@FootNote"
+"    @Location { ColFoot }"
+"{ ... }"
+}
+places the footnote at the bottom of the column, and
+@ID @Code {
+"@FootNote"
+"    @Location { PageFoot }"
+"{ ... }"
+}
+places it at the bottom of the current page, occupying the full page
+width even in a multi-column document (this is occasionally
+useful for footnotes to headings).  Of course, in a single-column
+document there is no difference anyway.  The default value of the
+@Code "@Location" option is {@Code "ColFoot"}.
+@PP
+Endnotes work in exactly the same way as footnotes, except that the
+endnote. @Index @Code "@EndNote"
+symbol to use is @Code "@EndNote" and they appear either at the end
+of the document or at the end of some major part of it, depending on
+the type of document (Chapter {@NumberOf types}).  Endnotes are
+always column width and so have no @Code "@Location" option.
+@PP
+Footnotes are usually labelled with consecutive Arabic numberals, but
+you can tell Lout to label a footnote (not an endnote) with something
+else, like this:
+@ID @OneRow @Code @Verbatim {
+@FootNote
+    @Label { @Dagger }
+{ This footnote will be labelled with a dagger, not a number. }
+}
+whose result should appear at the bottom of this page.
+@FootNote
+    @Label { @Dagger }
+{ This footnote will be labelled with a dagger, not a number. }
+Symbols commonly used for footnote labels include @Code "@Dagger" (@Dagger),
+@Code "@DaggerDbl" (@DaggerDbl), @Code "@Star" (@Star),
+@Code "@SectSym" (@SectSym), and @Code "@ParSym" (@ParSym),
+but you can use any object.  If you want no label at all,
+use an empty object like this:
+@ID @OneRow @Code @Verbatim {
+@FootNote
+    @Label {}
+}
+Footnotes with a @Code "@Label" option are excluded from the automatic
+numbering that applies to other footnotes.
+@PP
+The language of a footnote or endnote will be the language of the
+document as a whole.  This is not necessarily the same as the
+current language at the point where the footnote or endnote occurs,
+or even the language of the enclosing large-scale structure symbol.  It
+may be necessary to enclose the body of the footnote in a language
+symbol, like this:
+@ID @Code "@FootNote { French @Language { ... } }"
+Doing it the other way ({@Code "French @Language @FootNote ..."}) is
+not effective.
+@PP
+A footnote attached to the very last line of a chapter or appendix of
+a book occasionally runs onto the first page of the following chapter
+or appendix, and this looks very poor.  If this happens, the solution
+is to place an @Code "@LP" after the last line (including the footnote).
+@PP
+In the rare case where more than one footnote is attached to one word,
+use @Code "@AnotherFootNote" for the second and subsequent footnotes:
+anotherfootnote. @Index @Code "@AnotherFootNote"
+@ID @Code {
+"something or other."
+"@FootNote { The first footnote. }"
+"@AnotherFootNote { The second footnote. }"
+}
+This ensures that the superscripts will be separated by
+commas, as convention demands.
+@PP
+The setup file contains a number of options for controlling the
+appearance of footnotes.  (See Section @NumberOf setup for a general
+introduction to setup files and their options.)  Here are all the
+options, with their default values:
+@ID @OneRow @Code {
+"@FootNoteThrough { No }"
+"@FootNoteLocation { ColFoot }"
+"@FootNoteNumbers { Arabic }"
+"@FootNoteFont { 0.80f }"
+"@FootNoteBreak { 1.20fx }"
+"@FootNoteFormat { { number &0.05f } @Insert body }"
+"@FootLen { 2.00c }"
+"@FootAboveGap { 1.00v }"
+"@FootGap { 0.20c }"
+}
+There are also setup file options for controlling endnotes.  Since
+they are quite similar to the ones for footnotes, we won't say any
+more about them here.
+@PP
+@Code "@FootNoteThrough" may be @Code "Yes" or @Code { "No" };
+footnotethrough. @Index @Code "@FootNoteThrough"
+@Code "Yes" means that the footnotes are numbered continuously
+through the document (or through each chapter in the case of books);
+@Code "No" means that the numbering begins afresh on each
+page.  @Code "@FootNoteLocation" determines the default value of
+footnotelocatin. @Index @Code "@FootNoteLocation"
+the @Code "@Location" option mentioned above; it may be either
+@Code "ColFoot" or {@Code "PageFoot"}.  @Code "@FootNoteNumbers"
+determines how the footnotes are numbered;
+footnotenumbers. @Index @Code "@FootNoteNumbers"
+it may be {@Code Arabic}, {@Code Roman}, {@Code UCRoman}, {@Code Alpha},
+or {@Code UCAlpha}.
+@PP
+@Code "@FootNoteFont" and @Code "@FootNoteBreak" determine the
+footnotefont. @Index @Code "@FootNoteFont"
+footnotebreak. @Index @Code "@FootNoteBreak"
+font and paragraph breaking style of footnotes.  The default value
+of @Code "@FootNoteFont" produces the same font family and face as the
+bulk of the document, but reduced to 0.8 times the original size.
+@PP
+@Code "@FootNoteFormat" determines the format of the footnote.  The
+@Code number symbol within it must appear exactly once, and is replaced
+by the number of the footnote (if numbered).  The @Code body symbol is
+replaced by the body (that is, the content) of the footnote.  The default
+value shown uses symbols from raw Lout to add a small space at the right of
+the number, then insert it at the beginning of the first paragraph of
+the body.  Another suitable value might be
+@ID @Code "@FootNoteFormat { number |1fx body }"
+which places the body in a separate column to the number, one
+font width to the right of the left edge of the number.
+@PP
+@Code "@FootLen" determines the length of the small horizontal line
+footlen. @Index @Code "@FootLen"
+drawn above the footnotes; 
+@Code "@FootAboveGap" determines the minimum space to be left clear
+footabovegap. @Index @Code "@FootAboveGap"
+above this line; and @Code "@FootGap" determines the
+footgap. @Index @Code "@FootGap"
+vertical separation between footnotes.  All three may be any length.
+@End @Section
diff --git a/doc/user/str_indx b/doc/user/str_indx
new file mode 100644
index 0000000..c9ea2de
--- /dev/null
+++ b/doc/user/str_indx
@@ -0,0 +1,314 @@
+@Section
+   @Title { Indexes }
+   @Tag { indexes }
+@Begin
+@PP
+Although Lout is not clever enough to guess what entries should go in
+indexes. @Index { indexes }
+your index, it will do almost everything else for you:  sort the
+entries and attach the correct page numbers automatically.  As for
+tables of contents, the default setting is to have an index in
+books but not in other types of documents.  This and a few aspects of
+the appearance of the index can be changed by changing the setup file,
+as explained at the end of this section.
+@PP
+Now, suppose you are discussing Galileo and you want his name in your
+index.  Let's be ambitious and say that you want the index to contain
+something like this:
+@ID @OneRow lines @Break {
+Galileo Galilei
+    life of, 201
+    telescope, his use of, 201--203
+    trial of, 205--211, 242, 395
+}
+Each line shows off one of Lout's four tricks:  the first is a
+@I { raw entry } (no page number attached); the second is a
+@I sub-entry (indented); the third has a @I { page number range }
+instead of a single page number; and the fourth is a @I { merged entry }
+(several page numbers or ranges within one entry).
+@PP
+We'll take each of them in turn in a moment, but first, let's see how
+to get a basic entry, like this one:
+@ID { Galileo Galilei, 201 }
+To get this into your index, type
+@ID @Code "galileo @Index { Galileo Galilei }"
+at the point where you mention Galileo.  Nothing will be printed there,
+but the object following the @Code "@Index" symbol will be placed in
+the index, with a comma and the correct page number appended
+automatically.
+@PP
+The object preceding the @Code "@Index" symbol is a compulsory key
+which is used for sorting the index entries,
+@FootNote {
+The collating sequence used to decide what comes after what is the
+collating sequence used by the @Code "memcmp()" library routine (just
+the underlying binary character codes).  Alternatively, the version
+of Lout installed on your system may use the @Code "strcoll()"
+collating sequence, which understands accented characters and whose
+effect depends on your locale.  To find out whether @Code "strcoll()"
+is in use or not, type @Code "lout -V" which prints out several lines
+of this and similar information.
+@PP
+If the sorting you get turns out to be not what you expected, the
+first thing to try is the replacement of all accented letters in index
+keys by unaccented ones.  Sorting is quite an intractable problem:  even
+if @Code "strcoll()" gets the sorting right for one language, there still
+remains the problem of sorting multilingual indexes.
+@PP
+Lout's database mechanism assumes that the @I tab character is collated
+before any character that could appear in a sorting key.  It seems that
+there are a few collating sequences in existence which do not satisfy this
+condition, and in these cases Lout will fail to produce the correct index.
+}
+but which is not itself printed anywhere.  It is best to construct these
+sorting keys from lower-case letters and the . character only, beginning
+with a letter, although multi-word keys are allowed.  These sorting keys
+do not have to be distinct from the tags used in cross referencing;
+however, they do have to be distinct from each other, unless you want
+merged entries (see below).
+@PP
+Our first trick, raw entries (no page number attached), is very
+easy:  just use @Code "@RawIndex" instead of {@Code "@Index"}.  So the
+first line of our ambitious example is obtained by
+@ID @Code "galileo @RawIndex { Galileo Galilei }"
+This could go anywhere, since no page numbers are involved.
+@PP
+Another use for @Code "@RawIndex" is to get blank lines into the index
+between the letters of the alphabet, by inserting phantom entries:
+@ID @OneRow @Code {
+"b @RawIndex {}"
+"c @RawIndex {}"
+"d @RawIndex {}"
+"..."
+"z @RawIndex {}"
+}
+In fact there is a symbol called @Code "@IndexBlanks" that makes
+indexblanks. @Index @Code "@IndexBlanks"
+exactly these 25 entries.  Unfortunately, these blanks will occasionally
+appear at the top of a column, and if there are no tags beginning with
+x, for example, there will be two blank lines between the w and y
+entries.  You can start off with @Code "@IndexBlanks" and replace it
+later by the appropriate subset, if necessary.
+@FootNote {
+For Lout to solve this problem automatically, it would need to be told
+which letter each index entry belongs under, perhaps by symbols
+{@Code "@AIndex"}, {@Code "@BIndex"}, etc.  The author felt that this
+would have been too tedious.
+}
+@PP
+Our second trick, sub-entries, is also very easy, since a sub-entry
+differs from an ordinary entry only by having an indent.  The symbol
+is {@Code "@SubIndex"}, so the second line of our ambitious example is
+produced by
+@ID @Code "galileo.life @SubIndex { life of }"
+You should always give sub-entries the same sorting key as their
+corresponding main entries, plus a . and another word, because then
+you can be certain that the sorting will place sub-entries directly
+after their main entries.  There is a @Code "@SubSubIndex" symbol that
+produces a double indent, and there are @Code "@RawSubIndex" and
+@Code "@RawSubSubIndex" symbols.
+@PP
+For our third trick, page number ranges, we use the @Code "to" option
+of the {@Code "@Index"}, {@Code "@SubIndex"}, and {@Code "@SubSubIndex"}
+symbols.  For example, to produce the sub-entry
+@ID { telescope, his use of, 201--203 }
+put
+@ID @Code {
+  "galileo.telescope @SubIndex to { gt.end } { telescope, his use of }"
+}
+at the beginning of the range, and
+@ID @Code "@PageMark { gt.end }"
+at the end.  You can use any tag you like inside the @Code "to" option,
+as long as it differs from every other tag (notice that sorting keys
+do not have to differ from tags, but @Code "to" options do:  this
+is because @Code "to" options go into @Code "@PageMark" like other
+tags do, and if two tags are the same we would have an ambiguous
+result of {@Code "@PageOf"}).  If both ends of the range fall on the
+same page, the @Code "to" option is ignored:  you will never get
+201--201.
+@PP
+Our fourth and final trick is the merged entry:
+@ID { trial of, 205--211, 242, 395 }
+The main thing to grasp is that this merged entry was originally three
+separate entries (sub-entries in this case):
+@ID @OneRow lines @Break {
+trial of, 205--211
+trial of, 242
+trial of, 395
+}
+We already know how to produce these three entries, using three
+@Code "@SubIndex" symbols, one with a @Code "to" option.  Now we have
+discovered that Lout is able to merge several entries into one
+entry.  This raises two questions:  how does Lout know which entries
+to merge? and given those entries, what does the merging produce?
+@PP
+The answer to the first question is that Lout merges entries whose
+sorting keys are equal.  The merged entry above is produced by these
+three entries, placed in the appropriate places:
+@ID @OneRow @Code {
+"galileo.trial @SubIndex to { gtrial.end } { trial of }"
+"galileo.trial @SubIndex { trial of }"
+"galileo.trial @SubIndex { trial of }"
+}
+The entries are merged because they have the same sorting key
+({@Code "galileo.trial"}), not because they happen to have the
+same content ({@Code "trial of"}).  In fact, once the page numbers are
+added the content is not the same at all.
+@PP
+Now, having decided that the three entries
+@ID @OneRow lines @Break {
+trial of, 205--211
+trial of, 242
+trial of, 395
+}
+must be merged, what does Lout do?  It takes the second entry, discards
+any initial part that is the same as the first entry ({@Code "trial of,"}
+in this case), and, if anything remains, it adds a comma, a space, and
+the remainder to the first entry, producing
+@ID { trial of, 205--211, 242 }
+in this case.  This process is repeated on this and the third entry,
+producing
+@ID { trial of, 205--211, 242, 395 }
+in this case, and so on.  The entries are merged in the order in which
+their points of origin appear in the final printed document.
+@PP
+If nothing remains after discarding the common initial part, nothing is
+added to the growing merged entry; in effect, the entry that could
+contribute nothing new is deleted.  With this in mind, let us return to
+our initial, ambitious example:
+@ID @OneRow lines @Break {
+Galileo Galilei
+    life of, 201
+    telescope, his use of, 201--203
+    trial of, 205--211, 242, 395
+}
+We now know how to produce all four of these entries, but one problem
+of some practical importance remains.  Suppose we delete the section on
+the life of Galileo.  If we had put the entry that produces `Galileo
+Galilei' in that section, we might inadvertently delete it, and the
+other two sub-entries will lose their main entry.  Before deleting
+anything, we must hunt through it for index entries and ponder their
+significance, an error-prone and time-wasting thing to do.
+@PP
+The solution is as follows.  When an index entry has sub-entries, make
+it raw, and repeat it just before each of its sub-entries:
+@ID @OneRow @Code {
+"galileo @RawIndex { Galileo Galilei }"
+"galileo.life @SubIndex { life of }"
+}
+at the first place,
+@ID @OneRow @Code {
+"galileo @RawIndex { Galileo Galilei }"
+"galileo.telescope @SubIndex { telescope, his use of }"
+}
+at the second, and so on.  Now it is easy to verify that every
+sub-entry has a main entry; and when deleting a sub-entry we can and
+should delete the adjacent main entry.  After sorting, our index
+entries will be
+@ID @Tab
+    @Fmta { @Col @Code A ! @Col B }
+{
+@Rowa
+    A { galileo }
+    B { Galileo Galilei }
+@Rowa
+    A { galileo }
+    B { Galileo Galilei }
+@Rowa
+    A { galileo }
+    B { Galileo Galilei }
+@Rowa
+    A { galileo }
+    B { Galileo Galilei }
+@Rowa
+    A { galileo }
+    B { Galileo Galilei }
+@Rowa
+    A { galileo.life }
+    B { {}    life of, 201 }
+@Rowa
+    A { galileo.telescope }
+    B { {}    telescope, his use of, 201--203 }
+@Rowa
+    A { galileo.trial }
+    B { {}    trial of, 205--211 }
+@Rowa
+    A { galileo.trial }
+    B { {}    trial of, 242 }
+@Rowa
+    A { galileo.trial }
+    B { {}    trial of, 395 }
+}
+The first five entries have the same sorting key, and will be merged
+as required.
+@PP
+The language of the index entry will be the initial language of the
+document as a whole, which is not necessarily the language at the point
+where the index entry occurs.  To get the correct language you will need a
+@Code "@Language" symbol following the @Code "@Index" symbol:
+@ID @Code "galileo. @Index French @Language { Galileo Galilei }"
+or whatever.  If you don't do this your index entry might be hyphenated
+incorrectly.
+@PP
+Although the page numbers in index entries will be kept up to date
+automatically as the document changes, as all cross references are, 
+it is best to refrain from inserting index entries until the document
+is complete and an overall plan of the structure of the index can
+be made.
+@PP
+The remainder of this section describes how to change the appearance of
+the index by setting options in the setup file.  For setup files and
+their options in general, consult Section {@NumberOf setup}.
+@PP
+There are five setup file options for the index.  Here they are with
+their default values:
+@ID @OneRow @Code {
+"@MakeIndex { No }"
+"@IndexFont { }"
+"@IndexBreak { oragged 1.2fx }"
+"@IndexColumnNumber { 2 }"
+"@IndexColumnGap { 1.00c }"
+}
+The @Code "@MakeIndex" option, which may be @Code Yes or {@Code No},
+makeindex. @Index @Code "@MakeIndex"
+determines whether to produce an index or not.  Although the default
+value is {@Code No}, any type of document may be given an index just
+by changing it to {@Code Yes}.  This has already been done in the
+@Code book setup file, but not in the others.
+@PP
+@Code "@IndexFont" determines the font and font size of index entries
+indexfont. @Index @Code "@IndexFont"
+(e.g. {@Code "Times Base 12p"}).  Leaving it empty as above produces
+the same font as the rest of the document.  @Code "@IndexBreak" is the
+indexbreak. @Index @Code "@IndexBreak"
+paragraph breaking style applied to index entries; @Code oragged is the
+traditional and best way.
+@PP
+@Code "@IndexColumnNumber" and @Code "@IndexColumnGap" determine the
+indexcolumnnumber. @Index @Code "@IndexColumnNumber"
+indexcolumngap. @Index @Code "@IndexColumnGap"
+number of index columns per page, and the gap between them, and are
+exactly analogous to the @Code "@ColumnNumber" and @Code "@ColumnGap"
+options described in Section {@NumberOf columns}.
+@PP
+Lout offers the possibility of having up to three independent indexes
+(useful for glossaries, author indexes, etc.).  The other two are called
+index A and index B, and they precede the main index in the
+output.  Just replace @Code Index by @Code IndexA to refer to index A,
+and by @Code IndexB to refer to index B.  For example,
+@ID @Code "smith.j @IndexA { Smith, John }"
+will insert an index entry to index A, and @Code "@IndexBBlanks"
+will insert the usual 25 blank entries into index B.
+@PP
+In large projects it might help to rename the @Code "@IndexA" symbol
+to something else, such as {@Code "@AuthorIndex"}.  This can
+be done by placing
+@ID @Code {
+"import @DocumentSetup"
+"macro @AuthorIndex { @IndexA }"
+}
+in the @Code mydefs file.  See Section {@NumberOf definitions} for
+an introduction to the @Code "mydefs" file; the word @Code macro
+is needed here instead of @Code "def" because we are introducing
+a new name for an existing symbol, not defining a new symbol.
+@End @Section
diff --git a/doc/user/str_larg b/doc/user/str_larg
new file mode 100644
index 0000000..618e69f
--- /dev/null
+++ b/doc/user/str_larg
@@ -0,0 +1,177 @@
+@Section
+    @Title { Large-scale structure:  chapters, sections, etc. }
+    @RunningTitle { Large-scale structure }
+    @Tag { largescale }
+@Begin
+@PP
+Lout's large-scale structure symbols vary with the type of document
+large.scale. @Index { large-scale structure }
+({@Code "@Chapter"} for books, @Code "@Overhead" for overhead
+transparencies, etc.), but they all work in the same way.  Here is a
+typical example, {@Code "@Section"}, as it would actually be used:
+@ID @OneRow @Code {
+"@Section"
+"    @Title { Allocation of teachers }"
+"@Begin"
+"@PP"
+"Apart from the usual need to avoid clashes, the allocation of teachers must"
+"ensure that no teacher teaches more than seven periods per day, or ..."
+"@End @Section"
+}
+First comes the symbol itself, then any options in the usual way, and
+then the following object, enclosed in @Code "@Begin" and
+{@Code "@End @Section"}.  The following object, also called the body
+of the section, may contain paragraphs, displays, and all the other
+features as usual.  The body should begin with a paragraph symbol,
+which may be @Code "@PP" or @Code "@LP" as you prefer.  The result is
+a section like the present one, automatically numbered, with the
+@Code "@Title" option for its heading, preceded by a conditional new
+title. @Index @Code "@Title"
+page symbol (Section {@NumberOf paragraphs}).
+@PP
+When @Code "@Section" symbols are used within an ordinary document, they
+must be bracketed by @Code "@BeginSections" and @Code "@EndSections"
+symbols, like this:
+@ID @OneRow @Code {
+"@SysInclude { doc }"
+"@Doc @Text @Begin"
+"preceding text"
+"@BeginSections"
+"@Section ... @End @Section"
+"@Section ... @End @Section"
+"..."
+"@Section ... @End @Section"
+"@EndSections"
+"@End @Text"
+}
+This arrangement is reminiscent of the one for lists, and, as for
+lists, there may be no paragraph or new page symbols before, between,
+or after the sections.  To change the gap between sections, you need
+to change the @Code "@SectionGap" option in the setup file, as explained
+in Chapter {@NumberOf types}.
+@PP
+The @Code "@Begin ... @End @Section" that brackets the body of each
+section may be abbreviated to {@Code "{ ... }"}.  However, the long
+form is recommended because it helps Lout to detect missing or extra
+braces within the body of the section.
+@PP
+All large-scale structure symbols have a @Code "@Tag" option, whose
+use is explained in Section {@NumberOf cross}, and a @Code "@RunningTitle"
+runningtitle. @Index @Code "@RunningTitle"
+option.  If running page headers have been requested, @Code "@RunningTitle"
+will be used if it is given, otherwise @Code "@Title" will be used for the
+running header.  For example, the present section begins like this:
+@ID @OneRow @Code {
+"@Section"
+"    @Title { Large-scale structure:  chapters, sections, etc. }"
+"    @RunningTitle { Large-scale structure }"
+"    @Tag { largescale }"
+"@Begin"
+"..."
+}
+The point is that the section title is rather long for a running
+title, and so we use @Code "@RunningTitle" to get an abbreviated
+version of it.
+@PP
+Section titles typically appear in Bold face in the section heading,
+but in Roman face in tables of contents and running page headers.  So
+if part of your title is in italics, enclose it in @Code "@II" rather
+than just @Code "@I" to ensure that you get the right kind of italics
+in both contexts.
+@PP
+All large-scale structure symbols also have an @Code "@InitialLanguage"
+option which sets the current language for the duration of that
+symbol.  However, footnotes, endnotes, figures, tables, references,
+and index entries are set in the initial language of the document as
+a whole, unless you change their language explicitly using the
+@Code "@Language" symbol.
+@PP
+The remainder of this section describes the setup file options for
+controlling the appearance of large-scale structure symbols.  (For an
+introduction to setup files, consult Section {@NumberOf setup}.)  These
+options mainly appear in the third @Code "@Use" clause, since exactly which
+large-scale structure symbols exist depends on the type of document.  For
+example, here are the setup file options from the @Code "doc" setup file
+relating to appendices:
+@ID @OneRow @Code {
+"@AppendixWord { appendix }"
+"@AppendixNumbers { UCAlpha }"
+"@FirstAppendixNumber { 1 }"
+"@AppendixHeadingFont { Bold }"
+"@AppendixHeadingBreak { ragged 1.2fx nohyphen }"
+"@AppendixHeadingFormat { number @DotSep title }"
+"@AppendixGap { 2.0v @OrIfPlain 2f }"
+"@AppendixInContents { Yes }"
+"@AppendixNumInTheorems { No }"
+"@AppendixNumInDisplays { Yes }"
+"@AppendixNumInFigures { No }"
+"@AppendixNumInTables { No }"
+"@AppendixPrefix { }"
+}
+There are similar options for each large-scale structure symbol.  Here is
+a brief explanation.
+@PP
+@Code "@AppendixWord" contains the word that is to be prefixed to the
+appendix number in full headings.  The special value @Code appendix
+produces Appendix or its equivalent translated into the current
+language.  Any other value produces itself.
+@PP
+@Code "@AppendixNumbers" determines the style of numbering of appendices,
+and may be {@Code Arabic}, {@Code Roman}, {@Code UCRoman}, {@Code Alpha},
+{@Code UCAlpha}, or {@Code None} meaning unnumbered.  Most common is
+{@Code Arabic}, but appendices traditionally use upper-case
+letters, hence the value {@Code UCAlpha} given above.
+@PP
+@Code "@FirstAppendixNumber { 1 }" is the number (always in Arabic) to
+assign to the first appendix.  It is almost always 1, but a few people
+like to start their numbering from 0; this is only possible if the
+style of numbering specified by @Code "@AppendixNumbers" is {@Code Arabic}.
+@PP
+@Code "@AppendixHeadingFont" and @Code "@AppendixHeadingBreak" specify
+the font and paragraph breaking style to be applied to the appendix
+heading (relative to {@Code "@InitialFont"} and {@Code "@InitialBreak"});
+the default values shown above produce Bold in the current font family
+and size, and ragged breaking without hyphenation.
+@PP
+@Code "@AppendixHeadingFormat" defines the format of the appendix
+heading.  Within it, the symbols @Code number and @Code title stand for the
+appendix number (including the appendix word) and title respectively.  The
+@Code "@DotSep" symbol produces a dot and two spaces, except when there is
+no number, when it produces nothing.  For example, to draw a full-width
+rule under the heading, change this option to
+@ID @Code "@AppendixHeadingFormat { number @DotSep title @LP @FullWidthRule }"
+Arbitrary formats are acceptable.
+@PP
+@Code "@AppendixGap" determines the vertical space to leave between
+appendices; the default above leaves {@Code 2v}, except that when plain
+text output is in effect it leaves @Code 2f instead.  To get a new page
+between appendices, use the magic value {@Code 2b}, which is raw Lout for
+new page.  In books, the major components (preface, introduction, tables
+of contents, parts, chapters, appendices, and indexes) always start on a
+new page and there is nothing you can do to change that.
+@PP
+@Code "@AppendixInContents" determines whether the appendix will be listed
+in the table of contents, and may be @Code "Yes" or {@Code No}.  The
+next few options determine whether an appendix number will be included
+in the numbers assigned to theorems etc., numbered displays, figures,
+and tables.
+@PP
+There is a @Code "@StructPageNums" setup file option which determines
+whether page numbers will include the numbers of large-scale structure
+symbols.  If it is {@Code "Yes"}, @Code "@AppendixPrefix" is prefixed
+to all page numbers of pages containing appendices.  For example, setting
+@Code "@AppendixPrefix" to @Code { APP- } produces page
+numbers APP-A-1, APP-A-2, and so on.  The object separating each element
+of such compound numbers is determined by the @Code "@NumberSeparator"
+numberseparator. @Index @Code "@NumberSeparator"
+setup file option, which has default value @Code "." but which can easily
+be set to @Code "-" or @Code "--" if desired.
+@PP
+Running page headers above appendices always include the title of
+the appendix, so there is no option for specifying whether to do so or
+not.  But for subappendices and other such smaller units, the choice of
+whether to mention them in running headers is left to the user:
+@ID @Code "@SubAppendixNumInRunners { Yes }"
+Despite the misleading name, this option determines whether the entire
+subappendix @I title as well as number will be used as a running header.
+@End @Section
diff --git a/doc/user/str_list b/doc/user/str_list
new file mode 100644
index 0000000..0654ca6
--- /dev/null
+++ b/doc/user/str_list
@@ -0,0 +1,392 @@
+@Section
+   @Title { Lists }
+   @Tag { lists }
+@Begin
+@PP
+The @Code "@List" symbol introduces a sequence of items to be
+lists. @Index { lists }
+list. @Index @Code "@List"
+l. @Index @Code "@L"
+made into a displayed list:
+@ID @OneRow @Code {
+"preceding text"
+"@List"
+"@ListItem @I Emma"
+"@ListItem @I { Mansfield Park }"
+"@EndList"
+"following text"
+}
+After the initial @Code "@List" symbol, each item is introduced by
+list.item. @Index @Code "@ListItem"
+li. @Index @Code "@LI"
+{@Code "@ListItem"}, and the list ends with {@Code "@EndList"}.  The
+end.list. @Index @Code "@EndList"
+el. @Index @Code "@EL"
+result here is
+@ID @OneRow {
+preceding text
+@List
+@ListItem @I Emma
+@ListItem @I { Mansfield Park }
+@EndList
+following text
+}
+with space inserted automatically before, between, and after
+the items.
+@PP
+As the example shows, the @Code "@List" symbol causes the items to be
+indented.  Also available are {@Code "@LeftList"}, {@Code "@IndentedList"},
+leftlist. @Index @Code "@LeftList"
+ll. @Index @Code "@LL"
+indentedlist. @Index @Code "@IndentedList"
+il. @Index @Code "@IL"
+{@Code "@QuotedList"}, {@Code "@CentredList"}, and {@Code "@CenteredList"},
+quotedlist. @Index @Code "@QuotedList"
+ql. @Index @Code "@QL"
+centredlist. @Index @Code "@CentredList"
+centeredlist. @Index @Code "@CenteredList"
+cl. @Index @Code "@CL"
+which format the items like the corresponding display symbols do.
+Other list symbols generate a @I label for each item.  For example,
+@Code "@NumberedList" causes the items to be numbered:
+numberedlist. @Index @Code "@NumberedList"
+nl. @Index @Code "@NL"
+@ID @OneRow @Code {
+"@Heading { Quiz }"
+"@NumberedList"
+"@ListItem { Which American statesman owned a two-storey clock? }"
+"@ListItem { Which Yankee commander from the Civil War cut a"
+"swathe of destruction through the State of Georgia? }"
+"@EndList"
+}
+has result
+@ID @OneRow {
+@Heading { Quiz }
+@NumberedList
+@ListItem { Which American statesman owned a two-storey clock? }
+@ListItem { Which Yankee commander from the Civil War cut a
+swathe of destruction through the State of Georgia? }
+@RawEndList
+}
+The generated labels are added at the left margin.  Here is the full set
+of label-generating list symbols, showing the first label produced by each:
+parennumberedlist. @Index @Code "@ParenNumberedList"
+pnl. @Index @Code "@PNL"
+romanlist. @Index @Code "@RomanList"
+rl. @Index @Code "@RL"
+parenromanlist. @Index @Code "@ParenRomanList"
+prl. @Index @Code "@PRL"
+ucromanlist. @Index @Code "@UCRomanList"
+ucrl. @Index @Code "@UCRL"
+parenucromanlist. @Index @Code "@ParenUCRomanList"
+pucrl. @Index @Code "@PUCRL"
+alphalist. @Index @Code "@AlphaList"
+al. @Index @Code "@AL"
+parenalphalist. @Index @Code "@ParenAlphaList"
+pal. @Index @Code "@PAL"
+ucalphalist. @Index @Code "@UCAlphaList"
+ucal. @Index @Code "@UCAL"
+parenucalphalist. @Index @Code "@ParenUCAlphaList"
+pucal. @Index @Code "@PUCAL"
+bulletlist. @Index @Code "@BulletList"
+bl. @Index @Code "@BL"
+starlist. @Index @Code "@StarList"
+sl. @Index @Code "@SL"
+dashlist. @Index @Code "@DashList"
+dl. @Index @Code "@DL"
+@ID @Tab
+    @Fmta { @Col @CC A ! @Col @Code B ! @Col ! @Col @CC C ! @Col @Code D }
+{
+@Rowa
+    A { 1. }
+    B { "@NumberedList" }
+    C { (1) }
+    D { "@ParenNumberedList" }
+@Rowa
+    A { i. }
+    B { "@RomanList" }
+    C { (i) }
+    D { "@ParenRomanList" }
+@Rowa
+    A { I. }
+    B { "@UCRomanList" }
+    C { (I) }
+    D { "@ParenUCRomanList" }
+@Rowa
+    A { a. }
+    B { "@AlphaList" }
+    C { (a) }
+    D { "@ParenAlphaList" }
+@Rowa
+    A { A. }
+    B { "@UCAlphaList" }
+    C { (A) }
+    D { "@ParenUCAlphaList" }
+@Rowa
+    A { @Bullet }
+    B { "@BulletList" }
+@Rowa
+    A { @Star }
+    B { "@StarList" }
+@Rowa
+    A { -- }
+    B { "@DashList" }
+}
+roman @Index { Roman numerals }
+The Roman numerals end at cc (200), but ordinary decimal numbers have
+no limit.  The labels produced by the four alphabetical list symbols are
+determined by the current language; in English they start at @Code "a"
+and end at {@Code "z"}.
+@PP
+You may also supply your own labels using the @Code "@TaggedList"
+taggedlist @Index @Code "@TaggedList"
+tl. @Index @Code "@TL"
+symbol.  Each item is introduced by @Code "@TagItem" instead of
+tagitem. @Index @Code "@TagItem"
+ti. @Index @Code "@TI"
+{@Code "@ListItem"}.  Since such labels tend to be quite wide,
+there are @Code "@WideTaggedList" and @Code "@VeryWideTaggedList" symbols
+widetaggedlist @Index @Code "@WideTaggedList"
+wtl. @Index @Code "@WTL"
+verywidetaggedlist @Index @Code "@VeryWideTaggedList"
+vwtl. @Index @Code "@VWTL"
+which leave extra space for them:
+@ID @OneRow @Code {
+"@WideTaggedList"
+"@TagItem { 9 a.m. } { Breakfast in the Ipamena Lounge,"
+"served with Irish coffee and fresh croissants. }"
+"@TagItem { 10 a.m. } { Prof. A. Smith"
+"speaks on `The Wealth of Nations.' }"
+"@EndList"
+}
+Each @Code "@TagItem" symbol is followed by the desired label between
+braces, and then the item proper.  The label may be empty, but still its
+enclosing braces must be there.  The result here is
+@ID @OneRow {
+@RawWideTaggedList
+@TagItem { 9 a.m. } { Breakfast in
+the Ipamena Lounge, served with
+Irish coffee and fresh croissants. }
+@TagItem { 10 a.m. } { Prof. A. Smith
+speaks on `The Wealth of Nations.' }
+@RawEndList
+}
+An alternative way to accommodate wide labels is the `drop item,'
+drop.item @Index { drop items }
+which looks like this:
+@ID @OneRow {
+@RawTaggedList
+@DTI { 10 a.m. } { Prof. A. Smith speaks on `The Wealth of Nations.' }
+@RawEndList
+}
+Individual items are dropped in this way by using @Code "@DropTagItem"
+drop.tag.item @Index @Code "@DropTagItem"
+dti. @Index @Code "@DTI"
+instead of {@Code "@TagItem"}.  There is also a @Code "@DropListItem"
+drop.list.item @Index @Code "@DropListItem"
+dli. @Index @Code "@DLI"
+symbol corresponding to {@Code "@ListItem"}, but it is very rarely
+needed.  Lout is not able to decide for itself whether a label is wide
+enough to require a drop item.
+@PP
+Each list has a `raw' version which omits the preceding space, and
+raw.lists @Index { raw lists }
+raw.list. @Index @Code "@RawList"
+raw.end.list. @Index @Code "@RawEndList"
+@Code "@EndList" has a raw version which omits the following
+space.  These are mainly used when an item is itself a list:
+@ID @OneRow @Code {
+"@ParenNumberedList"
+"@ListItem {"
+"   @RawParenRomanList"
+"   @ListItem { MV Nominees,"
+"hereinafter called the vendor, ... }"
+"   @RawEndList"
+"}"
+"@EndList"
+}
+produces
+@ID @OneRow {
+@RawParenNumberedList
+@ListItem {
+   @RawParenRomanList
+   @ListItem { MV Nominees,
+hereinafter called the vendor, ... }
+   @RawEndList
+}
+@RawEndList
+}
+If @Code "@ParenRomanList" had been used instead of
+{@Code "@RawParenRomanList"}, (1) and (i) would have appeared on
+different lines; or if @Code "@EndList" had been used instead of
+{@Code "@RawEndList"}, there would have been too much space following
+the list.
+@PP
+A list item may come out partly on one page or column and partly on
+the next, if it has places where it obviously can be broken in two.  For
+example, a list item which is an ordinary paragraph of text might be
+broken in two between any two lines.  To force a list item to keep
+together on one page or column, use the @Code "@OneRow" symbol like
+this:  @Code "@ListItem @OneRow { ... }".
+@PP
+Occasionally it is desirable to start a new page or column between
+two list items.  This cannot be done by inserting @Code "@NP"
+between them, because the space between two list items is a kind
+of no-man's land where nothing is allowed to be.  Instead, the
+@Code "@ListNewPage" symbol is used:  it is permitted only between
+two list items, and its effect is to make the following list item
+appear at the top of the next page or column.  It may be used within
+any kind of list.
+@PP
+Another special list item is {@Code "@ListInterruptItem"}.  This
+prints its content without any numbering or formatting:
+@ID @OneRow @Code {
+"@NumberedList"
+"@ListItem { This is the first list item. }"
+"@ListInterruptItem { This is an interruption to the list. }"
+"@ListItem { This is the second list item. }"
+"@EndList"
+}
+produces
+@ID @OneRow {
+@RawNumberedList
+@ListItem { This is the first list item. }
+@ListInterruptItem { This is an interruption to the list. }
+@ListItem { This is the second list item. }
+@RawEndList
+}
+Although @Code "@ListInterruptItem" is written like a list item, the
+result appears to be an interruption to the list.  It may be used
+in any kind of list.
+@PP
+Every symbol introduced in this section has an abbreviated form
+consisting of @Code "@" followed by its capital letters only.  For
+example, @Code "@RawNumberedList" abbreviates to {@Code "@RNL"},
+and @Code "@ListItem" to {@Code "@LI"}.  The sole exception is
+{@Code "@RawList"}, which has no abbreviation because @Code "@RL"
+is the abbreviation for {@Code "@RomanList"}.
+@PP
+list.symbol.options @Index { list symbol options }
+Expert users will be interested to learn that all of the list symbols
+described in this section are derived from the two basic ones,
+@Code "@List" and {@Code "@RawList"}, merely by setting options.  Here
+are all the options, together with their default values:
+@ID @OneRow @Code {
+"@List"
+"    type { num }"
+"    style { num }"
+"    labelwidth { 2f }"
+"    indent { 0c }"
+"    rightindent { 0c }"
+"    gap { 1v }"
+"    start { 1 }"
+}
+These options may be used with all of the list and raw list symbols,
+except that some combinations don't make sense, for example @Code "indent"
+with {@Code "@CentredList"} or @Code "style" with {@Code "@BulletList"},
+since the list symbol has clearly already set the option.
+@PP
+The @Code "type" option determines the type of numbering (Arabic, Roman,
+etc.) and is not intended for ordinary use, since there are distinct
+symbols for each type, as we have seen.  The @Code "style" option
+determines the format of the label, any @Code "num" symbol within it
+being replaced by the number (in Arabic, Roman, etc. as determined by the
+@Code "type" option) of the item.  For example, @Code "@ParenNumberedList"
+is just
+@ID @OneRow @Code {
+"@List"
+"    style { (num) }"
+}
+and @Code "@BulletList" is just
+@ID @OneRow @Code {
+"@List"
+"    style { @Bullet }"
+}
+with @Code "num" not mentioned since no number is wanted.  The
+@Code "@TaggedList" symbol and its variants also have the
+@Code "style" option; in their case, the @Code "num" symbol within
+it must be mentioned exactly once, and its value is set to produce
+the label supplied by the author.
+@PP
+The @Code "labelwidth" option determines the width set aside for the labels;
+this is where @Code "@WideTaggedList" and @Code "@VeryWideTaggedList" differ
+from {@Code "@TaggedList"}.  The @Code "indent" and @Code "rightindent"
+options determine the space left blank at the left and right margins.  The
+value given to these three options may be any length, for example
+@Code "0.5i" (half an inch), or @Code "0.5f" (half the current font
+size).  Section {@NumberOf objects} describes lengths in general.  There
+are also three useful symbols denoting lengths:  @Code "@DisplayIndent"
+is the amount by which indented and quoted displays are indented;
+@Code "@WideIndent" and @Code "@VeryWideIndent" are the indents used by
+@Code "@WideTaggedList" and {@Code "@VeryWideTaggedList"}.  Using these
+symbols helps to keep documents consistent.
+@PP
+The @Code "gap" option determines the vertical space inserted between
+items.  Once again this must be a length, although since it is
+vertical rather than horizontal, somewhat different kinds of lengths
+are appropriate:  @Code "1.5v" for 1.5 times the current vertical space
+between lines, or the default value, {@Code "@DisplayGap"}, which produces
+the amount of vertical space used before and after displays.  Owing to
+problems behind the scenes, there is no list option for the space before or after
+the list as a whole.  To change this space in one list, use a raw list and
+insert your own paragraph symbols; to change it in every list there is a
+setup file option, described below.
+@PP
+The @Code "start" option is the number assigned to the first
+item.  It must be decimal:
+@ID @OneRow @Code {
+"@ParenRomanList"
+"    start { 25 }"
+}
+looks strange, but it is the correct way to number the first
+item (xxv).
+@PP
+Here is a larger example of these options in action.  Setting both
+@Code "indent" and @Code "rightindent" to @Code "@DisplayIndent"
+produces an effect similar to {@Code "@QuotedDisplay"}:
+@ID @OneRow @Code {
+"preceding text"
+"@List"
+"    style { @I {Item num}: }"
+"    indent { @DisplayIndent }"
+"    rightindent { @DisplayIndent }"
+"    labelwidth { @WideIndent }"
+"    start { 10 }"
+"@ListItem { The vendor ... in the case of accident.  }"
+"@ListItem { The vendor ... adjacent to the facility. }"
+"@EndList"
+"following text"
+}
+The result is
+@ID @OneRow {
+preceding text
+@List
+    style { @I {Item num}: }
+    indent { @DisplayIndent }
+    rightindent { @DisplayIndent }
+    labelwidth { @WideIndent }
+    start { 10 }
+@ListItem {
+The vendor will not be liable for any injury caused by the escape of
+radiation or radioactive materials from the facility, nor for the
+costs of repair of any property damaged by nuclear blast or fallout
+in the case of accident.
+}
+@ListItem {
+The vendor will not be liable for any injury caused by radioactive
+materials being transported to or from the facility, nor for injury
+caused by radioactive materials stored adjacent to the facility.
+}
+@EndList
+following text
+}
+You can change the @I default values of the {@Code "labelwidth"},
+{@Code "indent"}, {@Code "rightindent"}, and {@Code "gap"} options,
+by setting options called {@Code "@ListTagWidth"}, {@Code "@ListIndent"},
+{@Code "@ListRightIndent"}, and {@Code "@ListGap"} in the setup
+file (Section {@NumberOf setup}).  These default values will then apply
+automatically to every list in the document unless overridden by an option,
+just as the usual default values do.  The setup file also has a
+{@Code "@ListOuterGap"} option which determines the gap before the first
+and after the last list item in non-raw lists.
+@End @Section
diff --git a/doc/user/str_marg b/doc/user/str_marg
new file mode 100644
index 0000000..0f9f75d
--- /dev/null
+++ b/doc/user/str_marg
@@ -0,0 +1,156 @@
+@Section
+   @Title { Margin notes and arbitrary placement }
+   @Tag { marginnotes }
+@Begin
+@PP
+A note can be placed in the left margin by typing
+leftnote. @Index @Code "@LeftNote"
+marginnote. @Index { margin notes }
+@ID {
+@Code "@LeftNote { A left note. }"
+@LeftNote { A left note. }
+}
+after the word that the note refers to.  The note will appear in the
+margin at the same height on the page as that word, unless that would
+cause it to overlap a previous margin note, in which case it will be
+shifted downwards (but never onto the next page).  The note may be an
+arbitrary Lout object; for example, you might type
+@ID {
+@Code "@LeftNote @I { A left note. }"
+@LeftNote @I { A left note. }
+}
+to make your note come out in italics.
+@PP
+You can get a note in the right margin by using @Code "@RightNote"
+@RightNote { A right note. }
+rightnote. @Index @Code "@RightNote"
+instead of {@Code "@LeftNote"}.  To get a note in the outer margin
+(left on even pages, right on odd pages), use {@Code "@OuterNote"};
+@OuterNote { An outer note. }
+outernote. @Index @Code "@OuterNote"
+and for the opposite, use {@Code "@InnerNote"}.
+@InnerNote { An inner note. }
+@PP
+By default, Lout produces margins that are 2.5 centimetres wide, which
+is not really enough to accommodate reasonable margin notes.  To
+change these margins, you need to change options in the setup file, as
+explained in Section {@NumberOf margins}.
+@PP
+The appearance of the margin notes themselves is also determined by
+options in the setup file (for a general introduction to setup files
+and their options, consult Section {@NumberOf setup}).  Here are
+the options and their default values:
+@ID @OneRow @Code {
+"@MarginNoteFont { 0.80f }"
+"@MarginNoteBreak { ragged 1.10fx }"
+"@MarginNoteHGap { 0.5c }"
+"@MarginNoteVGap { 1.00v }"
+"@MarginNoteWidth { 1.50c }"
+}
+@Code "@MarginNoteFont" determines the font; the default value
+produces the current font scaled to 0.8 times the current size.
+@Code "Slope 0.80f" would yield italic notes, and so
+on.  @Code "@MarginNoteBreak" is the paragraph breaking style,
+similar to the @Code "@InitialBreak" setup file option.
+@PP
+@Code "@MarginNoteHGap" determines how far away from the
+adjacent text column the margin note will appear; the default
+value is 0.5 centimetres.  @Code "@MarginNoteVGap" is the minimum
+vertical separation between margin notes (i.e. it determines how
+far downwards a note will be shifted to avoid the previous
+one).  @Code "@MarginNoteWidth" determines the width of the column
+in which margin notes (both left and right) are set; the default
+value of 1.5 centimetres is suited to the 2.5 centimetre page margins
+that are the default, but if you widen the page margins you will be
+able to increase @Code "@MarginNoteWidth" too.
+@PP
+Left notes extend into the left margin a total distance of
+@Code "@MarginNoteHGap" plus {@Code "@MarginNoteWidth"}, and it is
+up to you to make sure that this does not put them off
+the page.  Similar remarks apply to right notes.  And since notes
+are never shifted to the next page, only downwards, there is also
+a risk that a note will be shifted off the bottom of the page, if
+it is very long or if preceding notes obstruct it.  Again, it is
+up to you to avoid this problem by keeping your notes small and not
+too close together.
+@PP
+Margin notes inside footnotes, figures and tables work well.  Margin
+notes in multi-column documents are disastrous unless used very
+sparingly.  Margin notes do not appear in plain text output
+(Section {@NumberOf plain}).
+@PP
+A more radical way to place objects at arbitrary points on the current
+place. @Index @Code "@Place"
+page is provided by the @Code "@Place" symbol:
+@ID @OneRow @Code {
+"@Place"
+"    x { right - 1 cm - xsize }"
+"    y { { foot + top } / 2 }"
+"{"
+"    @Box { Hello }"
+"}"
+}
+The placed object may be any object.  This particular example produces a
+box whose @I x (horizontal) position is such that its right edge is one
+centimetre from the right edge of the page, and whose @I y (vertical)
+position is halfway up &
+@Place
+    x { right - 1 cm - xsize }
+    y { { foot + top } / 2 }
+{
+    @Box { Hello }
+}
+the page.
+@PP
+In addition to numbers, Lout lengths (Section {@NumberOf objects}),
+and Diag lengths (Section {@NumberOf dia_summ}), the following symbols
+may be used inside the @Code "x" and @Code "y" options:
+@ID @Tab
+    @Fmta { @Col @Code A ! @Col B }
+{
+@Rowa
+    A { left }
+    B { The left edge of the page }
+@Rowa
+    A { right }
+    B { The right edge of the page }
+@Rowa
+    A { foot }
+    B { The foot edge of the page }
+@Rowa
+    A { top }
+    B { The top edge of the page }
+@Rowa
+    A { "+" }
+    B { Addition (positive is to the right and up) }
+@Rowa
+    A { "-" }
+    B { Subtraction (negative is to the left and down) }
+@Rowa
+    A { "*" }
+    B { Multiplication }
+@Rowa
+    A { "/" }
+    B { Division }
+@Rowa
+    A { "xsize" }
+    B { The width of the object being placed }
+@Rowa
+    A { "xmark" }
+    B { The column mark of the object being placed (for expert users) }
+@Rowa
+    A { "ysize" }
+    B { The height of the object being placed }
+@Rowa
+    A { "ymark" }
+    B { The row mark of the object being placed (for expert users) }
+}
+The usual precedences and associativities apply to the mathematical
+operators; braces (not parentheses) may be used for grouping.  It is
+best to give values to @Code "x" and @Code y that do not depend on
+any assumptions about where the coordinate system's origin is; this
+is true of the examples above.  At the point where @Code "@Place" occurs,
+the result is an empty object.  As with margin notes, Lout does not know
+what is happening and will not lay out the rest of the page around the
+placed object.
+@End @Section
diff --git a/doc/user/str_theo b/doc/user/str_theo
new file mode 100644
index 0000000..5d85c37
--- /dev/null
+++ b/doc/user/str_theo
@@ -0,0 +1,108 @@
+@Section
+   @Title { Theorems, lemmas, corollaries, definitions, propositions,
+examples, and claims }
+   @RunningTitle { Theorems, lemmas, etc. }
+   @Tag { theorems }
+@Begin
+@PP
+theorem. @Index @Code "@Theorem"
+A theorem is created like this:
+@ID @OneRow @Code {
+"@LD @Theorem"
+"    @Title { Fermat's Last Theorem }"
+"{"
+"@Eq { a sup n + b sup n != c sup n } for all positive integers @Eq { a },"
+"@Eq { b }, @Eq { c } and @Eq { n } when @Eq { n > 2 }."
+"@LP"
+"@Proof I have a proof of this theorem, but the margin"
+"is too small to contain it. @EndProof"
+"}"
+}
+where we have used the @Code "@LD" `left display' symbol from
+Section {@NumberOf displays} to get a left-justified display,
+and the @Code "@Eq" symbol from Chapter {@NumberOf equations}
+for the equations.  The result is
+@ID @Theorem
+    @Title { Fermat's Last Theorem }
+{
+@Eq { a sup n + b sup n != c sup n } for all positive integers @Eq { a },
+@Eq { b }, @Eq { c } and @Eq { n } when @Eq { n > 2 }.
+@LP
+@Proof I have a proof of this theorem, but the margin
+is too small to contain it. @EndProof
+}
+The @Code "@Theorem" symbol produces an object with no adjacent
+vertical space, hence it needs to be used in conjuction with
+display or paragraph symbols.  The theorem is numbered automatically,
+with the title and number inserted at the start of the first
+paragraph.  @Code "@Title" may be omitted.
+@PP
+@Code "@Proof" produces @Proof @Null
+proof. @Index @Code "@Proof"
+with the appropriate following space, and @Code "@EndProof" produces
+endproof. @Index @Code "@EndProof"
+a box at the end of the line.  They may be used anywhere, not
+just within theorems.
+@FootNote { Occasionally @Code "@EndProof" does not
+appear as far to the right as it should.  This problem can be fixed by using
+{@Code "@LD @HExpand @Theorem"}, which instructs Lout to make sure
+that as much horizontal space as possible is allocated to the theorem. }
+@PP
+There are seven symbols that produce independently numbered sequences
+in this way.  They are {@Code "@Theorem"}, {@Code "@Definition"},
+definition. @Index @Code "@Definition"
+claim. @Index @Code "@Claim"
+proposition. @Index @Code "@Proposition"
+lemma. @Index @Code "@Lemma"
+corollary. @Index @Code "@Corollary"
+example. @Index @Code "@Example"
+{@Code "@Claim"}, {@Code "@Proposition"}, {@Code "@Lemma"},
+{@Code "@Corollary"}, and {@Code "@Example"}.
+@PP
+The setup file contains options which determine whether the theorem
+numbers include a chapter number ({@Code "@ChapterNumInTheorems"}),
+or a section number ({@Code "@SectionNumInTheorems"}), and so on.  A
+section number automatically includes a chapter number, etc.  There
+are also options to change the word printed.  For example, if you
+need a sequence of conjectures, change the @Code "@ClaimWord" setup
+file option to
+@ID @Code "@ClaimWord { Conjecture }"
+and use the @Code "@Claim" symbol for your conjectures.  You can even put
+@ID @Code {
+"import @DocumentSetup"
+"macro @Conjecture { @Claim }"
+}
+into your @Code mydefs file (Section {@NumberOf definitions}) if you wish,
+so that you can write @Code "@Conjecture" in your documents instead of
+{@Code "@Claim"}.
+@PP
+The setup file also contains two options which control the format of
+the theorem (claims and so on have corresponding options).  Here they
+are with their default values:
+@ID @Code {
+"@TheoremTitleFormat { (title) }"
+"@TheoremFormat { { @B { word @NumSep number title: } &2s } @Insert body }"
+}
+The first option is used only when a @Code "@Title" is given to the
+theorem, and it determines how the title is formatted:  the @Code title
+symbol within the option stands for the @Code "@Title" option.  The default
+value shown places parentheses around the title.  The second option
+determines the format of the entire theorem.  Within it, @Code word
+stands for the value of {@Code "@TheoremWord"};
+@Code "number" is the number of the theorem; @Code "title" is the title
+of the theorem after formatting by {@Code "@TheoremFormat"} (if there
+is a title; otherwise @Code title is {@Code "@Null"}, which prints as
+nothing and even deletes the preceding space as required); and
+@Code body is the body of the theorem.  The default value prints the
+word, number and title with a colon in bold, and inserts them and two
+spaces into the first paragraph of the body; another value might be
+@ID @Code { "@TheoremFormat { @B { word @NumSep number title } @LP body }" }
+which places the header in bold on a line by itself, separated from the
+body by a paragraph break.  For @Code "@NumSep" see page {@PageOf numsep}.
+@PP
+Owing to problems behind the scenes, the @Code "@Theorem" symbol and its
+companions have a potential efficiency problem:  although all numbers are
+finalized on the second run, it takes Lout time proportional to the square
+of the highest theorem number to do this.  So large numbers of theorems
+numbered together might be slow.
+@End @Section
diff --git a/doc/user/su_crest.eps b/doc/user/su_crest.eps
new file mode 100644
index 0000000..95bc0f9
--- /dev/null
+++ b/doc/user/su_crest.eps
@@ -0,0 +1,1156 @@
+%!PS-Adobe-3.0 EPSF-3.0
+%%BoundingBox: 0 0 60 53
+%%Pages: 1
+%%Title: Crest for The University of Sydney
+%%Creator: jaa@cs.su.oz.au encapsulated by rex@cs.su.oz.au
+%%+ Converted for colour and bug fixes by Rex.
+%%CreationDate: Wed May 13 18:02:34 EST 1992
+%%+ Converted for colour: Tue Jul 7 20:06:30 EST 1992
+%%DocumentNeededResources: font Times-Bold
+%%EndComments
+%%BeginProlog
+%%EndProlog
+%%BeginSetup
+%%EndSetup
+
+% PMS colours
+% red  - 185
+% blue - 286
+% gold - 871
+gsave
+.01 dup scale
+-1988 -1050 translate
+/colour 1 def		% set to one if colour
+/pathtextdict 27 dict def
+
+/pathtext
+ { pathtextdict begin
+   /spacing exch def
+   /offset exch def
+   /str exch def
+   /pathdist 0 def
+   /offset offset str 0 1 getinterval stringwidth pop 2 div add def
+   /setdist offset def
+   /charcount 0 def
+   gsave flattenpath
+   {movetoproc} {linetoproc} {} {closepathproc} pathforall
+   grestore
+   newpath
+   end } def
+
+pathtextdict begin
+
+/movetoproc
+ { /newy exch def /newx exch def
+   /firstx newx def /firsty newy def
+   /ovr setdist pathdist sub def
+   newx newy transform
+   /cpy exch def /cpx exch def } def
+
+/linetoproc
+ { /oldx newx def /oldy newy def
+   /newy exch def /newx exch def
+   /dx newx oldx sub def
+   /dy newy oldy sub def
+   /dist dx dup mul dy dup mul add sqrt def
+   dist 0 ne
+    { /dsx dx dist div ovr mul def
+      /dsy dy dist div ovr mul def
+      oldx dsx add oldy dsy add transform
+      /cpy exch def /cpx exch def
+      /pathdist pathdist dist add def
+       { setdist pathdist le
+	 { charcount str length lt
+	    {setchar} {exit} ifelse }
+	 { /ovr setdist pathdist sub def
+	   exit }
+         ifelse } loop } if } def
+
+/closepathproc
+ { firstx firsty linetoproc
+   firstx firsty movetoproc } def
+
+/setchar
+ { /char str charcount 1 getinterval def
+   /charcount charcount 1 add def
+   /charwidth char stringwidth pop def
+   gsave
+      cpx cpy itransform translate
+      dy dx atan rotate
+      charwidth -2 div 0 moveto char show
+      /charwidth str length charcount gt
+	{ str charcount 1 getinterval stringwidth pop }
+	{ 0 } ifelse charwidth add 2 div def
+      charwidth 0 moveto
+      currentpoint transform
+      /cpy exch def /cpx exch def
+   grestore
+   /setdist setdist charwidth spacing add add def } def
+end
+/gold_colour {
+	colour 0 ne
+	{ 0.9453 0.6206 0.004 setrgbcolor }
+	{ 1 setgray }
+	ifelse
+} def
+/blue_colour {
+	colour 0 ne
+%	{ 0.0 0.0 0.0 setrgbcolor }
+%	{ 1.0 1.0 1.0 setrgbcolor }
+	{ 0.0599 0.0526 0.5493 setrgbcolor }
+	{ 1 setgray }
+	ifelse
+} def
+/red_colour {
+	colour 0 ne
+	{ 0.9375 0.0 0.0 setrgbcolor }
+	{ 1 setgray }
+	ifelse
+} def
+/c { curveto } def
+/m { moveto } def
+/l { lineto } def
+
+/sym1 { 5000 1939 m
+4974 2006 4971 2065 4924 2119 c
+4909 2137 4893 2152 4870 2153 c
+4845 2154 4824 2141 4811 2120 c
+4791 2089 4771 2068 4740 2047 c
+4722 2079 4713 2105 4706 2141 c
+4659 2111 4624 2091 4580 2057 c
+4555 2116 4561 2178 4597 2232 c
+4570 2236 4551 2242 4525 2242 c
+4543 2280 4564 2305 4598 2329 c
+4572 2345 4553 2358 4528 2375 c
+4432 2284 4332 2235 4201 2226 c
+3989 2210 3846 2323 3636 2356 c
+3596 2363 3565 2353 3525 2362 c
+3478 2372 3444 2415 3441 2463 c
+3358 2444 3304 2395 3250 2329 c
+3222 2365 3205 2402 3211 2447 c
+3179 2445 3148 2437 3135 2408 c
+3122 2378 3135 2351 3144 2320 c
+3092 2351 3046 2396 3050 2457 c
+3053 2509 3097 2544 3146 2563 c
+3104 2574 3073 2584 3030 2587 c
+3053 2628 3079 2655 3119 2679 c
+3070 2703 3031 2726 3003 2773 c
+3033 2798 3059 2811 3095 2827 c
+3062 2842 3035 2852 2999 2850 c
+2961 2846 2934 2826 2909 2798 c
+2897 2844 2904 2890 2936 2925 c
+2999 2992 3096 2968 3185 2949 c
+3143 3062 3116 3145 3080 3260 c
+3056 3248 3037 3240 3012 3228 c
+3009 3255 3008 3275 3004 3303 c
+2954 3263 2914 3228 2851 3218 c
+2792 3210 2733 3215 2694 3260 c
+2657 3302 2652 3361 2676 3411 c
+2698 3457 2745 3480 2796 3479 c
+2848 3478 2888 3433 2900 3382 c
+2976 3532 2884 3672 2865 3839 c
+2853 3951 2882 4059 2972 4127 c
+3035 4175 3120 4184 3186 4141 c
+3233 4110 3249 4047 3232 3993 c
+3306 4030 3338 4126 3312 4204 c
+3286 4278 3221 4333 3143 4334 c
+3082 4335 3030 4290 3012 4231 c
+2987 4270 2970 4307 2979 4352 c
+2991 4411 3040 4445 3096 4466 c
+3052 4496 3012 4518 2959 4515 c
+2915 4512 2887 4486 2857 4455 c
+2857 4526 2870 4594 2928 4636 c } def
+/sym2 { 3004 4693 3106 4680 3188 4630 c
+3195 4668 3210 4699 3241 4721 c
+3280 4749 3325 4751 3370 4734 c
+3324 4681 3347 4603 3386 4544 c
+3428 4480 3447 4422 3454 4346 c
+3491 4560 3479 4786 3309 4922 c
+3309 4871 3298 4821 3255 4794 c
+3200 4760 3143 4771 3080 4784 c
+2987 4804 2933 4885 2837 4880 c
+2806 4878 2771 4868 2762 4837 c
+2750 4800 2777 4768 2801 4737 c
+2736 4747 2662 4782 2659 4848 c
+2657 4904 2696 4947 2744 4976 c
+2706 4986 2676 4992 2637 4986 c
+2650 5022 2666 5051 2700 5067 c
+2751 5090 2798 5075 2851 5060 c
+2854 5126 2881 5190 2942 5213 c
+2997 5235 3049 5211 3099 5180 c
+3043 5175 2983 5150 2972 5095 c
+2960 5029 2985 4969 3033 4922 c
+3045 4972 3068 5004 3102 5043 c
+3175 5126 3245 5203 3235 5313 c
+3228 5402 3182 5463 3122 5528 c
+3096 5557 3073 5580 3067 5618 c
+3059 5671 3076 5722 3118 5756 c
+3174 5801 3245 5811 3313 5787 c
+3350 5775 3378 5745 3382 5707 c
+3387 5660 3355 5625 3320 5594 c
+3378 5596 3424 5615 3465 5657 c
+3488 5680 3500 5709 3492 5741 c
+3479 5789 3422 5808 3372 5807 c
+3398 5849 3436 5877 3485 5879 c
+3540 5881 3582 5851 3621 5812 c
+3626 5868 3617 5910 3633 5965 c
+3647 6015 3678 6046 3720 6077 c
+3728 6032 3736 5996 3761 5957 c
+3793 6007 3828 6041 3883 6062 c
+3939 6083 3991 6081 4047 6060 c
+3996 6024 3964 5988 3935 5934 c
+3967 5942 3991 5948 4021 5962 c
+4016 5935 4014 5915 4008 5889 c
+4103 5911 4184 5919 4273 5880 c
+4323 5858 4354 5820 4374 5768 c
+4396 5801 4407 5829 4419 5867 c
+4426 5890 4435 5908 4453 5924 c
+4487 5953 4511 5975 4544 6004 c
+4556 5978 4563 5960 4575 5935 c
+4629 5971 4670 5993 4721 6033 c
+4730 5997 4739 5972 4751 5937 c
+4775 5951 4795 5964 4806 5990 c
+4816 6013 4815 6039 4797 6057 c
+4771 6083 4733 6075 4696 6068 c
+4704 6112 4719 6149 4757 6172 c
+4799 6198 4847 6189 4892 6169 c
+4896 6198 4905 6220 4923 6243 c
+4942 6267 4969 6275 5000 6276 c
+closepath  0 setgray fill } def
+/sym3 { 5000 6214 m
+4943 6214 4937 6122 4950 6067 c
+4900 6113 4830 6146 4770 6114 c
+4809 6102 4847 6083 4855 6044 c
+4876 5953 4780 5890 4699 5844 c
+4690 5859 4685 5870 4676 5885 c
+4687 5894 4695 5900 4705 5908 c
+4700 5925 4697 5938 4692 5955 c
+4663 5938 4642 5927 4615 5910 c
+4588 5893 4579 5868 4565 5840 c
+4549 5838 4538 5837 4522 5836 c
+4531 5867 4536 5892 4530 5924 c
+4495 5894 4471 5865 4457 5821 c
+4444 5776 4425 5744 4391 5712 c
+4388 5697 4383 5687 4376 5673 c
+4469 5733 4547 5769 4656 5786 c
+4818 5811 4930 5924 5000 6072 c
+closepath gold_colour fill
+5000 2189 m
+4938 2287 4857 2343 4746 2376 c
+4678 2396 4629 2419 4570 2459 c
+4567 2441 4563 2427 4557 2410 c
+4614 2373 4657 2348 4717 2315 c
+4676 2303 4642 2301 4606 2277 c
+4637 2276 4659 2271 4688 2262 c
+4643 2233 4615 2195 4602 2143 c
+4652 2176 4692 2196 4748 2215 c
+4749 2183 4753 2160 4763 2130 c
+4787 2168 4816 2203 4861 2204 c
+4925 2205 4976 2156 5000 2096 c
+closepath gold_colour fill
+4392 2432 m
+4408 2444 4419 2476 4402 2484 c
+4390 2489 4373 2482 4371 2469 c
+4368 2450 4354 2439 4337 2430 c
+4322 2422 4305 2425 4292 2436 c
+4269 2456 4267 2491 4281 2518 c
+4302 2562 4346 2582 4395 2588 c
+4443 2593 4494 2578 4515 2534 c
+4533 2497 4520 2455 4494 2422 c
+4429 2336 4347 2292 4241 2272 c
+4078 2243 3955 2308 3798 2362 c
+3712 2391 3644 2402 3552 2403 c
+3526 2403 3502 2415 3489 2438 c } def
+/sym4 { 3478 2458 3480 2484 3496 2500 c
+3511 2515 3533 2519 3552 2510 c
+3577 2498 3586 2477 3603 2454 c
+3616 2466 3627 2472 3641 2482 c
+3611 2524 3575 2566 3524 2561 c
+3489 2558 3459 2538 3448 2505 c
+3371 2498 3317 2460 3262 2407 c
+3251 2431 3260 2453 3265 2479 c
+3203 2492 3143 2480 3097 2436 c
+3096 2455 3095 2471 3107 2487 c
+3142 2535 3198 2539 3256 2554 c
+3211 2591 3168 2607 3111 2619 c
+3127 2634 3139 2645 3158 2654 c
+3250 2647 3315 2628 3406 2609 c
+3408 2621 3408 2631 3410 2643 c
+3340 2669 3285 2680 3211 2689 c
+3152 2696 3112 2723 3063 2756 c
+3103 2781 3140 2795 3187 2788 c
+3134 2861 3054 2899 2965 2890 c
+3045 2966 3170 2921 3265 2864 c
+3251 2897 3248 2926 3254 2962 c
+3340 2893 3343 2793 3410 2707 c
+3422 2716 3431 2723 3443 2732 c
+3372 2844 3351 2965 3233 3026 c
+3227 3016 3223 3008 3218 2997 c
+3175 3107 3141 3187 3116 3302 c
+3124 3313 3128 3322 3135 3333 c
+3160 3280 3179 3241 3192 3184 c
+3252 3221 3277 3279 3291 3349 c
+3355 3062 3431 2842 3621 2618 c
+3809 2396 4163 2253 4392 2432 c
+closepath gold_colour fill
+3039 4863 m
+2983 4908 2943 4954 2927 5024 c
+2915 5080 2929 5128 2960 5175 c
+2899 5138 2888 5055 2909 4986 c
+2847 5018 2791 5045 2724 5028 c
+2766 5018 2795 4995 2820 4959 c
+2781 4942 2744 4934 2720 4898 c
+2705 4875 2705 4845 2720 4822 c
+2727 4875 2775 4915 2829 4920 c
+2912 4928 2966 4873 3045 4844 c
+3043 4851 3042 4856 3039 4863 c
+closepath gold_colour } def
+/sym5 { 3771 5716 m
+3765 5719 3760 5721 3754 5724 c
+3770 5759 3789 5787 3823 5803 c
+3878 5829 3926 5846 3959 5896 c
+3928 5887 3906 5879 3877 5866 c
+3878 5934 3908 5984 3952 6036 c
+3868 6021 3814 5962 3770 5888 c
+3735 5918 3714 5947 3698 5990 c
+3657 5925 3671 5860 3657 5785 c
+3646 5724 3605 5682 3549 5656 c
+3576 5689 3603 5723 3592 5765 c
+3578 5817 3517 5835 3463 5835 c
+3513 5807 3554 5753 3539 5697 c
+3504 5571 3311 5510 3202 5581 c
+3175 5599 3155 5628 3162 5659 c
+3170 5697 3216 5709 3255 5709 c
+3264 5709 3272 5699 3272 5690 c
+3272 5682 3266 5673 3258 5672 c
+3242 5672 3219 5667 3219 5650 c
+3219 5634 3234 5620 3250 5619 c
+3283 5618 3311 5638 3327 5667 c
+3340 5692 3331 5728 3306 5741 c
+3261 5764 3210 5761 3167 5733 c
+3130 5710 3107 5670 3114 5627 c
+3125 5558 3186 5514 3254 5498 c
+3369 5471 3464 5510 3568 5565 c
+3734 5651 3855 5715 4032 5775 c
+4106 5801 4192 5825 4246 5767 c
+4264 5748 4269 5713 4249 5695 c
+4238 5684 4222 5684 4207 5688 c
+4197 5690 4189 5710 4198 5714 c
+4205 5717 4213 5722 4212 5729 c
+4210 5738 4203 5742 4196 5747 c
+4180 5756 4160 5757 4145 5747 c
+4128 5736 4119 5718 4119 5698 c
+4119 5657 4151 5616 4192 5612 c
+4242 5608 4293 5626 4316 5670 c
+4339 5715 4335 5769 4301 5806 c
+4259 5852 4200 5860 4138 5854 c
+4067 5848 4018 5824 3948 5818 c
+3890 5771 3825 5768 3771 5716 c
+closepath gold_colour fill
+3351 3504 m
+3316 3561 3252 3571 3187 3584 c
+3110 3600 3060 3641 3004 3697 c
+3016 3707 3025 3713 3037 3724 c
+3101 3660 3167 3625 3257 3613 c
+3312 3606 3361 3640 3388 3688 c
+3411 3731 3408 3781 3382 3822 c
+3364 3849 3334 3858 3302 3859 c
+3271 3861 3242 3842 3231 3813 c
+3222 3791 3221 3763 3240 3749 c
+3253 3739 3284 3740 3285 3757 c
+3286 3768 3301 3773 3312 3771 c
+3322 3769 3329 3757 3326 3747 c
+3322 3727 3305 3714 3284 3708 c
+3256 3700 3230 3704 3203 3718 c
+3115 3764 3064 3837 3037 3933 c
+3113 3879 3205 3865 3289 3905 c
+3595 4053 3667 4488 3532 4801 c
+3477 4929 3390 5011 3265 5073 c
+3297 5102 3328 5121 3371 5123 c } def
+/sym6 { 3413 5125 3443 5105 3479 5084 c
+3476 5132 3466 5167 3451 5214 c
+3527 5188 3578 5153 3638 5100 c
+3632 5179 3602 5235 3556 5299 c
+3590 5327 3613 5351 3634 5389 c
+3530 5370 3412 5363 3351 5450 c
+3310 5451 3280 5452 3240 5461 c
+3287 5354 3297 5242 3236 5142 c
+3194 5074 3147 5036 3101 4970 c
+3075 4931 3081 4876 3115 4844 c
+3144 4817 3187 4810 3223 4827 c
+3260 4844 3270 4889 3265 4928 c
+3262 4944 3246 4954 3230 4952 c
+3215 4951 3195 4943 3196 4927 c
+3198 4910 3191 4886 3174 4887 c
+3140 4888 3147 4960 3174 4980 c
+3197 4996 3221 5002 3248 4995 c
+3457 4941 3527 4682 3509 4467 c
+3501 4375 3484 4302 3429 4228 c
+3414 4238 3403 4244 3389 4254 c
+3422 4339 3411 4425 3360 4500 c
+3318 4562 3278 4620 3293 4695 c
+3239 4664 3226 4599 3234 4538 c
+3175 4590 3117 4626 3039 4626 c
+2987 4625 2949 4593 2920 4550 c
+3017 4578 3119 4523 3169 4436 c
+3099 4425 3027 4388 3017 4318 c
+3072 4363 3134 4389 3203 4373 c
+3269 4357 3316 4315 3344 4253 c
+3384 4164 3381 4054 3308 3990 c
+3269 3956 3220 3939 3171 3956 c
+3138 3948 3102 3956 3083 3984 c
+3070 4003 3072 4027 3084 4047 c
+3094 4064 3113 4077 3132 4073 c
+3145 4070 3154 4057 3153 4044 c
+3152 4035 3146 4027 3137 4025 c
+3130 4024 3125 4024 3119 4026 c
+3114 4015 3122 4001 3134 3997 c
+3152 3992 3170 4004 3181 4019 c
+3192 4037 3190 4058 3182 4078 c
+3173 4098 3158 4113 3137 4118 c
+3063 4138 2984 4100 2947 4034 c
+2887 3928 2905 3819 2938 3702 c
+2978 3561 2993 3351 2852 3312 c
+2826 3305 2798 3300 2778 3318 c
+2760 3335 2756 3368 2774 3386 c
+2782 3395 2797 3400 2806 3392 c
+2813 3385 2815 3372 2808 3364 c
+2804 3358 2809 3347 2816 3347 c
+2833 3346 2851 3352 2857 3367 c
+2865 3390 2850 3414 2830 3427 c
+2803 3444 2768 3445 2742 3426 c
+2715 3406 2703 3372 2710 3338 c
+2719 3293 2759 3258 2805 3257 c
+2904 3254 2972 3321 3034 3397 c
+3040 3365 3047 3342 3053 3310 c
+3088 3343 3108 3375 3125 3420 c
+3173 3371 3193 3321 3214 3256 c
+3249 3322 3255 3386 3240 3459 c
+3283 3440 3321 3428 3368 3437 c
+3376 3438 3379 3449 3376 3457 c
+3370 3475 3361 3487 3351 3504 c
+closepath gold_colour fill } def
+
+/sym7 {
+%main interior
+5000 2313 m
+4955 2385 4880 2430 4730 2470 c
+4670 2490 4630 2538 4621 2553 c
+4641 2530 4630 2538 4621 2553 c
+4585 2613 4538 2650 4472 2670 c
+4397 2694 4326 2682 4259 2639 c
+4193 2598 4169 2523 4172 2445 c
+3789 2440 3543 2822 3392 3344 c
+3431 3350 3458 3359 3495 3371 c
+3490 3425 3475 3465 3415 3578 c
+3530 3685 3540 3805 3441 3896 c
+3632 4058 3686 4286 3678 4536 c
+3673 4730 3650 4830 3573 4935 c
+3573 5041 l
+3596 5023 3630 4992 3667 4942 c
+3740 5075 3732 5205 3670 5295 c
+3713 5352 3745 5410 3780 5495 c
+3692 5468 3608 5445 3533 5440 c
+4026 5680 l
+4040 5593 4125 5530 4250 5530 c
+4310 5530 4415 5580 4453 5616 c
+4514 5658 4607 5693 4661 5699 c
+4823 5717 4930 5780 5000 5890 c
+closepath  1 setgray fill } def
+/sym8 {
+% Banner outside
+5000 1556 m
+4862 1556 4759 1613 4651 1699 c
+4509 1814 4423 1918 4279 2033 c
+4149 2137 4015 2173 3848 2182 c
+3697 2189 3587 2175 3436 2165 c
+3273 2154 3136 2138 2993 2218 c
+2923 2257 2875 2297 2823 2359 c
+2818 2365 2826 2373 2832 2378 c
+2864 2398 2887 2412 2919 2433 c
+2954 2455 2947 2512 2922 2545 c
+2881 2600 2850 2641 2823 2703 c
+2793 2771 2795 2830 2758 2894 c
+2745 2916 2720 2935 2696 2927 c
+2647 2911 2610 2902 2561 2886 c
+2557 2885 2552 2889 2550 2894 c
+2530 2941 2515 2976 2502 3027 c
+2500 3032 2505 3038 2510 3040 c
+2546 3054 2573 3062 2609 3075 c
+2626 3081 2638 3091 2645 3108 c
+2652 3125 2651 3142 2643 3159 c
+2619 3213 2586 3244 2561 3297 c
+2538 3350 2530 3393 2511 3448 c
+2500 3481 2452 3494 2421 3478 c
+2291 3413 2194 3370 2064 3305 c
+2034 3289 2015 3267 2004 3236 c
+1988 3194 2014 3153 2048 3124 c
+2053 3119 2059 3111 2065 3115 c
+2075 3120 2082 3124 2092 3130 c
+2102 3135 2116 3133 2121 3123 c
+2134 3092 2150 3073 2169 3046 c
+2174 3040 2177 3030 2171 3026 c
+2144 3007 2124 2995 2097 2977 c
+2081 2966 2072 2948 2074 2928 c
+2078 2872 2082 2830 2101 2778 c
+2125 2717 2157 2677 2203 2631 c
+2210 2624 2219 2620 2228 2623 c
+2254 2631 2274 2637 2300 2646 c
+2307 2648 2315 2644 2318 2638 c
+2330 2616 2332 2597 2339 2574 c
+2340 2568 2336 2562 2330 2558 c
+2303 2539 2280 2531 2251 2515 c
+2240 2509 2234 2497 2237 2484 c
+2293 2264 2369 2102 2522 1934 c
+2640 1804 2769 1740 2940 1699 c
+3122 1655 3264 1689 3451 1705 c
+3631 1720 3776 1743 3942 1673 c
+4083 1613 4148 1508 4263 1408 c
+4485 1215 4706 1090 5000 1090 c
+closepath  0 setgray fill } def
+
+/sym9 { 5000 1502 m
+4722 1503 4558 1710 4353 1898 c
+4199 2039 4042 2129 3833 2132 c
+3632 2136 3486 2109 3286 2101 c
+3149 2096 3040 2122 2923 2194 c
+2745 2303 2674 2468 2599 2664 c
+2500 2600 2426 2557 2324 2497 c
+2385 2294 2456 2143 2606 1994 c
+2761 1838 2945 1768 3165 1777 c
+3357 1784 3497 1797 3689 1807 c
+3873 1817 4023 1758 4161 1638 c
+4301 1516 4393 1411 4554 1319 c
+4703 1234 4828 1178 5000 1177 c
+closepath  1 setgray fill
+2660 2661 m
+2695 2563 2727 2492 2784 2405 c
+2798 2413 2808 2420 2822 2430 c
+2771 2508 2758 2578 2721 2663 c
+2712 2683 2692 2706 2671 2697 c
+2658 2692 2655 2674 2660 2661 c
+closepath  1 setgray fill
+2608 2857 m
+2597 2853 2589 2851 2577 2847 c
+2586 2839 2592 2833 2602 2826 c
+2606 2837 2606 2846 2608 2857 c
+closepath  1 setgray fill
+2390 2680 m
+2403 2655 2407 2634 2412 2607 c
+2482 2651 2535 2679 2607 2721 c
+2633 2736 2659 2747 2688 2739 c
+2726 2728 2751 2702 2766 2665 c
+2795 2595 2806 2539 2845 2474 c
+2853 2460 2869 2447 2883 2454 c
+2901 2463 2894 2490 2885 2508 c
+2851 2572 2813 2612 2784 2679 c
+2758 2740 2752 2789 2729 2851 c
+2722 2870 2709 2890 2689 2888 c
+2670 2887 2663 2864 2662 2845 c
+2660 2803 2625 2773 2586 2757 c
+2514 2728 2462 2707 2390 2680 c
+closepath  1 setgray fill
+2481 3136 m
+2479 3113 2479 3094 2486 3072 c
+2500 3078 2510 3082 2524 3088 c
+2512 3108 2500 3121 2481 3136 c
+closepath  1 setgray fill } def
+/syma { 
+2429 3113 m
+2333 3058 2261 3021 2166 2965 c
+2173 2856 2202 2775 2261 2684 c
+2368 2725 2447 2754 2553 2799 c
+2482 2901 2455 2992 2429 3113 c
+closepath  1 setgray fill
+2472 3422 m
+2469 3434 2457 3445 2445 3441 c
+2434 3436 2427 3423 2430 3411 c
+2438 3381 2452 3362 2471 3338 c
+2373 3280 2300 3241 2200 3186 c
+2219 3144 2234 3114 2259 3077 c
+2326 3114 2374 3141 2441 3178 c
+2466 3191 2497 3200 2518 3182 c
+2549 3156 2567 3134 2593 3105 c
+2600 3136 2599 3166 2579 3190 c
+2552 3224 2532 3250 2514 3289 c
+2493 3336 2484 3372 2472 3422 c
+closepath  1 setgray fill
+2380 3392 m
+2379 3400 2368 3406 2361 3402 c
+2269 3354 2202 3321 2112 3270 c
+2093 3260 2096 3233 2102 3212 c
+2103 3210 2105 3206 2107 3208 c
+2210 3264 2288 3301 2391 3358 c
+2386 3370 2383 3380 2380 3392 c
+closepath  1 setgray fill } def
+/symb_colour {
+% cross in 'azure' blue
+blue_colour 
+5000 2313 m
+4955 2385 4880 2430 4730 2470 c
+4670 2490 l
+4670 3220 l
+3430 3220 l
+3392 3344 l
+3431 3350 3458 3359 3495 3371 c
+3490 3425 3475 3465 3415 3578 c
+3530 3685 3500 3805 3490 3813 c
+4670 3813 l
+4670 4582 l
+5000 4582 l
+closepath fill
+% Chief Gules
+red_colour 
+5000 4582 m
+3675 4582 l
+3673 4730 3650 4830 3573 4935 c
+3573 5041 l
+3596 5023 3630 4992 3667 4942 c
+3740 5075 3732 5205 3670 5295 c
+3713 5352 3745 5410 3780 5495 c
+3692 5468 3608 5445 3533 5440 c
+4026 5680 l
+4040 5593 4125 5530 4250 5530 c
+4310 5530 4415 5580 4453 5616 c
+4514 5658 4607 5693 4661 5699 c
+4823 5717 4930 5780 5000 5890 c
+closepath fill
+% and now some lines around the cross, and at the base of the lion field
+0 setgray
+16 setlinewidth
+3675 4582 m 5000 4582 l stroke
+3490 3813 m 4670 3813 l 4670 4582 l stroke
+3430 3220 m 4670 3220 l 4670 2490 l stroke
+} def
+/book_clasp {
+2 copy
+gold_colour 
+m
+50 0 rlineto
+0 50 rlineto
+-50 0 rlineto
+closepath fill
+2 copy
+0 setgray
+m
+50 0 rlineto
+stroke
+m
+0 50 rmoveto
+50 0 rlineto
+stroke
+} def
+/sym_book {
+% Book outline
+% First fill the outline
+1 setgray
+5000 3742 m
+4856 3798 4755 3804 4671 3700 c
+4671 3325 l
+5329 3325 l
+5329 3700 l
+5245 3804 5144 3798 5000 3742 c
+closepath fill
+% along the base of the book colour it gold
+gold_colour 
+5329 3315 m
+5227 3420 5114 3413 5000 3363 c
+4886 3413 4773 3420 4671 3315 c 
+closepath fill
+% Clasps for the book
+% Firstly colour the clasps gold
+gold_colour 
+8 setlinewidth
+4671 3355 m
+4611 3355 l
+4611 3700 l
+4671 3700 l
+closepath
+gsave
+fill
+grestore
+0 setgray
+stroke
+% and strokes on the clasp holder
+3412 58 3644 { dup 4611 exch m 4671 exch l stroke } for
+4671 3300 m 4671 3700 l stroke
+% Now do the three book clasps
+5329 3400 book_clasp
+5329 3500 book_clasp
+5329 3600 book_clasp
+% then actually draw the book in black
+16 setlinewidth
+0 setgray
+5000 3742 m
+5000 3363 l
+4886 3413 4773 3420 4671 3315 c 
+4671 3700 l
+4755 3804 4856 3798 5000 3742 c
+closepath stroke
+5329 3700 m
+5245 3804 5144 3798 5000 3742 c
+5000 3363 l
+5114 3413 5227 3420 5329 3315 c 
+5329 3700 l
+closepath stroke
+5337 3300 m
+4663 3300 l
+stroke
+% Stroke along the spine of the book
+5000 3300 m
+5000 3742 l
+stroke
+% Line to the sides of the book
+22 setlinewidth
+4716 3360 m
+4716 3750 l
+stroke
+5284 3360 m
+5284 3750 l
+stroke
+0 setgray
+% finally some fine text lines on the book
+4 setlinewidth
+3470 60 3710 { dup dup dup dup dup dup dup
+	4766 exch m 4840 exch l stroke
+	5234 exch m 5160 exch l stroke
+	4877 exch m 4953 exch l stroke
+	5123 exch m 5047 exch l stroke
+	} for
+} def
+/symb_mono {
+0 setgray 30 setlinewidth
+% bottom most horizontal stroke
+4860 2400 m 5000 2400 l stroke
+% Horizontal strokes to base of book
+2500 100 3200 { dup 4670 exch m 5000 exch l stroke } for
+% strokes to the sides of the book
+3300 100 3700 { dup 3400 exch m 5000 exch l stroke } for
+% horiz strokes above the book
+3800 100 4500 { dup 4670 exch m 5000 exch l stroke } for
+% Vertical strokes to the top of the figure
+3614 5450 m 3614 5520 l stroke
+5060 5580 5620 5680 5720 5590 5570 5580 5620 5690 5720 5740 5770 5860 5950
+5000 -99 3614 { dup 4620 m exch l stroke } for
+% bottom dark horizontal line for cross
+84 setlinewidth 3400 3220 m 4696 3220 l stroke
+% Top dark horizontal line for cross
+56 setlinewidth 3460 3813 m 4696 3813 l stroke
+% Bottom dark line for vertical strokes
+92 setlinewidth 3650 4582 m 5000 4582 l stroke
+} def
+
+/sym { sym1 sym2 sym3 sym4 sym5 sym6 sym7 sym8 sym9 syma
+	colour 0 ne
+	{ symb_colour }
+	{ symb_mono }
+	ifelse
+} def
+
+% Draw the main body of the crest..
+0 setlinecap
+5000 0 translate -1 1 scale -5000 0 translate sym
+5000 0 translate -1 1 scale -5000 0 translate sym
+sym_book
+colour 0 eq
+{
+	% draw the dark & light edges for the cross
+	30 setlinewidth
+	4681 3813 m 4681 4582 l stroke
+	4681 3220 m 4681 2400 l stroke
+	84 setlinewidth
+	5346 3813 m 5346 4582 l stroke
+	5346 3220 m 5346 2400 l stroke
+} if
+
+/star {
+-41 -82 rlineto
+-112 42 rlineto
+39 -90 rlineto
+-85 -52 rlineto
+87 -48 rlineto
+-28 -86 rlineto
+93 33 rlineto
+45 -89 rlineto
+44 83 rlineto
+90 -28 rlineto
+-27 106 rlineto
+75 45 rlineto
+-77 42 rlineto
+28 82 rlineto
+-90 -24 rlineto
+-41 66 rlineto closepath } def
+% Draw the lion in black
+0 setlinewidth
+5863 4715 m
+5825 4660 5740 4655 5695 4700 c
+5660 4670 5608 4670 5582 4700 c
+5553 4730 5555 4780 5588 4800 c
+5554 4852 5576 4902 5655 4895 c
+5668 4893 5678 4900 5678 4910 c
+5678 4970 l
+5607 4971 5546 4980 5481 5020 c
+5481 4875 l
+5363 4930 5323 4890 5364 4810 c
+5267 4842 5240 4830 5245 4735 c
+5174 4810 5112 4773 5146 4703 c
+5115 4655 5055 4640 5021 4678 c
+4972 4677 4934 4694 4923 4723 c
+4910 4757 4917 4798 4955 4822 c
+4932 4850 4952 4875 4983 4896 c
+5012 4918 5050 4911 5077 4892 c
+5190 4970 l
+5127 5061 l
+5010 4973 4928 4950 4870 4962 c
+4845 4910 4795 4875 4733 4858 c
+4659 4942 4610 4932 4602 4804 c
+4520 4855 4483 4842 4460 4757 c
+4422 4782 4393 4781 4367 4760 c
+4378 4710 4357 4672 4326 4659 c
+4285 4648 4240 4655 4223 4697 c
+4167 4693 4137 4720 4115 4752 c
+4112 4790 4130 4828 4183 4840 c
+4183 4875 4192 4901 4222 4920 c
+4248 4939 4272 4930 4313 4904 c
+4315 4980 4272 5010 4225 4994 c
+4233 5040 4231 5070 4195 5080 c
+4149 5060 4095 5062 4075 5090 c
+4050 5112 4045 5159 4074 5193 c
+4047 5238 4050 5270 4075 5301 c
+4108 5338 4162 5330 4196 5298 c
+4232 5320 4262 5315 4287 5285 c
+4304 5262 4312 5220 4275 5181 c
+4387 5072 l
+4430 5095 l
+4408 5132 4395 5145 4395 5175 c
+4375 5193 4355 5219 4347 5251 c
+4302 5293 4300 5330 4335 5367 c
+4283 5422 4314 5485 4393 5483 c
+4407 5531 4465 5552 4506 5530 c
+4545 5561 4615 5562 4655 5530 c
+4716 5543 4762 5522 4770 5472 c
+4835 5490 4855 5422 4813 5372 c
+4844 5313 l
+4960 5313 l
+4865 5422 4870 5514 5015 5575 c
+5035 5631 5067 5658 5114 5700 c
+5128 5713 5153 5702 5151 5672 c
+5150 5617 l
+5195 5656 5240 5660 5258 5628 c
+5267 5611 5259 5586 5204 5530 c
+5220 5511 5227 5470 5207 5423 c
+5255 5442 5300 5467 5334 5485 c
+5473 5565 5652 5553 5728 5450 c
+5771 5382 5770 5338 5708 5272 c
+5673 5245 5674 5200 5702 5173 c
+5745 5131 5802 5110 5865 5093 c
+5810 5033 5813 5010 5866 4968 c
+5795 4925 5795 4898 5863 4850 c
+5786 4791 5783 4760 5863 4715 c
+5539 5324 m
+5565 5327 5589 5328 5607 5348 c
+5620 5363 5615 5388 5601 5403 c
+5586 5421 5562 5419 5539 5418 c
+5470 5406 5386 5372 5332 5324 c
+5539 5324 l
+closepath 0 setgray fill
+% We firstly fix problems,
+% The hole in the tail
+red_colour
+5091 5462 m
+5083 5471 5073 5475 5062 5475 c
+5050 5475 5040 5471 5032 5462 c
+5023 5454 5019 5444 5019 5433 c
+5019 5421 5023 5411 5032 5403 c
+5040 5394 5050 5390 5062 5390 c
+5073 5390 5083 5394 5091 5403 c
+5100 5411 5104 5421 5104 5433 c
+5104 5444 5100 5454 5091 5462 c
+closepath  fill
+% Inside of right fore paw
+4294 5212 m
+4287 5200 4282 5191 4274 5180 c
+4280 5173 4287 5171 4294 5164 c
+4294 5182 4295 5195 4294 5212 c
+closepath  fill
+% Rest of the right fore paw
+4328 5261 m
+4328 5212 4328 5176 4328 5127 c
+4347 5110 4360 5098 4379 5080 c
+4386 5074 4401 5084 4400 5094 c
+4400 5120 4396 5138 4396 5164 c
+4395 5179 4386 5190 4375 5200 c
+4354 5219 4354 5250 4328 5261 c
+closepath  fill
+% and now in the rest in gold
+gold_colour
+% crotch
+5300 5162 m
+5326 5166 5354 5166 5371 5145 c
+5344 5139 5321 5146 5300 5162 c
+% Right hind leg
+closepath  fill
+5316 4855 m
+5271 4863 5221 4835 5211 4791 c
+5188 4803 5166 4806 5141 4798 c
+5107 4787 5107 4741 5109 4704 c
+5096 4692 5085 4679 5067 4680 c
+5044 4682 5030 4709 5033 4731 c
+5034 4740 5010 4743 5009 4734 c
+5007 4723 4998 4712 4987 4713 c
+4962 4716 4939 4737 4939 4762 c
+4939 4784 4964 4797 4986 4797 c
+4995 4797 5003 4816 4995 4821 c
+4979 4831 4973 4859 4987 4872 c
+5010 4893 5051 4883 5071 4860 c
+5123 4892 5160 4917 5211 4950 c
+5221 4956 5224 4970 5218 4979 c
+5200 5007 5187 5027 5171 5056 c
+5162 5072 5157 5096 5173 5104 c
+5207 5121 5231 5135 5264 5152 c
+5299 5125 5338 5112 5382 5120 c
+5405 5088 5425 5067 5451 5037 c
+5450 4993 5449 4961 5449 4916 c
+5416 4926 5386 4940 5356 4924 c
+5330 4910 5318 4884 5316 4855 c
+closepath  fill
+% Chest
+4631 5190 m
+4627 5148 4616 5095 4575 5091 c
+4535 5087 4514 5140 4511 5180 c
+4491 5152 4467 5122 4481 5091 c
+4494 5062 4515 5048 4537 5025 c
+4580 5046 4612 5060 4653 5085 c
+4673 5097 4681 5120 4680 5144 c
+4679 5168 4651 5175 4631 5190 c
+closepath  fill
+% Main Body
+4306 4871 m
+4291 4896 4249 4908 4229 4888 c
+4212 4871 4212 4841 4227 4824 c
+4224 4819 4220 4817 4217 4812 c
+4195 4813 4169 4805 4166 4784 c
+4163 4765 4171 4745 4188 4737 c
+4207 4728 4229 4738 4243 4753 c
+4249 4748 4255 4746 4261 4742 c
+4255 4722 4259 4695 4278 4688 c
+4297 4682 4319 4681 4332 4696 c
+4346 4713 4336 4734 4330 4755 c
+4328 4762 4327 4769 4332 4775 c
+4358 4805 4401 4817 4438 4801 c
+4464 4849 4526 4868 4577 4851 c
+4579 4891 4612 4926 4652 4932 c
+4687 4936 4722 4923 4740 4892 c
+4781 4908 4812 4928 4835 4965 c
+4843 4977 4841 4989 4839 5002 c
+4835 5027 4826 5043 4815 5065 c
+4810 5074 4836 5085 4841 5076 c
+4856 5048 4864 5026 4873 4996 c
+4939 4998 4995 5004 5047 5045 c
+5138 5116 5212 5185 5328 5191 c
+5357 5192 5384 5181 5399 5156 c
+5462 5050 5572 5010 5694 4995 c
+5703 4994 5707 4984 5707 4975 c
+5707 4912 5707 4866 5707 4802 c
+5697 4802 5689 4802 5678 4801 c
+5677 4822 5674 4837 5672 4858 c
+5669 4883 5613 4876 5605 4853 c
+5597 4833 5615 4813 5633 4800 c
+5631 4793 5628 4787 5626 4780 c
+5610 4780 5592 4778 5587 4764 c
+5581 4748 5584 4729 5598 4719 c
+5613 4708 5630 4703 5649 4709 c
+5668 4714 5679 4728 5690 4745 c
+5698 4744 5703 4743 5711 4742 c
+5718 4710 5767 4698 5797 4712 c
+5769 4752 5770 4807 5801 4845 c
+5773 4874 5770 4922 5794 4954 c
+5772 4992 5773 5033 5791 5072 c
+5745 5094 5709 5112 5675 5150 c
+5643 5186 5635 5231 5647 5277 c
+5688 5310 5718 5357 5707 5410 c
+5691 5483 5604 5514 5529 5511 c
+5385 5505 5298 5418 5159 5379 c
+5109 5365 5062 5347 5019 5374 c
+4997 5388 4981 5409 4982 5436 c
+4983 5465 5003 5488 5030 5500 c
+5052 5510 5077 5511 5097 5497 c
+5118 5482 5125 5460 5127 5435 c
+5128 5423 5147 5413 5157 5419 c
+5175 5430 5187 5447 5185 5468 c
+5182 5495 5172 5513 5161 5537 c
+5187 5554 5199 5574 5217 5599 c
+5222 5606 5204 5619 5198 5613 c
+5175 5593 5153 5586 5128 5568 c
+5122 5563 5107 5568 5107 5576 c
+5110 5608 5110 5631 5109 5663 c
+5072 5629 5045 5590 5050 5541 c
+4992 5542 4922 5509 4919 5451 c
+4916 5384 4969 5341 5021 5300 c
+4954 5296 4904 5297 4836 5293 c
+4833 5276 4821 5264 4806 5256 c
+4798 5223 4777 5202 4749 5185 c
+4742 5157 4725 5138 4701 5122 c
+4694 5093 4682 5069 4657 5054 c
+4531 4981 4435 4936 4306 4871 c
+5207 5299 l
+5319 5353 5395 5408 5515 5439 c
+5555 5450 5594 5453 5625 5426 c
+5643 5411 5654 5391 5650 5368 c
+5645 5330 5611 5298 5573 5297 c
+5207 5299 l
+closepath  fill
+% Mane below Left Ear
+4774 5350 m
+4765 5338 4761 5328 4755 5315 c
+4770 5303 4780 5293 4793 5279 c
+4800 5284 4804 5289 4810 5295 c
+4805 5296 4802 5296 4798 5296 c
+4798 5307 4798 5315 4797 5325 c
+4796 5338 4783 5342 4774 5350 c
+closepath  fill
+% Mane below Right Ear
+4378 5312 m
+4368 5324 4365 5337 4362 5352 c
+4344 5342 4322 5328 4326 5308 c
+4328 5296 4333 5287 4342 5278 c
+4354 5292 4362 5302 4378 5312 c
+closepath  fill
+% Mane below left Eye
+4690 5230 m
+4683 5217 4674 5209 4661 5200 c
+4677 5187 4687 5177 4700 5161 c
+4713 5173 4735 5196 4720 5207 c
+4709 5216 4701 5222 4690 5230 c
+closepath fill
+% Mane below right Eye
+4483 5195 m
+4466 5201 4452 5207 4443 5221 c
+4420 5208 4398 5174 4416 5155 c
+4425 5145 4432 5139 4442 5131 c
+4454 5156 4465 5173 4483 5195 c
+closepath  fill
+% Face
+4426 5435 m
+4418 5454 4400 5481 4417 5491 c
+4440 5505 4461 5512 4487 5509 c
+4496 5508 4505 5506 4510 5498 c
+4521 5479 4526 5464 4536 5444 c
+4545 5445 4552 5447 4561 5447 c
+4556 5473 4519 5512 4545 5518 c
+4571 5524 4606 5536 4619 5512 c
+4632 5489 4639 5471 4645 5445 c
+4655 5447 4662 5447 4673 5448 c
+4669 5471 4658 5508 4681 5511 c
+4701 5514 4721 5508 4733 5493 c
+4744 5479 4724 5463 4711 5452 c
+4717 5445 4722 5440 4729 5433 c
+4752 5447 4788 5465 4803 5441 c
+4818 5417 4783 5392 4758 5378 c
+4754 5375 4750 5372 4747 5367 c
+4739 5350 4733 5338 4724 5321 c
+4721 5315 4723 5307 4729 5303 c
+4747 5289 4758 5276 4777 5262 c
+4769 5246 4759 5235 4743 5228 c
+4725 5241 4711 5250 4693 5263 c
+4693 5269 4694 5273 4694 5278 c
+4685 5278 4679 5279 4670 5278 c
+4671 5247 4642 5218 4610 5218 c
+4597 5218 4585 5226 4581 5239 c
+4575 5260 4600 5274 4620 5283 c
+4632 5288 4643 5297 4643 5310 c
+4643 5325 4644 5336 4643 5350 c
+4643 5357 4648 5363 4654 5366 c
+4668 5373 4678 5377 4692 5384 c
+4690 5393 4689 5400 4687 5410 c
+4665 5402 4650 5396 4629 5387 c
+4622 5385 4616 5379 4616 5371 c
+4615 5351 4611 5336 4612 5315 c
+4613 5307 4605 5300 4597 5300 c
+4575 5299 4560 5301 4539 5301 c
+4529 5301 4524 5312 4523 5322 c
+4521 5339 4520 5351 4519 5369 c
+4518 5376 4516 5384 4509 5386 c
+4486 5397 4470 5405 4446 5414 c
+4443 5405 4440 5399 4437 5390 c
+4458 5382 4472 5371 4492 5361 c
+4494 5340 4494 5325 4496 5304 c
+4498 5288 4516 5279 4533 5278 c
+4545 5277 4551 5262 4551 5249 c
+4551 5235 4541 5217 4526 5218 c
+4509 5220 4496 5219 4478 5222 c
+4456 5227 4461 5258 4459 5281 c
+4450 5281 4443 5281 4434 5281 c
+4435 5257 4423 5236 4402 5223 c
+4388 5214 4371 5235 4366 5251 c
+4360 5273 4387 5291 4409 5295 c
+4410 5301 4411 5305 4412 5311 c
+4394 5328 4388 5350 4388 5375 c
+4361 5387 4321 5414 4338 5437 c
+4355 5460 4391 5441 4414 5425 c
+4418 5428 4421 5432 4426 5435 c
+closepath fill
+% Tongue
+4564 5204 m
+4556 5198 4549 5194 4540 5192 c
+4543 5167 4546 5129 4571 5130 c
+4597 5130 4596 5170 4595 5195 c
+4583 5197 4574 5198 4564 5204 c
+closepath  fill
+% Right Fore Paw
+4458 5072 m
+4429 5058 4408 5049 4379 5036 c
+4324 5086 4286 5124 4232 5174 c
+4255 5202 4277 5248 4249 5271 c
+4228 5288 4201 5264 4179 5248 c
+4158 5270 4127 5298 4103 5280 c
+4075 5260 4096 5216 4115 5188 c
+4094 5177 4077 5154 4084 5131 c
+4093 5101 4137 5086 4166 5100 c
+4186 5110 4208 5111 4227 5099 c
+4248 5084 4250 5059 4253 5034 c
+4304 5041 4346 4983 4351 4931 c
+4408 4961 4450 4983 4506 5014 c
+4487 5034 4471 5048 4458 5072 c
+closepath  fill
+% Draw the stars (outline in black)
+0 setgray 60 setlinewidth
+3943 3714 m star stroke
+6077 3714 m star stroke
+5010 2943 m star stroke
+5010 4379 m star stroke
+% and fill in gold
+gold_colour 
+3928 3725 m star fill
+6062 3725 m star fill
+4995 2958 m star fill
+4995 4394 m star fill
+
+0 setgray 
+%%IncludeResource: font Times-Bold
+
+/Times-Bold findfont [ 342 0 0 250 0 0 ] makefont setfont newpath
+
+2430 2395 m
+2460 2278 2514 2220 2555 2180 c
+2576 2140 2613 2090 2662 2053 c
+2730 1993 2812 1925 2910 1893 c
+2987 1870 3115 1851 3207 1855 c
+3290 1860 3400 1860 3495 1870 c
+3760 1890 3990 1834 4135 1732 c
+4195 1690 4273 1615 4320 1565 c
+4368 1513 4517 1435 4547 1390 c
+4666 1320 4847 1250 5000 1250 c
+5153 1250 5334 1320 5453 1390 c
+5483 1435 5632 1513 5680 1565 c
+5727 1615 5805 1690 5865 1732 c
+6010 1834 6240 1890 6505 1870 c
+6600 1860 6710 1860 6793 1855 c
+6885 1851 7013 1870 7090 1893 c
+7188 1925 7270 1993 7338 2053 c
+7387 2090 7424 2140 7445 2180 c
+7486 2220 7540 2278 7570 2395 c
+(SIDERE\264MENS\264EADEM\264MUTATO) 0 30 pathtext
+grestore
+showpage
+%%Trailer
diff --git a/doc/user/tbl b/doc/user/tbl
new file mode 100644
index 0000000..230c69e
--- /dev/null
+++ b/doc/user/tbl
@@ -0,0 +1,48 @@
+@Chapter
+    @Title { Tables }
+    @Tag { tables }
+@Begin
+@LP
+This chapter explains how to produce tables like this one:
+tables. @Index { tables }
+@CD @Tbl
+   aindent { ctr }
+   arulebelow { double }
+   aformat { @StartHSpan @Cell @B X | | @HSpan }
+   bformat { @Cell rr { no } @I A | @Cell rl { no } B | @Cell C }
+   rule { yes }
+{
+@Rowa
+   X { Value of mathematical formulae (millions of dollars) }
+@Rowb
+   A { Quadratic formula }
+   B { @Eq { x ^= { minus b +- sqrt { b sup 2 - 4ac } } over 2a } }
+   C { 3^.5 }
+@Rowb
+   A { Binomial theorem }
+   B { @Eq { ( a + b ) sup n ^= big sum from k=0 to infty
+matrix atleft { ( } atright { ) } { n above k } a sup k b sup n-k
+} }
+   C { 12^ }
+}
+As the example shows, the tables may contain spanning columns, aligned
+columns, and rules, and the cells may contain arbitrary objects.
+@BeginSections
+
+@Include { tbl_intr } # introduction
+@Include { tbl_cell } # basic cell formatting: font, break, width, paint
+@Include { tbl_rows } # row formats and the @Row symbol
+@Include { tbl_marg } # margins
+@Include { tbl_widt } # width and height
+@Include { tbl_inde } # indenting and struts
+@Include { tbl_rule } # rules
+@Include { tbl_span } # spanning columns and rows
+@Include { tbl_mult } # multi-page tables
+@Include { tbl_alig } # aligned columns and headings over them
+@Include { tbl_mark } # @MarkRow
+@Include { tbl_plai } # plain text tables
+@Include { tbl_setu } # setup file options
+@Include { tbl_summ } # summary
+
+@EndSections
+@End @Chapter
diff --git a/doc/user/tbl_alig b/doc/user/tbl_alig
new file mode 100644
index 0000000..24b6864
--- /dev/null
+++ b/doc/user/tbl_alig
@@ -0,0 +1,96 @@
+@Section
+    @Title { Aligned columns }
+    @Tag { tbl_alig }
+@Begin
+@PP
+Columns of numbers are often presented with decimal points aligned:
+aligned.columns @Index { aligned columns in tables }
+@CD @OneRow @Tbl
+    marginvertical { 0.5vx }
+    aformat { @Cell A }
+{
+@Rowa A { 5^.46 } marginabove { 0i }
+@Rowa A { 3^.4159 }
+@Rowa A { 5772^ } marginbelow { 0i }
+}
+You can produce this by placing a @Code "^" symbol, which is used
+generally throughout Lout for alignment, just before the alignment point in
+each entry:
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    marginvertical { 0.5vx }
+    aformat { @Cell A }
+{
+@Rowa A { 5^.46 }
+@Rowa A { 3^.4159 }
+@Rowa A { 5772^ }
+}
+}
+The equals signs of equations can be aligned in the same way (see the
+example at the start of this chapter).  Aligned cells should have no
+@Code indent option.
+@PP
+Owing to problems behind the scenes, getting a heading over the top
+of an aligned column is a problem with no ideal solution.  What most
+people want is for the heading to be centred in the column, and the
+aligned entries to be centred in the column as a block, but Lout cannot
+do this.  One approximation is to make the heading cell a spanning
+cell with centring, like this:
+@FootNote { Lout does not currently accept single-column tables
+with {@Code "@StartHSpan"}, so we've had to add
+an empty second column. }
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    marginvertical { 0.5vx }
+    aformat { @StartHSpan @Cell indent { ctr } @B A | }
+    bformat { @Cell A | }
+{
+@Rowa A { Heading }
+@Rowb A { 5^.46 }
+@Rowb A { 3^.4159 }
+@Rowb A { 5772^ }
+}
+}
+The spanning frees the heading from alignment, permitting
+@Code "indent { ctr }" to work:
+@CD @OneRow @Tbl
+    marginvertical { 0.5vx }
+    aformat { @StartHSpan @Cell indent { ctr } @B A | }
+    bformat { @Cell A | }
+{
+@Rowa A { Heading } marginabove { 0i }
+@Rowb A { 5^.46 }
+@Rowb A { 3^.4159 }
+@Rowb A { 5772^ } marginbelow { 0i }
+}
+But if the heading cell is wider than the aligned cells, you get this:
+@CD @OneRow @Tbl
+    marginvertical { 0.5vx }
+    aformat { @StartHSpan @Cell indent { ctr } @B A | }
+    bformat { @Cell A | }
+{
+@Rowa A { A Wider Heading } marginabove { 0i }
+@Rowb A { 5^.46 }
+@Rowb A { 3^.4159 }
+@Rowb A { 5772^ } marginbelow { 0i }
+}
+In other words, this will centre a heading with respect
+to aligned entries, but it will not centre aligned entries with
+respect to a heading.  In these cases you could forget about
+@Code "@StartHSpan" and treat the heading as an aligned entry,
+either by placing a @Code "^" within it or by using
+@ID @Code "@Cell 0.5w @HShift A"
+which places the alignment point in the centre of the entry.
+#@CD @OneRow @Tbl
+#    marginvertical { 0.5vx }
+#    aformat { @Cell 0.5w @HShift @B A }
+#    bformat { @Cell A }
+#{
+#@Rowa A { A Wider Heading } marginabove { 0i }
+#@Rowb A { 5^.46 }
+#@Rowb A { 3^.4159 }
+#@Rowb A { 5772^ } marginbelow { 0i }
+#}
+You can move the alignment point about by changing the 0.5.  Of course,
+all this is a poor substitute for the real thing.
+@End @Section
diff --git a/doc/user/tbl_cell b/doc/user/tbl_cell
new file mode 100644
index 0000000..159372e
--- /dev/null
+++ b/doc/user/tbl_cell
@@ -0,0 +1,97 @@
+@Section
+    @Title { Changing the appearance of cells }
+    @Tag { tbl_cell }
+@Begin
+@PP
+The @Code "@Cell" symbol offers a few options for changing the appearance
+cell.option @Index { cell options in tables }
+of entries placed in it.  Like all options, these
+appear immediately after the @Code "@Cell" symbol, with their values in braces:
+@ID @OneRow @Code @Verbatim {
+@Tbl
+   aformat { @Cell paint { lightgrey } font { Italic } break { clines } A }
+{
+@Rowa A {
+IMPORTANT
+Do not throw stones at this notice
+}
+}
+}
+The result here is
+@CD
+@Tbl
+   aformat { @Cell paint { lightgrey } font { Italic } break { clines } A | @Cell B }
+{
+@Rowa A {
+IMPORTANT
+Do not throw stones at this notice
+}
+}
+with a light grey background, Italic font, and
+@Code "clines" paragraph breaking style.  The paint colour
+may be any colour from Section {@NumberOf colour}.  Another option,
+{@Code background}, allows an arbitrary object to be placed in the
+background of the cell, in front of any paint but behind the entry.
+@PP
+Later sections introduce other @Code "@Cell" options, for
+fixed-width columns, indented entries, margins, and rules.  It is also
+possible to combine other symbols from Lout with cell formatting, by
+placing them between the @Code "@Cell" symbol and its following letter,
+rotated.entries @Index { rotated entries in tables }
+like this:
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    aformat { @Cell 90d @Rotate @S A | @Cell @B grey @Colour B }
+{
+@Rowa
+    A { Col A }
+    B { Col B }
+}
+}
+Think of the @Code "A" as standing for the value of the @Code "A"
+option of the @Code "@Rowa" symbol (which it does), and you'll see
+that this is just Lout's usual rule of symbols applying to the
+object that follows them.  The result here is
+@CD @Tbl
+    aformat { @Cell 90d @Rotate @S A | @Cell @B grey @Colour B }
+{
+@Rowa
+    A { Col A }
+    B { Col B }
+}
+In simple cases @Code "@B" is easier than {@Code "font { Bold }"};
+the latter is useful as a default value, as we will see in a moment.
+Note the difference between a coloured background, obtained with
+{@Code "paint"}, and a coloured entry, obtained using the @Code "@Colour"
+symbol.
+@PP
+@Code "@Tbl" offers many places where you can set cell options.  The meaning
+of the option is the same wherever you set it;
+what changes is the extent of its application.  Taking the @Code "paint"
+option as a representative example, the most specific place to set it
+is at a @Code "@Cell" symbol as above; then it affects only that cell
+in rows formatted using that format.  Alternatively,
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    apaint { lightgrey }
+    aformat { @Cell A | @Cell B }
+}
+will paint every cell in the {@Code "aformat"}.  And
+@ID @OneRow @Code @Verbatim {
+@Rowa
+    paint { lightgrey }
+    A { ... }
+}
+will paint every cell in a particular row.  To paint the entire table, use
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    paint { lightgrey }
+}
+And finally, there is a @Code "paint" option in the
+setup file (Section {@NumberOf tbl_setu}), which if set will paint every
+table in the document.  When a more general setting of an option is
+contradicted by a more specific setting (e.g. when @Code "@Tbl" has
+@Code "paint { lightgrey }" but some cell or row has
+{@Code "paint { nopaint }"}), the more specific setting applies.  For a
+precise description, see Section {@NumberOf tbl_summ}.
+@End @Section
diff --git a/doc/user/tbl_inde b/doc/user/tbl_inde
new file mode 100644
index 0000000..75a3471
--- /dev/null
+++ b/doc/user/tbl_inde
@@ -0,0 +1,58 @@
+@Section
+    @Title { Indenting and struts }
+    @Tag { tbl_inde }
+@Begin
+@PP
+By default, entries appear at the left within cells, not counting the
+cell margin.  The @Code indent option causes entries to be indented
+horizontally.  For example,
+@ID @OneRow @Code "@Cell indent { ctr }"
+horizontally centres the entry within the cell.  The other possible values
+centred.entries @Index { centred entries in tables }
+right.justified.entries @Index { right justified entries in tables }
+of this option are {@Code "left"}, {@Code "right"}, or any length (for
+example, {@Code 2f}) meaning that much indent.
+@PP
+There is a corresponding @Code "indentvertical" option for vertical indenting
+within the cell.  It takes the same values except that @Code "left" is
+renamed {@Code "top"}, and @Code "right" is renamed {@Code foot}.
+A common problem with vertical placement is that words that lack
+ascenders (parts of letters that rise up) or descenders (parts that
+sink down) can easily become misaligned with words that
+don't.  Looking at
+@CD @Tbl
+    aformat { @Cell A | @Cell B | @Cell C }
+    marginvertical { 0i }
+{
+@Rowa
+    A { resume }
+    B { poppy }
+    C { title }
+}
+which is the result of
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    aformat { @Cell A | @Cell B | @Cell C }
+{
+@Rowa
+    A { resume }
+    B { poppy }
+    C { title }
+}
+}
+we see that the words are aligned correctly despite the absence of
+ascenders from the first two words, and of descenders from the first
+and last; and this despite the fact that these words are vertically
+placed at the top of the cell.  This is because by default
+@Code "@Tbl" adds a @I { vertical strut } to each entry:  an invisible
+object of zero width and height {@Code "1f"}, which covers for any absent
+ascenders and descenders.  The option
+@ID @OneRow @Code "@Cell strut { no }"
+can be used to remove the strut; other acceptable values for this
+option are {@Code yes} (the default value), and any length, which will
+add a strut of that length.
+@PP
+For completeness there is a corresponding @Code "struthorizontal" option; it
+takes the same values, its default value is {@Code no}, and it unlikely
+ever to be used.
+@End @Section
diff --git a/doc/user/tbl_intr b/doc/user/tbl_intr
new file mode 100644
index 0000000..a46da18
--- /dev/null
+++ b/doc/user/tbl_intr
@@ -0,0 +1,119 @@
+@Section
+    @Title { Getting started }
+    @Tag { tbl_intr }
+@Begin
+@PP
+The Lout definitions for table formatting
+@FootNote {
+The @Code "tbl" package described here replaces the @Code "tab"
+package of Version 3.12 and earlier.  For backward compatibility
+the @Code "tab" package is still available and still works as
+described in older versions of this documentation.  Users of
+@Code "tab" will find simple uses of @Code "tbl" to be very similar,
+replacing @Code "@Tab" by {@Code "@Tbl"}, @Code "@Fmta" by
+{@Code "aformat"}, @Code "@Col" by {@Code "@Cell"}, and
+@Code "!" by {@Code "|"}.
+}
+are kept in a file called {@Code "tbl"}, which you must include at
+the start of your document if
+tbl.file @Index { @Code "tbl" file }
+you want tables, like this:
+@ID @OneRow @Code {
+"@SysInclude { tbl }"
+"@SysInclude { doc }"
+"@Doc @Text @Begin"
+"..."
+"@End @Text"
+}
+Specialized setup files, like {@Code "tbl"}, are included before the main
+setup file (@Code "doc" in this case).  Alternatively, if you are using
+your own setup file, you may place the include commands within it, near the
+start.
+@PP
+To begin with a very simple example, the table
+tbl. @Index @Code "@Tbl"
+@CD
+@Tbl
+    aformat { @Cell A  |  @Cell B  |  @Cell C }
+{
+@Rowa
+    A { Austen }
+    B { Chaucer }
+    C { Donne }
+@Rowa
+    A { Balzac }
+    B { Darwin }
+    C { Goethe }
+@Rowa
+    A { Byron }
+    B { Dickens }
+    C { Homer }
+}
+is produced by the following input:
+@ID @OneRow @Code {
+"@Tbl"
+"    aformat { @Cell A  |  @Cell B  |  @Cell C }"
+"{"
+"@Rowa"
+"    A { Austen }"
+"    B { Chaucer }"
+"    C { Donne }"
+"@Rowa"
+"    A { Balzac }"
+"    B { Darwin }"
+"    C { Goethe }"
+"@Rowa"
+"    A { Byron }"
+"    B { Dickens }"
+"    C { Homer }"
+"}"
+}
+Immediately after the @Code "@Tbl" symbol, which introduces the table,
+comes a @I { format option }, {@Code "aformat"}, describing the format of
+each row.  It says that each row contains three cells:  {@Code "@Cell A"},
+{@Code "@Cell B"}, and {@Code "@Cell C"}.  The format option may have up
+to 26 cells, with names chosen freely from the upper-case letters from
+@Code A to {@Code Z}.  The symbol @Code "|" separates each cell from the next.
+@PP
+After the format option comes the body of the table, enclosed in
+braces.  It consists entirely of a sequence of rows, each introduced by
+a @Code "@Rowa" symbol and containing one entry for each cell of the
+format option, as shown (the row may occupy any number of lines of the
+input file).  The entries may be arbitrary Lout objects, such as words,
+paragraphs, equations, figures, and so on without restriction.  An entry
+may be omitted altogether if it is empty.  Lout will choose suitable widths
+for the cells, and break paragraphs in the entries to the right widths.
+@PP
+The result of the @Code "@Tbl" symbol is an object.  As usual with
+Lout, this object may appear at any point in the document,
+@FootNote {
+In rare cases, when the table occupies an entire paragraph but is not
+displayed, a bug in the current version of Basser Lout causes the second
+column to appear much too far to the right.  Until the problem is fixed,
+the first thing to try if this occurs is to replace the very first
+row symbol ({@Code "@Rowa"}, {@Code "@Rowb"}, etc.) by {@Code "@FirstRowa"},
+{@Code "@FirstRowb"}, etc.
+# That should work, but if it doesn't, replacing
+# @Code "@Tbl" by @Code "@OneCol @Tbl" certainly will, although it also
+# prevents the table from breaking across page boundaries.
+}
+even within a paragraph or another table.  Most commonly, though, tables
+are displayed using the @Code "@IndentedDisplay" and @Code "@CentredDisplay"
+symbols (Section {@NumberOf displays}):
+@ID @Code "@CentredDisplay @Tbl ..."
+or else they go into the @Code "@Table" symbol (Section {@NumberOf figures}):
+@ID @OneRow @Code {
+"@Table"
+"    @Caption { ... }"
+"@Tbl ..."
+}
+which centres them at the top of the following page and adds a
+caption.  Note the difference between {@Code "@Tbl"}, which builds a
+table, and {@Code "@Table"}, which places an arbitrary object in an
+appropriate place.  It's important to remember that the result
+is an object like any other, because from time to time one wants such
+things as rotated tables whose entire contents are to be italicised:
+@ID @Code "90d @Rotate @I @Tbl ..."
+and it helps to remember that the full power of Lout can be
+brought to bear on the @I entire table.
+@End @Section
diff --git a/doc/user/tbl_marg b/doc/user/tbl_marg
new file mode 100644
index 0000000..89e63cd
--- /dev/null
+++ b/doc/user/tbl_marg
@@ -0,0 +1,74 @@
+@Section
+    @Title { Margins }
+    @Tag { tbl_marg }
+@Begin
+@PP
+The @Code "@Cell" symbol offers a @Code margin option for changing the
+margins @RawIndex { margins }
+margins.in.tables @SubIndex { margins in tables }
+amount of margin left between the entry and the boundary of the cell:
+@ID @Code "@Cell margin { 0.3f }"
+The default values are different for horizontal and vertical margins,
+which brings us to the @Code marginhorizontal and @Code marginvertical
+options:
+@ID @OneRow @Code @Verbatim {
+@Cell
+    marginhorizontal { 0.6f }
+    marginvertical { 0.3f }
+}
+These are the default values, 0.6 and 0.3 times the current font size
+respectively.  Another useful value is {@Code "marginvertical { 0.5vx }"},
+which asks for a vertical margin of half the current line separation, but
+measured from baseline to baseline (this is what the @Code "x" means).
+This produces a separation equal to the separation of the surrounding lines:
+@CD @Tbl
+    marginvertical { 0.5vx }
+    aformat { @Cell A  |  @Cell B  |  @Cell C }
+{
+@Rowa
+    A { Austen }
+    B { Chaucer }
+    C { Donne }
+@Rowa
+    A { Balzac }
+    B { Darwin }
+    C { Goethe }
+@Rowa
+    A { Byron }
+    B { Dickens }
+    C { Homer }
+}
+This margin does not work so well when the cells contain paragraphs,
+diagrams or other things that could not be described as single lines.
+@PP
+There are {@Code "marginabove"}, {@Code "marginbelow"}, {@Code "marginleft"},
+and {@Code "marginright"} options for setting margins individually.  For
+example, sometimes you don't want the extreme left and right margins in
+a table, and they can be got rid of like this:
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    paint { lightgrey }
+    aformat { @Cell ml { 0i } A  |  @Cell B  |  @Cell mr { 0i } C }
+{
+@Rowa
+    A { Column A }
+    B { Column B }
+    C { Column C }
+}
+}
+We've used abbreviated versions of the options' names:  @Code "ml" for
+{@Code marginleft}, and @Code "mr" for {@Code marginright}.  Every option
+has such an abbreviated name, made from the first letters of the parts of
+its full name (Section {@NumberOf tbl_summ} lists all these names).  The
+result is
+@CD @Tbl
+    paint { lightgrey }
+    aformat { @Cell ml { 0i } A  |  @Cell B  |  @Cell mr { 0i } C }
+{
+@Rowa
+    A { Column A }
+    B { Column B }
+    C { Column C }
+}
+with the painting showing the reduced margins.
+@End @Section
diff --git a/doc/user/tbl_mark b/doc/user/tbl_mark
new file mode 100644
index 0000000..8761979
--- /dev/null
+++ b/doc/user/tbl_mark
@@ -0,0 +1,65 @@
+@Section
+    @Title { Vertical alignment of tables }
+    @Tag { tbl_mark }
+@Begin
+@PP
+Occasionally the vertical alignment of a table with objects to its left
+vertical.alignment @Index { vertical alignment of tables }
+and right becomes an issue.  Examples are hard to find, but let's say
+that we need to construct a symbol
+@ID @AmberLight
+and include it in running text.  The obvious first attempt at a table
+with three rows produces
+#@ID @OneRow @Code @Verbatim {
+#@Tbl
+#   aformat { @Cell A }
+#   margin { 0i }
+#   strut { no }
+#{
+#@Rowa A { @OpenCircle }
+#@Rowa A { @ClosedCircle }
+#@Rowa A { @OpenCircle }
+#}
+#}
+#where @Code "@OpenCircle" and @Code "@ClosedCircle" produce open and
+#closed circles (they may be defined using the @Code "@Diag" package);
+#but this produces
+@Tbl
+   aformat { @Cell A }
+   margin { 0i }
+   strut { no }
+{
+@Rowa A { @OpenCircle }
+@Rowa A { @ClosedCircle }
+@Rowa A { @OpenCircle }
+}
+in running text, because vertical alignment is by default through the
+top boundary of the table.  To make the alignment pass through one of
+the rows, replace its @Code "@Row" symbol by a corresponding
+@Code "@MarkRow" symbol.  Here is the revised table, enclosed in a
+definition for ease of use:
+amberlight @Index { @Code "@AmberLight" symbol }
+@ID @OneRow @Code @Verbatim {
+import @TblSetup
+def @AmberLight
+{
+    @OneRow @Tbl
+         aformat { @Cell A }
+         margin { 0i }
+         strut { no }
+         paint { no }  rule { no }
+     {
+         @Rowa A { @OpenCircle }
+         @MarkRowa A { @ClosedCircle }
+         @Rowa A { @OpenCircle }
+     }
+}
+}
+Now when we write
+@ID @Code "produces @AmberLight in running text"
+we find that this definition produces @AmberLight in running text, as
+desired.  We have enclosed the table in @Code "@OneRow" to ensure that
+its rows will never become separated, and added some options just in
+case the definition is ever used with a setup file (Section
+{@NumberOf tbl_setu}) that has default painting or rules.
+@End @Section
diff --git a/doc/user/tbl_mult b/doc/user/tbl_mult
new file mode 100644
index 0000000..84ce363
--- /dev/null
+++ b/doc/user/tbl_mult
@@ -0,0 +1,57 @@
+@Section
+    @Title { Multi-page tables }
+    @Tag { tbl_mult }
+@Begin
+@PP
+The tables produced by @Code "@Tbl" permit page breaks (including breaking
+multi.page.tables @Index { multi-page tables }
+to a new column) between every two rows, except rows that have a
+vertically spanning cell in common.  Page breaks cannot occur
+within rows.  The choice of page breaks can either be left to Lout,
+or it can be forced by placing the new page symbol @Code "@NP" between two
+np.tables @Index { @Code "@NP" (new page) in tables }
+rows.
+@PP
+Some care is needed over where to put multi-page tables.  They can't go
+within any of the display symbols, because display symbols are not clever
+enough to break tables between rows, even though they are sometimes able
+to break simpler displays.  (A display symbol will scale a very high table
+to fit on one page, and it will go wrong on a table containing
+{@Code "@NP"}.)  Multi-page tables can go inside @Code "@Figure" or
+@Code "@Table" symbols, because these symbols have been set up to accept
+multi-page objects.  Or they can go into the body text of the document
+at full width with a paragraph symbol before and after, like this:
+@ID @Code @Verbatim {
+@DP
+@Tbl ...
+@DP
+}
+An example of this kind of multi-page table appears in
+Section {@NumberOf tbl_summ}.  You can simulate an indent by means of an
+empty cell at the left of each row format, although in the author's opinion
+a multi-page table looks better at full width anyway.  Lout will expand the
+rightmost column to the full page width; one way to prevent this is to add
+a @Code "|" after the last cell within each {@Code format} option, creating
+an empty extra column.
+@PP
+The simplest way to get rules right in multi-page tables is to set
+@Code "rulehorizontal" to {@Code yes}.  This places a rule above every
+row including the first on each page, and a rule below every row including
+the last on each page.
+@PP
+To prevent page breaks within a table, precede the @Code "@Tbl"
+symbol by {@Code "@OneRow"}:
+@ID @Code "@CD @OneRow @Tbl ..."
+@Code "@OneRow" is a general Lout symbol which binds the following
+object into a single, unbreakable row.  Make sure your table is
+small enough to fit on one page when you do this, otherwise an error
+message will be printed and it will be scaled to fit.  Of course, we
+have just said that display symbols like @Code "@CD" do this anyway,
+but that might change some day.
+@PP
+To prevent a page break between two particular rows, but not in
+general, replace the @Code "@Row" symbol of the second row with
+the corresponding @Code "@NoBreakRow" symbol (@Code "@NoBreakRowa"
+instead of {@Code "@Rowa"}, @Code "@NoBreakRowb" instead of
+{@Code "@Rowb"}, and so on).
+@End @Section
diff --git a/doc/user/tbl_plai b/doc/user/tbl_plai
new file mode 100644
index 0000000..0813717
--- /dev/null
+++ b/doc/user/tbl_plai
@@ -0,0 +1,84 @@
+@Section
+    @Title { Plain text tables }
+    @Tag { tbl_plai }
+@Begin
+@PP
+Tables work well with plain text output (Section {@NumberOf plain}):
+plain.text.tables @Index { plain text tables }
+@CD @OneRow -1px @Break @F @Verbatim {
+...................................................
+.                 .                               .
+. Johnson         . Johnson suddenly uttered an   .
+. suddenly        . apophegm, at which many will  .
+. uttered an      . start:  `Patriotism is the    .
+. apophegm, at    . last refuge of a scoundrel.'  .
+. which many      .                               .
+. will start:     .                               .
+. `Patriotism     .................................
+. is the last     .               .               .
+. refuge of a     . Johnson       . Johnson       .
+. scoundrel.'     . suddenly      . suddenly      .
+.                 . uttered an    . uttered an    .
+.                 . apophegm, at  . apophegm, at  .
+.                 . which many    . which many    .
+.                 . will start:   . will start:   .
+.                 . `Patriotism   . `Patriotism   .
+.                 . is the last   . is the last   .
+.                 . refuge of a   . refuge of a   .
+.                 . scoundrel.'   . scoundrel.'   .
+.                 .               .               .
+.                 .               .               .
+...................................               .
+.                                 .               .
+. Johnson suddenly uttered an     .               .
+. apophegm, at which many will    .               .
+. start:  `Patriotism is the      .               .
+. last refuge of a scoundrel.'    .               .
+.                                 .               .
+.                                 .               .
+...................................................
+}
+This table was produced by a separate run of Lout and pasted into this
+document.
+@PP
+@Code "@Tbl" changes the default values of several options when used
+in a plain text document:
+@ID @Code @Verbatim {
+@Tbl
+    marginvertical { 2f }
+    marginhorizontal { 2s }
+    rulehorizontalwidth { 1f }
+    ruleverticalwidth { 1s }
+    rulehorizontalgap { 0f }
+    ruleverticalgap { 0s }
+}
+When using plain text it is advisable to make vertical distances whole
+multiples of {@Code "1f"}, and horizontal distances whole multiples of
+{@Code "1s"}, since this avoids fractional spacing which cannot be successful
+in plain text files and produces quite messy results.  There is also a
+@Code ruleplainchar option for changing the character used to
+draw rules.  For example,
+@ID @Code @Verbatim {
+@Tbl
+    ruleplainchar { - }
+}
+would be a good choice if you plan to draw only horizontal rules.  This
+option can be set anywhere as usual.
+@PP
+If you do use rules it is worth pondering the implications of the last
+part of Section {@NumberOf tbl_rule}.  Right and below rules are drawn
+outside the boundary of the cell, which is unimportant
+in ordinary output, but means that they will appear one space to the
+right and one line below the cell in plain text output.  This explains
+the slight asymmetry in the example above; you can correct it with
+@ID @Code @Verbatim {
+@Tbl
+    marginright { 1s }
+    marginbelow { 1f }
+}
+but you still have to worry about rules at the extreme right of the
+page going off the edge, and rules below the last line bumping into
+whatever follows the table.  The first can be fixed by not using
+full width tables with right rules; the second by inserting an extra
+@Code "@DP" after a table that ends with a below rule.
+@End @Section
diff --git a/doc/user/tbl_rows b/doc/user/tbl_rows
new file mode 100644
index 0000000..7d26b75
--- /dev/null
+++ b/doc/user/tbl_rows
@@ -0,0 +1,59 @@
+@Section
+    @Title { Changing the appearance of rows }
+    @Tag { tbl_rows }
+@Begin
+@PP
+We've seen that the @Code aformat option of @Code "@Tbl" determines the
+format of the rows introduced by the @Code "@Rowa" symbol.  There are
+eight of these row format options: {@Code aformat},
+row.formats @Index { row formats in tables }
+{@Code bformat}, and so on up to {@Code hformat}, and for each there
+is a corresponding {@Code "@Row"} symbol:  {@Code "@Rowa"}, {@Code "@Rowb"},
+and so on up to {@Code "@Rowh"}:
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    aformat { @Cell @I A  |  @Cell @I B }
+    bformat { @Cell A  |  @Cell B }
+{
+@Rowa
+    A { Name }
+    B { Nationality }
+@Rowb
+    A { Austen }
+    B { English }
+@Rowb
+    A { Balzac }
+    B { French }
+}
+}
+The result of this is
+@CD @OneRow @Tbl
+    aformat { @Cell @I A  |  @Cell @I B }
+    bformat { @Cell A  |  @Cell B }
+{
+@Rowa
+    A { Name }
+    B { Nationality }
+@Rowb
+    A { Austen }
+    B { English }
+@Rowb
+    A { Balzac }
+    B { French }
+}
+The first row, being a {@Code "@Rowa"}, is formatted using
+{@Code aformat}; the others, being {@Code "@Rowb"} symbols, are
+formatted using {@Code bformat}.
+@PP
+In addition to the eight @Code format options of {@Code "@Tbl"}, it is
+possible to specify the format of a row at the row itself, using the
+@Code "@Row" symbol like this:
+@ID @OneRow @Code @Verbatim {
+@Row
+    format { @Cell @B A | @Cell paint { lightgrey } B }
+    A { ... }
+    B { ... }
+}
+All formats must contain the same number of cells, otherwise the table
+will not be rectangular.
+@End @Section
diff --git a/doc/user/tbl_rule b/doc/user/tbl_rule
new file mode 100644
index 0000000..383ffab
--- /dev/null
+++ b/doc/user/tbl_rule
@@ -0,0 +1,192 @@
+@Section
+    @Title { Rules }
+    @Tag { tbl_rule }
+@Begin
+@PP
+There is a @Code "rule" option for drawing a rule around a cell:
+@ID @OneRow @Code "@Cell rule { yes }"
+The other possible values are {@Code no} (the default),
+{@Code single} (the same as {@Code yes}), and {@Code double}, which
+draws a double rule.
+@PP
+There are @Code "rulehorizontal" and @Code "rulevertical" options which
+draw only horizontal or vertical rules, and also {@Code "ruleabove"},
+{@Code "rulebelow"}, {@Code "ruleleft"}, and {@Code "ruleright"} options:
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    aformat { @Cell A | @Cell B }
+{
+@Rowa
+    ruleabove { yes }
+    A { Commercial property }
+    B { 10% }
+@Rowa
+    A { Stock market }
+    B { 15% }
+    rulebelow { yes }
+}
+}
+produces
+@CD @OneRow @Tbl
+    aformat { @Cell A | @Cell B }
+{
+@Rowa
+    ruleabove { yes }
+    A { Commercial property  }
+    B { 10% }
+@Rowa
+    A { Stock market }
+    B { 15% }
+    rulebelow { yes }
+}
+These options take the same values as {@Code "rule"}, but draw
+along only one or two of the four edges.
+@PP
+Other options control the appearance of rules.  Here they are with their
+default values:
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    rulewidth { 0.05f }
+    rulegap { 0.15f }
+    rulecolour { black }
+}
+These say that rules are to be @Code "0.05f" wide (thick), double rules
+are to appear @Code "0.15f" apart, and the colour of rules is to be black.
+Once again, more specific versions of these symbols exist for controlling
+above, below, left, and right rules:
+@ID @OneRow @Code @Tbl
+    aformat { @Cell ml { 0i } A | @Cell B | @Cell C }
+    marginvertical { 0.5vx }
+{
+@Rowa
+    A { rulehorizontalwidth }
+    B { rulehorizontalgap }
+    C { rulehorizontalcolour }
+@Rowa
+    A { ruleabovewidth }
+    B { ruleabovegap }
+    C { ruleabovecolour }
+@Rowa
+    A { rulebelowwidth }
+    B { rulebelowgap }
+    C { rulebelowcolour }
+@Rowa
+    A { ruleverticalwidth }
+    B { ruleverticalgap }
+    C { ruleverticalcolour }
+@Rowa
+    A { ruleleftwidth }
+    B { ruleleftgap }
+    C { ruleleftcolour }
+@Rowa
+    A { rulerightwidth }
+    B { rulerightgap }
+    C { rulerightcolour }
+}
+As usual, all these options have abbreviated names; and @Code { colour }
+may be spelt @Code { color } wherever it appears.  Section
+{@NumberOf tbl_summ} has a complete summary of all spellings of all
+options.
+@PP
+To clarify exactly where the rules are drawn, let's start with
+a cell with no rules at all:
+@CD @Tbl
+    aformat { @Cell width { 3c } height { 1.5c } paint { lightgrey } A }
+{
+@Rowa
+}
+Above rules and left rules are drawn within the cell boundary, just
+touching it, with any above rule overstriking any left rule:
+@CD { @Tbl
+    aformat { @Cell width { 3c } height { 1.5c } paint { lightgrey } A }
+{
+@Rowa
+}
+@Background @Tbl
+    aformat { @Cell width { 3c } height { 1.5c } A }
+    ruleleft { yes }
+    ruleabove { yes }
+    rulehorizontalwidth { 0.8v }
+    ruleverticalwidth { 0.5v }
+    ruleverticalcolour { grey }
+    rulehorizontalcolour { black }
+{
+@Rowa
+}
+}
+Below and right rules are drawn just outside the boundary of the
+cell, also touching it:
+@CD @Tbl aformat { @Cell A | @Cell | @Cell B }
+{
+@Rowa
+    A {
+        @Tbl
+            aformat { @Cell width { 3c } height { 1.5c } paint { lightgrey } A }
+        {
+        @Rowa
+        }
+        @Background
+        @Tbl
+            aformat { @Cell width { 3c } height { 1.5c } A }
+            rulebelow { yes }
+	    rulehorizontalwidth { 0.8v }
+	    ruleverticalwidth { 0.5v }
+	    ruleverticalcolour { grey }
+	    rulehorizontalcolour { black }
+        {
+        @Rowa
+        }
+      }
+    B {
+        @Tbl
+            aformat { @Cell width { 3c } height { 1.5c } paint { lightgrey } A }
+        {
+        @Rowa
+        }
+        @Background
+        @Tbl
+            aformat { @Cell width { 3c } height { 1.5c } A }
+            ruleright { yes }
+	    rulehorizontalwidth { 0.8v }
+	    ruleverticalwidth { 0.5v }
+	    ruleverticalcolour { grey }
+	    rulehorizontalcolour { black }
+        {
+        @Rowa
+        }
+      }
+}
+@DP
+When a right rule is present, any above and below rules are extended
+by the width of the right rule, and they overstrike it:
+@CD {
+@Tbl
+    aformat { @Cell width { 3c } height { 1.5c } paint { lightgrey } A }
+{
+@Rowa
+}
+@Background
+@Tbl
+    aformat { @Cell width { 3c } height { 1.5c } A }
+    ruleabove { yes }
+    ruleright { yes }
+    rulebelow { yes }
+    rulehorizontalwidth { 0.8v }
+    ruleverticalwidth { 0.5v }
+    ruleverticalcolour { grey }
+    rulehorizontalcolour { black }
+{
+@Rowa
+}
+}
+@DP
+(These diagrams were produced by @Code "@Tbl" itself, using horizontal
+rules of width @Code 0.8v drawn in black, and vertical rules of width
+@Code 0.5v drawn in grey.)  These arrangements ensure that even thick
+rules produce clean corners, and also that a right rule and a neighbouring
+left rule exactly overstrike each other, as do a below rule and its
+neighbouring above rule.
+@PP
+For information about rules in plain text tables, consult Section
+{@NumberOf tbl_plai}.
+@End @Section
diff --git a/doc/user/tbl_setu b/doc/user/tbl_setu
new file mode 100644
index 0000000..74bdb9a
--- /dev/null
+++ b/doc/user/tbl_setu
@@ -0,0 +1,65 @@
+@Section
+    @Title { Changing the overall format }
+    @Tag { tbl_setu }
+@Begin
+@PP
+All of the options apart from the @Code format options can be changed
+setup.files.tables @Index { setup files for tables }
+in the @Code { tbl } setup file, in which case the new values become
+the default values for every table in the document.  This section
+explains how to do it.  Changing options in the setup file can save a
+lot of time, but its more important purposes are to promote consistency
+and to allow document-wide formatting changes to be carried out easily.
+@PP
+The first step is to obtain your own copy of the setup file, @Code { tbl },
+from the Lout system include directory.  You can find out where that
+is by typing
+@ID @Code { lout -V }
+This prints out various things about Lout.  Supposing that it says
+that the Lout system include directory is @Code { "/usr/lout/include" }, for
+example, you can copy the setup file into your current directory,
+renaming it @Code { mytbl }, with the Unix command
+@ID @Code "cp  /usr/lout/include/tbl  mytbl"
+or its equivalent on your system.  You will also need to make
+@Code { mytbl } writable.
+@PP
+The next step is to replace the @Code "@SysInclude { tbl }" line at the
+start of your document with @Code { "@Include { mytbl }" }.  This causes
+Lout to read your copy of the setup file, not the one in the system
+include directory.  Since the two files are currently identical, this
+has changed nothing so far, but now you can change the options within
+@Code mytbl and the changes will affect your document.
+@PP
+Your copy of the setup file has some lines beginning with @Code "#"
+that are ignored by Lout, and then it has @Code { "@SysInclude { tblf }" }.
+This line tells Lout to read file @Code tblf which contains the definition
+of the @Code tbl package, so it should not be changed.  After it comes
+the @Code "@TblSetup" @Code "@Use" clause, which looks like this:
+@ID @OneRow @Code @Verbatim {
+@Use { @TblSetup
+    # paint { nopaint }
+    # font { }
+    # break { }
+}
+}
+Only a few of the options are shown here.  To change a setup file
+option, delete the @Code "#" in front of it and change the value.  For
+example, suppose you want all table entries two points smaller than the
+surrounding text:
+@ID @OneRow @Code @Verbatim {
+@Use { @TblSetup
+    # paint { nopaint }
+    font { -2p }
+    # break { }
+}
+}
+This relative specification of font size is available anywhere, not
+just in setup files (Section {@NumberOf fonts}).
+@PP
+Some setup file options contain values which use the @Code "@OrIfPlain"
+symbol:
+@ID @Code "marginvertical { 0.3f @OrIfPlain 1f }"
+This means that the value of @Code marginvertical is to be @Code "0.3f"
+usually, but @Code 1f in plain text documents.  Feel free to leave these
+symbols there when you change a value, or delete them if you prefer.
+@End @Section
diff --git a/doc/user/tbl_span b/doc/user/tbl_span
new file mode 100644
index 0000000..5621961
--- /dev/null
+++ b/doc/user/tbl_span
@@ -0,0 +1,195 @@
+@Section
+    @Title { Spanning columns and rows }
+    @Tag { tbl_span }
+@Begin
+@PP
+To make a cell span across several columns, precede the @Code "@Cell"
+spanning.columns @Index { spanning columns and rows in tables }
+symbol with @Code "@StartHSpan" and replace each spanned cell's
+@Code "@Cell" symbol with {@Code "@HSpan"}, like this:
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    rule { yes }
+    aformat { @StartHSpan @Cell indent { ctr } @B A | @HSpan | @HSpan }
+    bformat { @Cell A | @Cell B | @Cell C }
+{
+@Rowa
+    A { Some famous authors }
+@Rowb
+    A { Austen }
+    B { Chaucer }
+    C { Donne }
+@Rowb
+    A { Balzac }
+    B { Darwin }
+    C { Goethe }
+}
+}
+The result of this is
+@CD @OneRow @Tbl
+    rule { yes }
+    aformat { @StartHSpan @Cell indent { ctr } @B A | @HSpan | @HSpan }
+    bformat { @Cell A | @Cell B | @Cell C }
+{
+@Rowa
+    A { Some famous authors }
+@Rowb
+    A { Austen }
+    B { Chaucer }
+    C { Donne }
+@Rowb
+    A { Balzac }
+    B { Darwin }
+    C { Goethe }
+}
+We've used a sample of options to show how naturally these go with
+spanning cells:  they apply to the whole cell as usual, whatever
+its extent.  It is quite acceptable to span just some of the columns,
+not all of them; indeed, there may be no @Code "@HSpan" symbols at
+all, and then the cell just spans its own column, which sounds redundant
+but actually has a use (Section {@NumberOf tbl_alig}).
+@PP
+Spanning rows work in the same way; the spanning cell is preceded by
+{@Code "@StartVSpan"}, and the spanned cells are replaced by
+{@Code "@VSpan"}:
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    rule { yes }
+    aformat { @StartVSpan @Cell @I A | @Cell B | @Cell C }
+    bformat { @VSpan | @Cell B | @Cell C }
+{
+@Rowa
+    A { Mathematics }
+    B { MATH 1001 }
+    C { Differential Calculus }
+@Rowb
+    B { MATH 1002 }
+    C { Linear Algebra }
+@Rowa
+    A { Computer Science }
+    B { COMP 1001 }
+    C { Introductory Programming }
+@Rowb
+    B { COMP 1002 }
+    C { Introductory Computer Science }
+}
+}
+The result of this is
+@CD @OneRow @Tbl
+    rule { yes }
+    aformat { @StartVSpan @Cell @I A | @Cell B | @Cell C }
+    bformat { @VSpan | @Cell B | @Cell C }
+{
+@Rowa
+    A { Mathematics }
+    B { MATH 1001 }
+    C { Differential Calculus }
+@Rowb
+    B { MATH 1002 }
+    C { Linear Algebra }
+@Rowa
+    A { Computer Science }
+    B { COMP 1001 }
+    C { Introductory Programming }
+@Rowb
+    B { COMP 1002 }
+    C { Introductory Computer Science }
+}
+Here is a notorious larger example, the `spiral':
+@ID @OneRow @Code @Verbatim {
+@QuotedDisplay @Tbl
+    rule { yes }
+{
+@Row
+    format { @StartVSpan @Cell A | @StartHSpan @Cell B | @HSpan }
+    A { @SomeText }
+    B { @SomeText }
+@Row
+    format { @VSpan | @Cell B | @StartVSpan @Cell C }
+    B { @SomeText }
+    C { @SomeText }
+@Row
+    format { @StartHSpan @Cell A | @HSpan | @VSpan }
+    A { @SomeText }
+}
+}
+The @Code "@SomeText" symbol produces a short paragraph of text.  The
+result is
+@QD @Tbl
+    rule { yes }
+{
+@Row format { @StartVSpan @Cell A | @StartHSpan @Cell B | @HSpan }
+    A { @SomeText }
+    B { @SomeText }
+@Row format { @VSpan | @Cell B | @StartVSpan @Cell C }
+    B { @SomeText }
+    C { @SomeText }
+@Row format { @StartHSpan @Cell A | @HSpan | @VSpan }
+    A { @SomeText }
+}
+It is important when constructing mind-boggling tables like this one
+to ensure that every format has exactly the same number of @Code "|"
+symbols.  Otherwise the number of columns will differ from row to row.
+The names given to the entries ({@Code "A"}, {@Code "B"}, {@Code "C"},
+etc.) are quite irrelevant:  having a @Code "@Cell D" in one row and a
+@Code "@Cell D" in another does not mean that the cells will appear in
+the same column.
+@PP
+There is an asymmetry in the spiral above:  the first column
+occupies slightly more space than the other two.  This arises
+because the left margin of the leftmost column is excluded from the
+calculation of how much space is available.  This anomaly might be
+corrected some day.
+@PP
+There is a @Code "@StartHVSpan" symbol which combines the effects
+of @Code "@StartHSpan" and {@Code "@StartVSpan"}.  You need to
+use it in this arrangement:
+@ID @OneRow @Tbl
+    mv { 0.5vx }
+    aformat { @Cell @Code A | @Cell @Code B | @Cell @Code C }
+{
+@Rowa
+    A { "@StartHVSpan" }
+    B { "@HSpan" }
+    C { "@HSpan" }
+@Rowa
+    A { "@VSpan" }
+@Rowa
+    A { "@VSpan" }
+}
+The blank positions should be left empty.  For example:
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    rule { yes }
+    aformat { @Cell A | @Cell B | @Cell C | @Cell D }
+    bformat { @Cell A | @StartHVSpan @Cell i { ctr } iv { ctr } B | @HSpan | @Cell D }
+    cformat { @Cell A | @VSpan |      | @Cell D }
+{
+@Rowa
+@Rowb
+    B { CPU }
+@Rowc
+@Rowa
+}
+}
+produces
+@CD @OneRow @Tbl
+    rule { yes }
+    strut { no }
+    aformat { @Cell A | @Cell B | @Cell C | @Cell D }
+    bformat { @Cell A | @StartHVSpan @Cell i { ctr } iv { ctr } B | @HSpan | @Cell D }
+    cformat { @Cell A | @VSpan | | @Cell D }
+{
+@Rowa
+@Rowb
+    B { CPU }
+@Rowc
+@Rowa
+}
+This example illustrates how Lout apportions space in the presence of
+spanning columns.  If the spanning cell is naturally narrower than the
+cells it spans, it is widened to their size.  If it is wider (as in
+the example above), then the last spanned cell is widened to take
+up the slack.  This is why the third cell is wider than the second in the
+first row of this example.
+@End @Section
diff --git a/doc/user/tbl_summ b/doc/user/tbl_summ
new file mode 100644
index 0000000..6fed734
--- /dev/null
+++ b/doc/user/tbl_summ
@@ -0,0 +1,255 @@
+@Section
+    @Title { Summary of options }
+    @Tag { tbl_summ }
+@Begin
+@PP
+This summary applies to all @Code "@Tbl" options except the @Code format
+options described in Section {@NumberOf tbl_rows}.  Here is the complete
+list of these options, one option per line, showing its alternative
+spellings, default values (PostScript and PDF, and plain text) from the setup
+file, and allowed range of values.  Where one option is indented below
+another, it means that the indented option is a specialized version of
+the other, which affects its default value.  For more on this see below.
+@DP
+@Tbl
+    marginvertical { 0.5vx }
+    aformat { @Cell ml { 0i }               @Code A |
+	      @Cell @Code B | @Cell @Code C | @Cell mr { 0i } D }
+    bformat { @Cell ml { 0i } indent { 1f } @Code A |
+	      @Cell @Code B | @Cell @Code C | @Cell mr { 0i } D }
+    cformat { @Cell ml { 0i } indent { 2f } @Code A |
+	      @Cell @Code B | @Cell @Code C | @Cell mr { 0i } D }
+    dfont { Italic }
+    dbreak { lines }
+    dformat { @Cell ml { 0i } A | @Cell B | @Cell C | @Cell mr { 0i } D }
+    fformat { @StartHSpan @Cell ml { 0i }               @Code A |
+	      @HSpan | @HSpan | @Cell mr { 0i } D }
+    gformat { @StartHSpan @Cell ml { 0i } indent { 1f } @Code A |
+	      @HSpan | @HSpan | @Cell mr { 0i } D }
+    hformat { @StartHSpan @Cell ml { 0i } indent { 2f } @Code A |
+	      @HSpan | @HSpan | @Cell mr { 0i } D }
+{
+@Rowd
+    A { Option names }
+    B { Default in
+PS, PDF }
+    C { Default in
+plain text }
+    D { Allowed values }
+    rulebelow { yes }
+@Rowa
+    A { paint  p }
+    B { nopaint }
+    D { any colour from Section {@NumberOf colour} }
+@Rowa
+    A { background  bg }
+    D { any object }
+@Rowa
+    A { font  f }
+    D { any font e.g. @Code "Helvetica Slope -2p" }
+@Rowa
+    A { break  b }
+    D { any break e.g. @Code "ragged nohyphen" }
+@Rowa
+    A { width  w }
+    D { @Code "expand" or any length e.g. @Code 5c }
+@Rowa
+    A { height  h }
+    D { any length e.g. @Code 3c }
+@Rowa
+    A { indent  i }
+    D { {@Code left}, {@Code ctr}, {@Code mctr}, {@Code right}, or any length }
+@Rowa
+    A { indentvertical  iv }
+    D { {@Code top}, {@Code ctr}, {@Code mctr}, {@Code foot}, or any length }
+@Rowa
+    A { strut  s }
+    B { yes }
+    C { yes }
+    D { {@Code no}, {@Code yes}, or any length }
+@Rowa
+    A { struthorizontal  sh }
+    B { no }
+    C { no }
+    D { {@Code no}, {@Code yes}, or any length }
+@Rowa
+@Rowa
+    A { margin  m }
+    B { }
+    C { }
+    D { any length }
+@Rowb
+    A { marginhorizontal  mh }
+    B { 0.6f }
+    C { 2s }
+    D { any length }
+@Rowc
+    A { marginleft  ml }
+    D { any length }
+@Rowc
+    A { marginright  mr }
+    D { any length }
+@Rowb
+    A { marginvertical  mv }
+    B { 0.3f }
+    C { 2f }
+    D { any length }
+@Rowc
+    A { marginabove  ma }
+    D { any length }
+@Rowc
+    A { marginbelow  mb }
+    D { any length }
+@Rowa
+@Rowa
+    A { rule  r }
+    B { no }
+    C { no }
+    D { {@Code no}, {@Code yes}, {@Code single}, or {@Code double} }
+@Rowb
+    A { rulehorizontal  rh }
+    D { {@Code no}, {@Code yes}, {@Code single}, or {@Code double} }
+@Rowc
+    A { ruleabove  ra }
+    D { {@Code no}, {@Code yes}, {@Code single}, or {@Code double} }
+@Rowc
+    A { rulebelow  rb }
+    D { {@Code no}, {@Code yes}, {@Code single}, or {@Code double} }
+@Rowb
+    A { rulevertical  rv }
+    D { {@Code no}, {@Code yes}, {@Code single}, or {@Code double} }
+@Rowc
+    A { ruleleft  rl }
+    D { {@Code no}, {@Code yes}, {@Code single}, or {@Code double} }
+@Rowc
+    A { ruleright  rr }
+    D { {@Code no}, {@Code yes}, {@Code single}, or {@Code double} }
+@Rowa
+@Rowa
+    A { rulewidth  rw }
+    B { 0.05f }
+    D { any length }
+@Rowb
+    A { rulehorizontalwidth  rhw }
+    C { 1f }
+    D { any length }
+@Rowc
+    A { ruleabovewidth  raw }
+    D { any length }
+@Rowc
+    A { rulebelowwidth  rbw }
+    D { any length }
+@Rowb
+    A { ruleverticalwidth  rvw }
+    C { 1s }
+    D { any length }
+@Rowc
+    A { ruleleftwidth  rlw }
+    D { any length }
+@Rowc
+    A { rulerightwidth  rrw }
+    D { any length }
+@Rowa
+@Rowa
+    A { rulegap  rg }
+    B { 0.15f }
+    D { any length }
+@Rowb
+    A { rulehorizontalgap  rhg }
+    C { 0f }
+    D { any length }
+@Rowc
+    A { ruleabovegap  rag }
+    D { any length }
+@Rowc
+    A { rulebelowgap  rbg }
+    D { any length }
+@Rowb
+    A { ruleverticalgap  rvg }
+    C { 0s }
+    D { any length }
+@Rowc
+    A { ruleleftgap  rlg }
+    D { any length }
+@Rowc
+    A { rulerightgap  rrg }
+    D { any length }
+@Rowa
+@Rowa
+    A { rulecolour  rulecolor  rc }
+    B { black }
+    D { any colour from Section {@NumberOf colour} }
+@Rowg
+    A { rulehorizontalcolour  rulehorizontalcolor  rhc }
+    D { any colour from Section {@NumberOf colour} }
+@Rowh
+    A { ruleabovecolour  ruleabovecolor  rac }
+    D { any colour from Section {@NumberOf colour} }
+@Rowh
+    A { rulebelowcolour  rulebelowcolor  rbc }
+    D { any colour from Section {@NumberOf colour} }
+@Rowg
+    A { ruleverticalcolour  ruleverticalcolor  rvc }
+    D { any colour from Section {@NumberOf colour} }
+@Rowh
+    A { ruleleftcolour  ruleleftcolor  rlc }
+    D { any colour from Section {@NumberOf colour} }
+@Rowh
+    A { rulerightcolour  rulerightcolor  rrc }
+    D { any colour from Section {@NumberOf colour} }
+@Rowa
+@Rowa
+    A { ruleplainchar  rpc }
+    C { . }
+    D { any simple word e.g. @Code + }
+    rulebelow { yes }
+}
+@DP
+There are seven places where these options may be given, counting the
+setup file (Section {@NumberOf tbl_setu}).  To make it clear that this
+summary applies to any of these options, we illustrate the seven places
+with a fictitious option called {@Code option}:
+@ID @OneRow @Code @Verbatim {
+@Use { @TblSetup
+    option { 1 }
+}
+
+@Tbl
+    option { 2 }
+    aoption { 3 }
+    aformat { @Cell option { 4 } A }
+{
+    @Rowa
+        option { 5 }
+    @Row
+        option { 6 }
+        format { @Cell option { 7 } A }
+}
+}
+Each occurrence of @Code option is of course optional.  If there are
+none, the default value given in the table above applies.  For any other
+combination of absent and present options, the value that applies is the
+present and relevant one with the largest number in the illustration
+just above.  But before applying this rule, any general options must be
+thought of as being replaced by their more specialized versions:
+@ID @Code "rulehorizontal { yes }"
+is equivalent to
+@ID @Code @Verbatim {
+ruleabove { yes }
+rulebelow { yes }
+}
+for example.  Conflicts are resolved in the logical way:
+@ID @Code @Verbatim {
+margin { 0.5f }
+marginleft { 0.0f }
+}
+is equivalent to the four specialized options
+@ID @Code @Verbatim {
+marginabove { 0.5f }
+marginbelow { 0.5f }
+marginleft { 0.0f }
+marginright { 0.5f }
+}
+General options are really just abbreviations for sets of specialized
+options.
+@End @Section
diff --git a/doc/user/tbl_widt b/doc/user/tbl_widt
new file mode 100644
index 0000000..b2e39ad
--- /dev/null
+++ b/doc/user/tbl_widt
@@ -0,0 +1,84 @@
+@Section
+    @Title { Cell width and height }
+    @Tag { tbl_widt }
+@Begin
+@PP
+Lout is quite good a choosing suitable widths for cells.  It leaves
+narrow cells at their natural width, then uses paragraph breaking to
+reduce the wider cells to a common width which is as large as
+the available space allows:
+@QD @OneRow @Tbl
+    aformat { @Cell @I A | @Cell B | @Cell C }
+{
+@Rowa
+    A { Acacia }
+    B {
+Shrub or small tree with grey-green foliage and brilliant
+yellow blossom in late winter.
+}
+    C {
+Distributed widely throughout Australia except in the most arid
+parts; many varieties.
+}
+}
+This usually looks good, but if you need something else, the @Code width
+option may be used to give a particular width to a cell:
+@ID @OneRow @Code "@Cell width { 3c }"
+Here we have asked for a cell width of three centimetres; this includes
+the cell margins.  When using @Code width to fine-tune the appearance of
+a table wide enough to require paragraph breaking, it is best to use
+@Code width to make cells narrower, not wider.
+@PP
+Regrettably, there is no way to request that several cells in a row be
+given a common width equal to the width of the widest.  One simple way to
+approximate this is to give these cells the same @Code width value.  The
+@Code width option also has a special value, {@Code "expand"}.  All
+cells with @Code "width { expand }" are assigned a common width
+expand.cell.width @Index { @Code expand cell width in tables }
+equal to the maximum amount permitted by the available space.  For example,
+@ID @OneRow @Code @Verbatim {
+@QuotedDisplay @Tbl
+    width { expand }
+    paint { lightgrey }
+    aformat { @Cell A  |  @Cell B  |  @Cell C }
+{
+@Rowa
+    A { 23.56 }
+    B { 98.76 }
+    C { 65.00 }
+}
+}
+has result
+@QuotedDisplay @Tbl
+    width { expand }
+    paint { lightgrey }
+    aformat { @Cell A  |  @Cell B  |  @Cell C }
+{
+@Rowa
+    A { 23.56 }
+    B { 98.76 }
+    C { 65.00 }
+}
+We have used our usual trick of making the option apply to several cells
+by moving it to a more general level, in this case to {@Code "@Tbl"}.
+The available space can be reduced using the @Code "@Wide" symbol; if
+we replace @Code "@QuotedDisplay @Tbl" in the example above with
+@ID @OneRow @Code "@CentredDisplay 4i @Wide @Tbl"
+the result will be
+@CentredDisplay 4i @Wide @Tbl
+    width { expand }
+    paint { lightgrey }
+    aformat { @Cell A  |  @Cell B  |  @Cell C }
+{
+@Rowa
+    A { 23.56 }
+    B { 98.76 }
+    C { 65.00 }
+}
+with the total table width reduced to four inches.
+@PP
+There is an analogous @Code height option which makes a cell take on
+a particular fixed height, again including margins.  Make sure there
+is enough height in the cell to hold its entry when you use this
+option.  The @Code "expand" value is not available for height.
+@End @Section
diff --git a/doc/user/typ b/doc/user/typ
new file mode 100644
index 0000000..7ebe52f
--- /dev/null
+++ b/doc/user/typ
@@ -0,0 +1,27 @@
+@Chapter
+    @Title { Types of Documents }
+    @Tag { types }
+@Begin
+@LP
+Particular types of documents have specialized formatting requirements:
+title pages in books, abstracts in technical reports, and so on.  Lout
+provides a range of @I { document types } with the appropriate
+specialized features for
+document.types @Index { document types }
+each type.
+@PP
+There are five types:  ordinary documents, technical reports,
+books, overhead transparencies, and stand-alone illustrations.  The
+features of all other chapters are available within each document type,
+but the features of one type are not available within other types.
+@BeginSections
+@Include { typ_ordi }
+@Include { typ_repo }
+@Include { typ_book }
+@Include { typ_over }
+@Include { typ_illu }
+@Include { typ_plai }
+@Include { typ_apdf }
+@Include { typ_orga }
+@EndSections
+@End @Chapter
diff --git a/doc/user/typ_apdf b/doc/user/typ_apdf
new file mode 100644
index 0000000..3203384
--- /dev/null
+++ b/doc/user/typ_apdf
@@ -0,0 +1,21 @@
+@Section
+   @Title { PDF (Adobe Portable Document Format) documents }
+   @Tag { pdf }
+@Begin
+@PP
+You can get Lout to produce PDF (Adobe Portable Document Format) output as
+an alternative to PostScript, by adding @Code "-PDF" to the command line
+like this:
+pdf. @Index { PDF documents }
+@ID @Code "lout -PDF simple > simple.pdf"
+No other changes are required.
+@PP
+The PDF output is superior to PostScript in providing links:  when viewed
+with a PDF viewer, entries in tables of contents and indexes can be
+clicked on and this transports the viewer to the part of the document
+referenced by the link.  (Recent versions of PostScript support this
+feature too, but Lout's PostScript doesn't.)  However, the PDF output
+produced by Lout is inferior at graphics:  the advanced features of the
+@Code "@Diag" and @Code "@Graph" packages do not produce any output.  One
+can still format documents that contain them, but the results are disappointing.
+@End @Section
diff --git a/doc/user/typ_book b/doc/user/typ_book
new file mode 100644
index 0000000..34abde2
--- /dev/null
+++ b/doc/user/typ_book
@@ -0,0 +1,420 @@
+@Section
+   @Title { Books }
+   @Tag { books }
+@Begin
+@PP
+To produce a book, start off with the @Code book setup file and the
+books. @Index { books }
+book. @Index @Code "@Book"
+@Code "@Book" symbol:
+@ID @OneRow @Code {
+"@SysInclude { book }"
+"@Book"
+"    @Title {}"
+"    @Author {}"
+"    @Edition {}"
+"    @Publisher {}"
+"    @BeforeTitlePage {}"
+"    @OnTitlePage {}"
+"    @AfterTitlePage {}"
+"    @AtEnd {}"
+"    @InitialFont { Times Base 12p }"
+"    @InitialBreak { adjust 1.2fx hyphen }"
+"    @InitialSpace { lout }"
+"    @InitialLanguage { English }"
+"    @PageOrientation { Portrait }"
+"    @PageHeaders { Titles }"
+"    @ColumnNumber { 1 }"
+"    @FirstPageNumber { 1 }"
+"    @IntroFirstPageNumber { 1 }"
+"    @OptimizePages { No }"
+"//"
+}
+This shows all the options of @Code "@Book" with their default values.  As
+usual, these options may be given in any order, and only those
+to be changed need be given at all.  The meaning of the
+@Code "//" symbol after the last option is beyond our scope, but total
+disaster will ensue if it is forgotten.
+@PP
+The {@Code "@Title"}, {@Code "@Author"}, and {@Code "@Edition"} options
+will appear on the title page, in the @Code "clines" paragraph breaking
+style which centres each line (Section {@NumberOf paras}).  The
+@Code "@Publisher" option will appear at the foot of the title page.
+@PP
+The {@Code "@BeforeTitlePage"} option will come out on the page (or
+pages) preceding the title page.  This is where publishers
+advertise other books of a similar kind, perhaps from a series.
+@PP
+If {@Code "@OnTitlePage"} is given it will replace the title page
+that usually appears, superseding the {@Code "@Title"}, {@Code "@Author"},
+{@Code "@Edition"}, and @Code "@Publisher" options in the process.
+@PP
+The {@Code "@AfterTitlePage"} option will come out on the page
+(or pages) following the title page.  This is where publishers
+traditionally put copyright notices, information about production,
+and cataloguing-in-publication data.  If this option is empty or
+omitted, there will be no such pages.
+@PP
+The {@Code "@AtEnd"} option will come out on a single unnumbered page
+with no page headers or footers, and using the same margins as for even
+pages, after the very last page of the book; even after the index if
+there is one.  It is intended to make it possible to include a back
+cover, so @Code "@PageOf last.page" (Section {@NumberOf cross}) does
+not take account of any @Code "@AtEnd" page.
+@PP
+The remaining options are a selection of setup file options (Section
+{@NumberOf setup}) that frequently need to be changed.  If your changes
+to the overall formatting are confined to these options, you can change
+them here and avoid having your own setup file.  If you already have
+your own setup file, change them in either place and omit them in
+the other.
+@PP
+@Code "@InitialFont" is the font of the bulk of the book,
+and should contain a family, a face, and a size.  The default
+value selects the Times family, the Base face, and the 12 point size.
+@PP
+@Code "@InitialBreak" controls the behaviour of paragraph breaking in
+the bulk of the book.  It should have three parts:  a paragraph
+breaking style ({@Code adjust}, {@Code ragged}, etc.), an inter-line
+spacing ({@Code "1.2fx"} for single spacing, {@Code "2.4fx"} for
+double spacing, and so on), and either @Code "hyphen" or
+@Code "nohyphen" for turning hyphenation on or off.  It may also
+have @Code "nobreakfirst" or @Code "nobreaklast" (or both), meaning
+to disallow a page break after the first line of a paragraph, or
+before the last, respectively.
+@PP
+@Code "@InitialSpace" determines how Lout treats white space
+between two objects, as described in Section
+{@NumberOf white}.  @Code "@InitialLanguage" determines the
+language of the bulk of the book.
+@PP
+@Code "@PageOrientation" determines the orientation of the page.  Its
+value may be {@Code Portrait} (the default), {@Code Landscape},
+{@Code ReversePortrait}, or {@Code ReverseLandscape}.  See
+Section {@NumberOf pagesize} for further details.
+@PP
+@Code "@PageHeaders" determines the appearance of page headers and
+footers.  Its value may be {@Code None},
+{@Code Simple}, {@Code Titles}, or {@Code NoTitles}.  Section
+{@NumberOf headers} has the details, but just briefly, {@Code None}
+and {@Code Simple} are not really suitable for books, @Code Titles
+produces full running titles as in the present document, and
+@Code "NoTitles" is like @Code "Titles" with the running titles
+omitted, leaving just the page numbers.
+@PP
+@Code "@ColumnNumber" is the number of columns per page in the bulk of
+the book, and may be anything from {@Code 1} (the default value) to
+{@Code 10}.  Irrespective of its value, all prefatory material, all
+chapter and appendix headings, and all figures and tables will be
+printed full width.  There is a separate @Code "@IndexColumnNumber"
+option in the setup file which determines the number of columns in
+the index (Section {@NumberOf indexes}).
+@PP
+@Code "@FirstPageNumber" is the page number to be given to the first
+non-introductory page.  @Code "@IntroFirstPageNumber" is the
+page number of the first introductory page; it will usually appear
+in Roman but must be given in Arabic.
+@PP
+Lout ordinarily places lines onto a page until space runs out, then moves
+to the next page and so on.  This often produces ugly empty spaces at
+the bottoms of pages preceding large unbreakable displays.  Setting the
+@Code "@OptimizePages" option to {@Code "Yes"} causes Lout to examine the
+overall situation and try to minimize the ugliness, using the @TeX
+optimal paragraph breaking algorithm.  It takes two runs to do this,
+with intermediate results stored in Lout's cross reference database
+(Section {@NumberOf cross}); so deleting file {@Code lout.li} will reset
+it, which might be wise after major changes.  It is possible for the
+optimizer to cycle, never settling on a single final best version; this
+is usually caused by footnotes or floating figures inserted at points
+which end up near page boundaries.
+@PP
+After the compulsory @Code "//" comes an optional preface:
+preface. @Index @Code "@Preface"
+@ID @OneRow @Code {
+"@Preface"
+"    @Title { About this book }"
+"@Begin"
+"@PP"
+"..."
+"@End @Preface"
+}
+Since the title of most prefaces is simply Preface, that is the default
+value in English of the @Code "@Title" option.  After the preface there
+will automatically appear a table of contents listing the introduction,
+chapters, sections, subsections, appendices, sub-appendices, bibliography,
+and index as appropriate.
+@PP
+The pages up to this point will be numbered in lower case Roman
+numerals; subsequent pages will be numbered in Arabic starting from
+the @Code "@FirstPageNumber" option of {@Code "@Book"}.  There is
+a setup file option for changing this to a single numbering sequence
+(see below).
+@PP
+Next comes an optional abbreviations sections, exactly like the
+preface except that its name is @Code "@Abbreviations" and the
+abbreviations. @Index @Code "@Abbreviations"
+default title in English is Abbreviation.  There is no support for
+what goes inside; you need to use a list or table to lay out the
+abbreviations, in the usual way.
+@PP
+Next comes an optional introduction, exactly like the preface except that
+its name is @Code "@Introduction" and the default title in English is
+introduction. @Index @Code "@Introduction"
+Introduction:
+@ID @OneRow @Code {
+"@Introduction"
+"@Begin"
+"@PP"
+"..."
+"@End @Introduction"
+}
+After that comes a sequence of chapters in the usual style:
+chapter. @Index @Code "@Chapter"
+@ID @OneRow @Code {
+"@Chapter"
+"    @Title { Australian Native Plants }"
+"@Begin"
+"@PP"
+"..."
+"@End @Chapter"
+}
+No @Code "@BeginChapters" or @Code "@EndChapters" symbols are
+beginchapters. @Index @Code "@BeginChapters"
+endchapters. @Index @Code "@EndChapters"
+needed, because these chapters are not inside any other large-scale
+structure symbol.  Within a chapter, there may be a sequence of sections,
+each introduced by {@Code "@Section"}, all bracketed
+section.books @SubIndex { in books }
+by @Code "@BeginSections" and {@Code "@EndSections"}:
+beginsections.books @SubIndex { in books }
+endsections.books @SubIndex { in books }
+@ID @OneRow @Code {
+"preceding text"
+"@BeginSections"
+"@Section ... @End @Section"
+"@Section ... @End @Section"
+"..."
+"@Section ... @End @Section"
+"@EndSections"
+}
+Within each section there may be subsections, each introduced by
+{@Code "@SubSection"}, and the sequence as a whole bracketed by
+@Code "@BeginSubSections" and {@Code "@EndSubSections"}:
+subsection.books @SubIndex { in books }
+beginsubsections.books @SubIndex { in books }
+endsubsections.books @SubIndex { in books }
+@ID @OneRow @Code {
+"preceding text"
+"@BeginSubSections"
+"@SubSection ... @End @SubSection"
+"@SubSection ... @End @SubSection"
+"..."
+"@SubSection ... @End @SubSection"
+"@EndSubSections"
+}
+The subsections may contain sub-subsections, but
+subsubsection.books @SubIndex { in books }
+beginsubsubsections.books @SubIndex { in books }
+endsubsubsections.books @SubIndex { in books }
+there are no sub-sub-subsections.
+@PP
+After the chapters comes an optional sequence of appendices.  Each
+is introduced by @Code "@Appendix" in the usual way:
+appendix.books @SubIndex { in books }
+@ID @OneRow @Code {
+"@Appendix"
+"    @Title { Climatic Regions of Australia }"
+"@Begin"
+"@PP"
+"..."
+"@End @Appendix"
+}
+No @Code "@BeginAppendices" or @Code "@EndAppendices" symbols are
+beginappendices.books @SubIndex { in books }
+endappendices.books @SubIndex { in books }
+needed, because (like chapters) these appendices do not lie inside
+any other large-scale structure symbol.  The appendices are numbered
+A, B, C, etc., as is conventional for them.  Within each appendix
+there may be a sequence of subappendices, obtained with the
+@Code "@SubAppendix" symbol and bracketed by
+subappendix.books @SubIndex { in books }
+@Code "@BeginSubAppendices" and {@Code "@EndSubAppendices"}:
+beginsubappendices.books @SubIndex { in books }
+endsubappendices.books @SubIndex { in books }
+@ID @OneRow @Code {
+"preceding text"
+"@BeginSubAppendices"
+"@SubAppendix ... @End @SubAppendix"
+"@SubAppendix ... @End @SubAppendix"
+"..."
+"@SubAppendix ... @End @SubAppendix"
+"@EndSubAppendices"
+}
+There are sub-subappendices following the same pattern, but no
+subsubappendix.books @SubIndex { in books }
+beginsubsubappendices.books @SubIndex { in books }
+endsubsubappendices.books @SubIndex { in books }
+sub-sub-subappendices.
+@PP
+The book ends with the last chapter or appendix; any reference list or
+index will be appended automatically.  Although we have described how to
+create books as though everything was in one large file, in practice it
+is much better to divide the book into multiple files, following the
+method given in Section {@NumberOf organizing}.
+@PP
+In addition to the {@Code "@Title"} option, each large-scale structure
+symbol (i.e. {@Code "@Preface"}, {@Code "@Introduction"}, {@Code "@Chapter"},
+{@Code "@Section"}, {@Code "@SubSection"}, {@Code "@SubSubSection"},
+{@Code "@Appendix"}, {@Code "@SubAppendix"}, and {@Code "@SubSubAppendix"})
+has a @Code "@Tag" option for cross referencing (Section {@NumberOf cross}),
+an @Code "@InitialLanguage" option for changing the language of that
+part of the document, and a @Code "@RunningTitle" option which will be
+used in place of @Code "@Title" in running headers if given.  This last
+is useful when the full title is rather long.
+@PP
+The @Code "@Chapter" symbol has three additional options for dividing
+parts. @Index { parts of books }
+the book into parts:
+part.number @Index @Code "@PartNumber"
+part.title @Index @Code "@PartTitle"
+part.text @Index @Code "@PartText"
+@ID @OneRow @Code {
+"@Chapter"
+"    @PartNumber { Part A }"
+"    @PartTitle { The Ancient World }"
+"    @PartText { ... }"
+}
+Any chapter with a non-empty @Code "@PartTitle" option will become the
+first chapter of a part.  It will be preceded by two pages containing the
+part number, title, and text, and there will also be an entry
+made in the table of contents.  @Code "@PartNumber" and @Code "@PartText"
+may be omitted.  Parts are @I not numbered automatically:  you
+have to supply your own numbers or letters as shown above.
+@PP
+The features described in other chapters are all available within
+books.  A table of contents and index will appear automatically, and
+you will need to change the setup file to avoid them.  Endnotes will
+appear at the end of the enclosing preface, introduction, chapter, or
+appendix.  The numbering of figures and tables includes a chapter or
+appendix number:  the first figure of Appendix C will be Figure C.1,
+and so on.  Figures and tables within the preface or introduction are
+numbered 1, 2, 3, etc.  A figure or table will never appear on the
+same page as the beginning of a chapter or appendix.  References work
+as described in Chapter {@NumberOf biblio}.  As explained there, it is
+possible to have a list of references at the end of each chapter as well
+as at the end of the book.
+@PP
+Within the @Code "book" setup file there is a @Code "@BookSetup"
+booksetup. @Index @Code "@BookSetup"
+symbol whose options control the appearance of features specific to books
+(in other words, the features described in this section).  Here is a
+representative sample of these options, showing their default values:
+@ID @OneRow @Code {
+"@Use { @BookSetup"
+"    # @TitlePageFont { Helvetica Base }"
+"    # @SeparateIntroNumbering { Yes }"
+"    # @PrefaceAfterContents { No }"
+"    # @ReferencesBeforeAppendices { No }"
+"    # @ChapterStartPages { Any }"
+"    # @ChapterWord { chapter }"
+"    # @ChapterNumbers { Arabic }"
+"    # @ChapterHeadingFont { Bold 2.00f }"
+"    # @ChapterHeadingBreak { ragged 1.2fx nohyphen }"
+"    # @ChapterHeadingFormat { number @DotSep title }"
+"    # @AboveChapterGap { 3.00f }"
+"    # @ChapterInContents { Yes }"
+"}"
+}
+Section {@NumberOf setup} explains how to make your own setup file and
+change its options.  @Code "@TitlePageFont" is the font used on the title
+title.page.font. @Index @Code "@TitlePageFont"
+page of the book, not including a size.  @Code "@ChapterStartPages"
+determines what kinds of pages chapters and other major components of the
+book may begin on, and may be {@Code Any}, {@Code Odd}, or {@Code Even},
+meaning any page, odd-numbered pages only, or even-numbered pages
+only.  @Code "@SeparateIntroNumbering"
+separate.intro.numbering @Index @Code "@SeparateIntroNumbering"
+determines whether the introductory part of the book is to have a
+separate numbering sequence or not.  @Code "@ReferencesBeforeAppendices"
+references.before.appendices @Index @Code "@ReferencesBeforeAppendices"
+determines whether any final list of references appears before or
+after any appendices.  @Code "@ChapterWord" determines
+the word used in chapter titles; its default value, {@Code "chapter"},
+produces `Chapter' in the current language.  The other six options control
+the appearance of chapters, and there are similar options for controlling
+the other large-scale structure symbols.
+@PP
+@Code "@ChapterNumbers" determines how chapters will be numbered, and may
+be @Code { None }, @Code { Arabic }, @Code { Roman }, @Code { UCRoman },
+@Code { Alpha }, or @Code { UCAlpha }.  The default value is @Code Arabic
+for chapters and also for all large-scale structure symbols except
+appendices, for which it is {@Code UCAlpha}.  This produces the appendices
+numbered in upper-case letters (A, B, C, etc.) that were mentioned earlier.
+@PP
+@Code "@ChapterHeadingFont" is the font used for chapter headings.  The
+default value shown above produces the bold face of the initial font
+family, at twice the initial size.  A family name is acceptable
+here as well.  @Code "@ChapterHeadingBreak" is the break style for
+chapter headings.
+@PP
+@Code "@ChapterHeadingFormat" allows you to change
+the format of the heading.  The symbol @Code "number" within it will
+be replaced by the number of the chapter (actually including the word
+Chapter as well in the current language, e.g. {@Code "Chapter 12"}); the
+symbol @Code "title" within it will be replaced by the title.  So you could
+write, say,
+@ID @Code
+"@ChapterHeadingFormat { @Box paint { lightgrey } { number @DP title } }"
+to get the title below the number, both enclosed in a box.  The default
+value uses the @Code "@DotSep" symbol from Section {@NumberOf headers}
+to produce the number and title separated by a dot and two spaces, roughly
+the same as
+@ID @Code "@ChapterHeadingFormat { number.  title }"
+except when there is no number.  This option is applied
+to other major headings, in the preface, introduction, table of
+contents, appendices, reference list, and index.  In all these other
+cases, @Code "number" is an empty object, except for appendices, when it
+contains @Code "Appendix A" or whatever.
+@PP
+There is a @Code "@PartHeadingFormat" option for determining the
+format of part headings.  It works in the same way as
+{@Code "@ChapterHeadingFormat"}, with @Code "number" and @Code "title"
+symbols standing for the relevant @Code "@PartNumber" and @Code "@PartTitle"
+options.  The default value is
+@ID @Code "@PartHeadingFormat { @CD number @DP @CD title }"
+which centres the number and title.  The default paragraph breaking
+style is {@Code "clines"}, but you may place a @Code "@Break" symbol
+within @Code "@PartHeadingFormat" to change this.
+@PP
+The example of boxed titles for chapters given above suffers from two
+practical deficiencies.  First, the box won't extend right across the
+page, and second, when there is no @Code "number" we don't want the
+@Code "@DP" either.  Here is a value for @Code "@ChapterHeadingFormat"
+that solves both of these problems and looks good in practice:
+@ID @OneCol @Code {
+"@ChapterHeadingFormat {"
+"    number @Case {"
+"        {} @Yield @Box paint { lightgrey } @HExpand { title }"
+"        else @Yield @Box paint { lightgrey } @HExpand { number @DP title }"
+"    }"
+"}"
+}
+The @Code "@Case" symbol (Expert's Guide @Cite { $kingston1995lout.expert })
+distinguishes between the cases where @Code "number" is empty and non-empty;
+the @Code "@HExpand" symbol expands the horizontal space occupied by the
+heading to the maximum possible, so that when the box is drawn around it
+it will occupy the full page width.  The format can be as
+complicated as you like, and there is no need to squeeze it all onto
+one line; as always, the end of a line is the same as one space.
+@PP
+Every chapter and appendix begins on a new page.  @Code "@AboveChapterGap"
+determines how much space is left blank above the chapter title; the
+default value is three times the initial font size.  There are similar
+options for other large-scale structure symbols, which determine how
+much space is left before each one.
+@PP
+@Code "@ChapterInContents" determines whether or not an entry is made in
+the table of contents for each chapter; it may be @Code Yes or {@Code No},
+but would always be {@Code Yes}.  The default value of the corresponding
+options for sub-subsections and sub-subappendices, however, is {@Code No}.
+@End @Section
diff --git a/doc/user/typ_illu b/doc/user/typ_illu
new file mode 100644
index 0000000..532b42b
--- /dev/null
+++ b/doc/user/typ_illu
@@ -0,0 +1,85 @@
+@Section
+   @Title { Stand-alone illustrations }
+   @Tag { illustrations }
+@Begin
+@PP
+This section describes how to use Lout to produce an illustration for
+stand.alone.illustrations. @Index { stand-alone illustrations }
+illustrations. @Index { illustrations }
+inclusion in some other document, which may itself be a Lout document
+but need not be.  The opposite process, the inclusion of an illustration
+in a Lout document, is the subject of Section {@NumberOf include}.
+@PP
+Suppose you want to produce the following logo
+for inclusion in some other document:
+@ID {
+45d @Rotate @CurveBox { ARMY @LP 180d @Rotate ARMY }
+}
+This is just an object, and it is not hard to make it using Lout's
+graphics features:
+@ID @Code "45d @Rotate @CurveBox { ARMY @LP 180d @Rotate ARMY }"
+The problem is that objects ordinarily come out on pages with margins,
+page numbers, and so forth, which we don't want here.  The solution
+is to use the illustration document type, whose setup file, curiously
+enough, is called {@Code "picture"}:
+illustration. @Index @Code "@Illustration"
+@ID @OneRow @Code {
+"@SysInclude { picture }"
+"@Illustration {"
+"    45d @Rotate @CurveBox { ARMY @LP 180d @Rotate ARMY }"
+"}"
+}
+After the usual @Code "@SysInclude" line comes one @Code "@Illustration"
+symbol.  Following it is an arbitrary object which becomes the entire
+result, with no pages and no margins, ready for inclusion in some other
+document as an illustration.
+@PP
+The @Code "@Illustration" symbol has options for setting the initial
+font, paragraph breaking style, colour, and language.  Here they are
+with their default values:
+@ID @OneRow @Code {
+"@Illustration"
+"    @InitialFont { Times Base 12p }"
+"    @InitialBreak { adjust 1.2fx hyphen }"
+"    @InitialSpace { lout }"
+"    @InitialLanguage { English }"
+"    @InitialColour { black }"
+"{"
+"    ..."
+"}"
+}
+You can specify any colour from the list in Section {@NumberOf colour},
+for example {@Code blue}, and then your illustration will have that
+colour wherever it is included.
+@PP
+Because there are no pages, the width and height of the result are
+indeterminate, depending on how large the object turns out to be.  This
+makes things very awkward for filled paragraphs and centring, which depend
+on knowing how much space is available to be occupied.  So you should either
+avoid filled paragraphs and all displays and lists altogether in
+illustrations, or else enclose your object in a @Code "@Wide" symbol:
+wide @RawIndex { @Code "@Wide" }
+wide.illustrations @SubIndex { with illustrations }
+@ID @OneRow @Code {
+"@Illustration 5c @Wide {"
+"    ..."
+"}"
+}
+to make clear how wide you want your illustration to be.
+@PP
+The technical name for a file containing a stand-alone illustration
+encapsulated.postscript @Index { encapsulated PostScript file }
+eps @Index { EPS file }
+is `encapsulated PostScript file' or `EPS file' for short.  To get
+Lout to produce an encapsulated PostScript file instead of an ordinary
+PostScript file, you have to use the @Code "-EPS" Unix command line
+flag.  For example, suppose the Lout file containing our example
+illustration is called {@Code "army"}; then the appropriate Unix
+command for formatting it is
+@ID @Code "lout -EPS army > army.eps"
+An EPS file is supposed to contain only one `page', so Lout will refuse
+to generate any second or subsequent pages when the @Code "-EPS" flag
+is given.  There is also a minor difference in format between ordinary
+and encapsulated PostScript files, which is why the @Code "-EPS" flag
+is needed at all.
+@End @Section
diff --git a/doc/user/typ_ordi b/doc/user/typ_ordi
new file mode 100644
index 0000000..9fbd07a
--- /dev/null
+++ b/doc/user/typ_ordi
@@ -0,0 +1,313 @@
+@Section
+   @Title { Ordinary documents }
+   @Tag { ordinary }
+@Begin
+@PP
+Ordinary documents are the simplest kind, consisting of a plain sequence
+ordinary. @Index { ordinary documents }
+of numbered pages.  To produce an ordinary document, use the @Code doc
+setup file and the @Code "@Doc" symbol:
+doc. @Index @Code "@Doc"
+@ID @OneRow @Code {
+"@SysInclude { doc }"
+"@Doc @Text @Begin"
+"..."
+"@End @Text"
+}
+where @Code ... stands for the body of your document.  This is the
+arrangement from Section {@NumberOf start} for getting
+started.  Alternatively, you can begin with
+@Code "@Document" instead of {@Code "@Doc"}:
+document. @Index @Code "@Document"
+@ID @OneRow @Code {
+"@SysInclude { doc }"
+"@Document"
+"    @InitialFont { Times Base 12p }"
+"    @InitialBreak { adjust 1.2fx hyphen }"
+"    @InitialSpace { lout }"
+"    @InitialLanguage { English }"
+"    @PageOrientation { Portrait }"
+"    @PageHeaders { Simple }"
+"    @FirstPageNumber { 1 }"
+"    @ColumnNumber { 1 }"
+"    @OptimizePages { No }"
+"    @Unpaginated { No }"
+"//"
+"@Text @Begin"
+"..."
+"@End @Text"
+}
+This shows all the options of {@Code "@Document"}, with their default
+values.  As usual with options, the options of {@Code "@Document"}
+may be given in any order, and only the ones that need to be changed
+need be given at all.  Notice the @Code "//" after the last option.  Its
+meaning is beyond our
+"//" @Index { @Code "//" symbol }
+scope, but total disaster will ensue if it is forgotten.  The @Code "@Doc"
+symbol is an abbreviation for {@Code "@Document //"}, which is why you don't
+need @Code "//" with {@Code "@Doc"}.
+@PP
+The eight options are a selection of setup file options (Section
+{@NumberOf setup}) that frequently need to be changed.  If your changes
+to the overall formatting are confined to these options, you can change
+them here and avoid having your own setup file.  If you already have
+your own setup file, change them in either place and omit them in
+the other.
+@PP
+@Code "@InitialFont" is the font of the bulk of the document,
+and should contain a family, a face, and a size.  The default
+value selects the Times family, the Base face, and the 12 point size.
+@PP
+@Code "@InitialBreak" controls the behaviour of paragraph breaking in
+the bulk of the document.  It should have three parts:  a paragraph
+breaking style ({@Code adjust}, {@Code ragged}, etc.), an inter-line
+spacing ({@Code "1.2fx"} for single spacing, {@Code "2.4fx"} for
+double spacing, and so on), and either @Code "hyphen" or @Code "nohyphen"
+for turning hyphenation on or off.  It may also have @Code "nobreakfirst"
+or @Code "nobreaklast" (or both), meaning to disallow a page break after
+the first line of a paragraph, or before the last, respectively.
+@PP
+@Code "@InitialSpace" determines how Lout treats white space between
+two objects, as described in Section
+{@NumberOf white}.  @Code "@InitialLanguage" determines the language
+of the bulk of the document.
+@PP
+@Code "@PageOrientation" determines the orientation of the page.  Its
+value may be {@Code Portrait} (the default), {@Code Landscape},
+{@Code ReversePortrait}, or {@Code ReverseLandscape}.  See
+Section {@NumberOf pagesize} for further details.
+@PP
+@Code "@PageHeaders" determines the appearance of page headers and
+footers throughout the document, and may be {@Code None},
+{@Code Simple}, {@Code Titles}, or {@Code NoTitles}.  Section
+{@NumberOf headers} has the details, but just briefly, {@Code None}
+means no page headers at all, {@Code Simple} means a
+page number between hyphens at the top of each page except the first,
+@Code Titles produces full running titles as in this guide,
+and @Code "NoTitles" is like @Code "Titles" with the running titles
+omitted, leaving just the page numbers.
+@PP
+@Code "@FirstPageNumber" is the page number given to the first page.
+@PP
+@Code "@ColumnNumber" is the number of columns per page in the bulk of
+the document, and may be anything from {@Code 1} (the default value) to
+{@Code 10}.  It is possible to produce full-width ordinary
+text in a multi-column document, using the @Code "@FullWidth"
+full.width. @Index @Code "@FullWidth"
+symbol:
+@ID @OneRow @Code {
+"@SysInclude { doc }"
+"@Document"
+"    @ColumnNumber { 2 }"
+"//"
+"@Text @Begin"
+"@FullWidth {"
+"@CentredDisplay @Heading { NOTICE TO TRESPASSERS }"
+"}Trespassers are hereby notified that, ..."
+"@End @Text"
+}
+This produces a full-width heading above a two-column body.  The word
+@Code Trespassers has been placed immediately after the closing brace
+of @Code "@FullWidth" because (regrettably) any space here will appear
+before @Code Trespassers in the output.  Alternatively you could use
+a paragraph symbol:
+@ID @OneRow @Code {
+"@FullWidth {"
+"@CentredDisplay @Heading { NOTICE TO TRESPASSERS }"
+"}"
+"@PP"
+"Trespassers are hereby notified that, ..."
+}
+You can have several @Code "@FullWidth" symbols,
+producing full-width text wherever you want.  Just be aware that
+@Code "@FullWidth" always causes a fresh page to be begun, it will never
+appear on the same page as a figure or table, and it is not able to hold
+a table of contents, a section, or an appendix.
+@PP
+Lout ordinarily places lines onto a page until space runs out, then moves
+to the next page and so on.  This often produces ugly empty spaces at
+the bottoms of pages preceding large unbreakable displays.  Setting the
+@Code "@OptimizePages" option to {@Code "Yes"} causes Lout to examine the
+overall situation and try to minimize the ugliness, using the @TeX
+tex.page @SubIndex { page optimization }
+optimal paragraph breaking algorithm.  It takes two runs to do this,
+with intermediate results stored in Lout's cross reference database
+(Section {@NumberOf cross}); so deleting file {@Code lout.li} will reset
+it, which might be wise after major changes.  It is possible for the
+optimizer to cycle, never settling on a single final best
+version; this is usually caused by footnotes or floating figures inserted
+at points that end up near page boundaries.
+@PP
+The @Code "@Unpaginated" option, whose value is ignored unless plain text
+output is in effect, produces unpaginated output when changed to
+{@Code Yes} (see Section {@NumberOf plain}).
+@PP
+Within the @Code "@Text" symbol, it is possible to have a sequence
+of sections:
+section. @RawIndex @Code "@Section"
+section.ordinary @SubIndex { in ordinary documents }
+beginsections. @RawIndex @Code "@BeginSections"
+beginsections.ordinary @SubIndex { in ordinary documents }
+endsections. @RawIndex @Code "@EndSections"
+endsections.ordinary @SubIndex { in ordinary documents }
+@ID @OneRow @Code {
+"preceding text"
+"@BeginSections"
+"@Section ... @End @Section"
+"@Section ... @End @Section"
+"..."
+"@Section ... @End @Section"
+"@EndSections"
+}
+as described in Section {@NumberOf largescale}.  Within any
+section, a similar arrangement produces subsections:
+subsection. @RawIndex @Code "@SubSection"
+subsection.ordinary @SubIndex { in ordinary documents }
+beginsubsections. @RawIndex @Code "@BeginSubSections"
+beginsubsections.ordinary @SubIndex { in ordinary documents }
+endsubsections. @RawIndex @Code "@EndSubSections"
+endsubsections.ordinary @SubIndex { in ordinary documents }
+@ID @OneRow @Code {
+"preceding text"
+"@BeginSubSections"
+"@SubSection ... @End @SubSection"
+"@SubSection ... @End @SubSection"
+"..."
+"@SubSection ... @End @SubSection"
+"@EndSubSections"
+}
+Within any subsection, there may be sub-subsections, obtained
+using {@Code "@BeginSubSubSections"}, {@Code "@SubSubSection"},
+subsubsection. @RawIndex @Code "@SubSubSection"
+subsubsection.ordinary @SubIndex { in ordinary documents }
+beginsubsubsections. @RawIndex @Code "@BeginSubSubSections"
+beginsubsubsections.ordinary @SubIndex { in ordinary documents }
+endsubsubsections. @RawIndex @Code "@EndSubSubSections"
+endsubsubsections.ordinary @SubIndex { in ordinary documents }
+and {@Code "@EndSubSubSections"}.  There are no sub-sub-subsections.
+@PP
+Also within the @Code "@Text" symbol only, there may be a sequence of
+appendices:
+appendix. @RawIndex @Code "@Appendix"
+appendix.ordinary @SubIndex { in ordinary documents }
+beginappendices. @RawIndex @Code "@BeginAppendices"
+beginappendices.ordinary @SubIndex { in ordinary documents }
+endappendices. @RawIndex @Code "@EndAppendices"
+endappendices.ordinary @SubIndex { in ordinary documents }
+@ID @OneRow @Code {
+"preceding text"
+"@BeginAppendices"
+"@Appendix ... @End @Appendix"
+"@Appendix ... @End @Appendix"
+"..."
+"@Appendix ... @End @Appendix"
+"@EndAppendices"
+}
+These will be `numbered' A, B, C etc. as is conventional.  Within any
+appendix there may be a sequence of subappendices, obtained in the
+usual way using  {@Code "@BeginSubAppendices"}, {@Code "@SubAppendix"},
+subappendix. @RawIndex @Code "@SubAppendix"
+subappendix.ordinary @SubIndex { in ordinary documents }
+beginsubappendices. @RawIndex @Code "@BeginSubAppendices"
+beginsubappendices.ordinary @SubIndex { in ordinary documents }
+endsubappendices. @RawIndex @Code "@EndSubAppendices"
+endsubappendices.ordinary @SubIndex { in ordinary documents }
+and {@Code "@EndSubAppendices"}.  There are sub-subappendices as well,
+following the same pattern, but no sub-sub-subappendices.
+subsubappendix. @RawIndex @Code "@SubSubAppendix"
+subsubappendix.ordinary @SubIndex { in ordinary documents }
+beginsubsubappendices. @RawIndex @Code "@BeginSubSubAppendices"
+beginsubsubappendices.ordinary @SubIndex { in ordinary documents }
+endsubsubappendices. @RawIndex @Code "@EndSubSubAppendices"
+endsubsubappendices.ordinary @SubIndex { in ordinary documents }
+@PP
+In addition to the {@Code "@Title"} option, each large-scale structure
+symbol ({@Code "@Section"}, {@Code "@SubSection"}, {@Code "@SubSubSection"},
+{@Code "@Appendix"}, {@Code "@SubAppendix"}, and {@Code "@SubSubAppendix"})
+has a @Code "@Tag" option for cross referencing (Section {@NumberOf cross}),
+an @Code "@InitialLanguage" option for changing the language of that part
+of the document, and a @Code "@RunningTitle" option which will be used in
+place of @Code "@Title" in running headers if given.  @Code "@RunningTitle"
+is useful when the full title is rather long.
+@PP
+The features described in other chapters are all available within
+ordinary documents.  Endnotes and references appear automatically at
+the end of the document.  Figures are labelled Figure 1, Figure 2,
+etc., and tables are labelled Table 1, Table 2, etc.
+@PP
+To get a table of contents, set the @Code "@MakeContents" option in
+the setup file to {@Code Yes}, and insert the symbol
+@Code "@ContentsGoesHere" at the point where you would like the
+contents.goes.here. @Index @Code "@ContentsGoesHere"
+table of contents to appear, anywhere before the first section:
+@ID @OneRow @Code {
+"@SysInclude { doc }"
+"@Text @Begin"
+"@CentredDisplay @Heading { Safety Procedures }"
+"@Heading { Contents }"
+"@DP"
+"@ContentsGoesHere"
+"@DP"
+"..."
+"@End @Text"
+}
+You must supply your own heading, as well as paragraph symbols
+before and after.  Regrettably, @Code "@ContentsGoesHere" may
+not be placed inside a display, nor inside {@Code "@FullWidth"}.
+@PP
+To get an index, set the @Code "@MakeIndex" option in the setup file
+to {@Code Yes}, and follow the instructions in Section
+{@NumberOf indexes}.  The index will appear automatically at the end
+of your document.
+@PP
+Within the @Code doc setup file there is an @Code "@OrdinarySetup"
+symbol whose options control the appearance of features specific to
+ordinary documents (in other words, the features described in this
+section).  Here is a representative sample of these options, showing
+their default values:
+ordinary.setup @Index @Code "@OrdinarySetup"
+@ID @OneRow @Code {
+"@Use { @OrdinarySetup"
+"  # @IndexWord { index }"
+"  # @AppendixWord { appendix }"
+"  # @SectionNumbers { Arabic }"
+"  # @SectionHeadingFont { Bold }"
+"  # @SectionGap { 2.00v }"
+"  # @SectionInContents { Yes }"
+"}"
+}
+Section {@NumberOf setup} explains how to make your own setup file and
+change its options.
+@PP
+The @Code "@IndexWord" option determines what the index is called, if
+there is one.  The default value, {@Code "index"}, produces the word
+`Index' in the current language.  Any other value produces itself.  The
+@Code "@AppendixWord" option is similar; its default value is `Appendix'
+in the current language.
+@PP
+@Code "@SectionNumbers" determines how sections will be numbered, and may
+be @Code { None }, @Code { Arabic }, @Code { Roman }, @Code { UCRoman },
+@Code { Alpha }, or @Code { UCAlpha }.  The default value is @Code Arabic
+for sections and also all other large-scale structure symbols except
+appendices, for which it is {@Code UCAlpha}.  This produces the appendices
+numbered in upper-case letters (A, B, C, etc.) that were mentioned earlier.
+@PP
+@Code "@SectionHeadingFont" is the font used for section headings.  The
+default value produces the bold face from the family of the
+initial font.  A family name or size is also acceptable:
+@ID @Code "@SectionHeadingFont { Helvetica Base +2p }"
+makes the section heading appear in the Helvetica font, two
+points larger than the initial size.
+@PP
+@Code "@SectionGap" determines how much space is left blank before each
+section title;  the default value shown above is twice the current
+inter-line spacing.  The special value @Code "2b" may be used to get a
+page break rather than a space.  There are similar options for other
+large-scale structure symbols, which determine how much space is left
+before each one.
+@PP
+@Code "@SectionInContents" determines whether or not an entry is made in
+the table of contents for each section; it may be @Code Yes or {@Code No},
+but would always be {@Code Yes}.  The default value of the corresponding
+options for sub-subsections and sub-subappendices, however, is {@Code No}.
+@End @Section
diff --git a/doc/user/typ_orga b/doc/user/typ_orga
new file mode 100644
index 0000000..8ba6ab7
--- /dev/null
+++ b/doc/user/typ_orga
@@ -0,0 +1,93 @@
+@Section
+   @Title { Organizing large documents }
+   @Tag { organizing }
+@Begin
+@PP
+It is not a good plan to store a large document in a single large
+organizing.large @Index { organizing large documents }
+file.  It takes too long to find things in it, and if some catastrophe
+occurs, you lose the lot.  Lout encourages you to break documents into
+pieces by its willingness to read a sequence of files
+({@Code "lout file1 file2 ..."}).  For large documents, the following
+plan is recommended.
+@PP
+Suppose you are making a book whose third chapter contains sections on
+banksias, grevilleas, acacias, and eucalypts.  Place each section, from
+@Code "@Section" to {@Code "@End @Section"}, in a separate file, making
+four files called, say, {@Code banksias}, {@Code grevilleas},
+{@Code acacias}, and {@Code eucalypts}.  Then make a single file for the
+chapter as a whole whose contents are as follows:
+@ID @OneRow @Code {
+"@Chapter"
+"    @Title { Australian Native Plants }"
+"@Begin"
+"Australian native plants provide a distinctive identity to the garden.  Although"
+"less colourful than their European alternatives, some banksias and grevilleas do"
+"flower strongly, and of course the acacias (wattles) are unsurpassable in late winter."
+"@BeginSections"
+"@Include { banksias }"
+"@Include { grevilleas }"
+"@Include { acacias }"
+"@Include { eucalypts }"
+"@EndSections"
+"@End @Chapter"
+}
+The @Code "@Include" symbol causes Lout to read the file whose name follows
+include. @Index @Code "@Include"
+it between braces, just as though the contents of that file had been included
+at that point.
+@PP
+With this arrangement you can easily rearrange the order of the
+sections:  just swap their @Code "@Include" lines.  You should be using
+Lout's automatic cross referencing features (Section {@NumberOf cross}),
+so you don't have to worry about keeping cross references up to date.  You
+can also temporarily delete a section by placing a @Code "#" character at
+the start of its line:
+@ID @Code "# @Include { acacias }"
+This works because @Code "#" is the @I { comment character }:  Lout will
+comment. @Index { comments }
+ignore this character (unless enclosed in double quotes) and everything
+following it up to the end of the line.  You can even temporarily delete
+every section except the one you are working on at the moment, using
+these comments.
+@PP
+Suppose now that this chapter file is called @Code { natives }, and you
+have others called @Code { preface }, @Code { flowers }, etc.  Then you
+can make one file (call it @Code { garden }) for the whole book like this:
+@ID @OneRow @Code {
+"@SysInclude { book }"
+"@Book"
+"    @Title { The Australian Garden }"
+"    @Author { Martha S. Vineyard }"
+"//"
+"@Include { preface }"
+"@Include { flowers }"
+"@Include { shrubs }"
+"@Include { natives }"
+"@Include { trees }"
+}
+You can play the same tricks here:  swap chapters around, or temporarily
+delete one or more with a {@Code "#"}.  When a chapter is finished
+you can temporarily delete it to save formatting time and paper, and
+bring it back at the end.  To format the book, use
+@Code "lout garden > out.ps"
+in Unix.  Lout will read each @Code "@Include" file as it comes to it,
+and if it finds an @Code "@Include" of a section while reading a chapter
+file, it will read the section too.
+@PP
+If the order of your chapters is fairly stable, it might be advantageous
+to use the @Code "@BypassNumber" option of @Code "@Chapter" (described
+in Appendix {@NumberOf bypass}) to fix the numbers of all your chapters,
+so that you get correct chapter numbers even when formatting one
+chapter at a time.
+@PP
+If you decide to store chapters in separate Unix directories, make sure
+that any @Code "/" characters in the file names are enclosed in double
+quotes:
+@ID @Code "@Include { \"natives.dir/acacias\" }"
+Be careful not to give the directory the same name as your chapter
+file.  You might also find it useful to construct your book
+@I { top-down }, as computer scientists call it, laying out all the
+chapters and sections as empty skeletons and filling their contents in
+later.
+@End @Section
diff --git a/doc/user/typ_over b/doc/user/typ_over
new file mode 100644
index 0000000..fd14e2a
--- /dev/null
+++ b/doc/user/typ_over
@@ -0,0 +1,314 @@
+@Section
+   @Title { Overhead transparencies }
+   @Tag { overheads }
+@Begin
+@PP
+To produce overhead transparencies
+@FootNote {
+In Version 3.15 overhead transparencies were updated and brought into line
+with the other document types.  Although existing source files do not need
+to be modified, their printed appearance may change (spacing, running
+headers).  There are some new setup file options, and some changes to
+existing setup file options.
+}
+(hereafter called overheads), start off
+overheads. @Index { overhead transparencies }
+slides. @RawIndex { slides @I see overhead transparencies }
+with the @Code slides setup file and the @Code "@OverheadTransparencies"
+overhead.transparencies. @Index @Code "@OverheadTransparencies"
+symbol:
+@ID @OneRow @Code {
+"@SysInclude { slides }"
+"@OverheadTransparencies"
+"    @Title {}"
+"    @RunningTitle {}"
+"    @Author {}"
+"    @Institution {}"
+"    @DateLine { No }"
+"    @InitialFont { Times Base 20p }"
+"    @InitialBreak { ragged 1.2fx nohyphen }"
+"    @InitialSpace { lout }"
+"    @InitialLanguage { English }"
+"    @PageOrientation { Portrait }"
+"    @PageHeaders { Titles }"
+"    @FirstPageNumber { 1 }"
+"    @FirstOverheadNumber { 1 }"
+"    @FirstLectureNumber { 1 }"
+"    @OptimizePages { No }"
+"//"
+}
+This shows all the options of @Code "@OverheadTransparencies" with their
+default values.  As usual with options, they may be given in any order, and
+only the ones whose values need to be changed need be given at all.  The
+meaning of the @Code "//" symbol after the last option is beyond our
+scope, but disaster will ensue if it is forgotten.
+@PP
+If @Code "@Title" is not empty, an initial overhead will be produced
+containing the {@Code "@Title"}, {@Code "@Author"}, {@Code "@Institution"},
+and {@Code "@DateLine"} options.  @Code "@DateLine" may be set to
+{@Code "No"}, meaning no dateline, {@Code "Yes"}, meaning print the current
+date, or anything else, which is taken to be a date and printed.
+@PP
+Each overhead has a running header printed in small type at the top
+left.  The @Code "@RunningTitle" option goes into this header, or, if
+there is no @Code "@RunningTitle" option, @Code "@Title" is used instead.
+@PP
+The remaining options are a selection of setup file options (Section
+{@NumberOf setup}) that frequently need to be changed.  If your changes
+to the overall formatting are confined to these options, you can change
+them here and avoid having your own setup file.  If you already have
+your own setup file, change them in either place and omit them in
+the other.
+@PP
+@Code "@InitialFont" is the font in which the overheads will be set, and
+should contain a family, a face, and a size.  A good font size for
+overheads is 20 points, so that is the default size.
+@PP
+@Code "@InitialBreak" controls the behaviour of paragraph breaking in
+the overheads.  It should have three parts:  a paragraph
+breaking style ({@Code adjust}, {@Code ragged}, etc.), an inter-line
+spacing ({@Code "1.2fx"} for single spacing, {@Code "2.4fx"} for
+double spacing, and so on), and either @Code "hyphen" or @Code "nohyphen"
+for turning hyphenation on or off.  Adjusted lines and hyphenated words
+are difficult to read from overheads, so the default is not to have them.
+@Code "@InitialSpace" determines how Lout treats white space between
+objects (Section {@NumberOf white}).  @Code "@InitialLanguage"
+determines the language of the overheads.
+@PP
+@Code "@PageOrientation" determines the orientation of the page.  Its
+value may be {@Code Portrait} (the default), {@Code Landscape},
+{@Code ReversePortrait}, or {@Code ReverseLandscape}.  See
+Section {@NumberOf pagesize} for further details.
+@PP
+@Code "@PageHeaders" determines the appearance of page headers and
+footers.  Its value may be {@Code None}, {@Code Simple}, {@Code Titles},
+or {@Code NoTitles}.  Section {@NumberOf headers} has the details, but
+just briefly, {@Code None} produces no page headers, {@Code Simple} produces
+page numbers only, @Code Titles produces full running titles, and
+@Code "NoTitles" is similar to @Code "Simple" in this context.
+@PP
+@Code "@FirstPageNumber" is the number given to the first page,
+@Code "@FirstOverheadNumber" is the number given to the first overhead,
+and @Code "@FirstLectureNumber" is the number given to the first lecture,
+of which more below.  See preceding sections for {@Code "@OptimizePages"}.
+# Lout ordinarily places lines onto a page until space runs out, then moves
+# to the next page and so on.  This often produces ugly empty spaces at
+# the bottoms of pages preceding large unbreakable displays.  Setting the
+# @Code "@OptimizePages" option to {@Code "Yes"} causes Lout to examine the
+# overall situation and try to minimize the ugliness, using the @TeX
+# optimal paragraph breaking algorithm.  It takes two runs to do this,
+# with intermediate results stored in Lout's cross reference database
+# (Section {@NumberOf cross}); so deleting file {@Code lout.li} will reset
+# it, which might be wise after major changes.  It is possible for the
+# optimizer to cycle, never settling on a single final best
+# version; this is usually caused by footnotes or floating figures inserted
+# at points which end up near page boundaries.
+@PP
+After the compulsory {@Code "//"} come the overheads themselves.  There
+are two alternatives:  a series of overheads, corresponding to a single
+lecture, or a series of series of overheads, corresponding to a series
+of lectures.  If the first is wanted, use this arrangement:
+overhead. @Index @Code "@Overhead"
+@ID @OneRow @Code {
+"@SysInclude { slides }"
+"@OverheadTransparencies"
+"    ..."
+"//"
+"@Overhead ... @End @Overhead"
+"@Overhead ... @End @Overhead"
+"..."
+"@Overhead ... @End @Overhead"
+}
+@Code "@Overhead" is a large-scale structure symbol, similar to
+{@Code "@Section"}, with the usual options:
+@ID @OneRow @Code {
+"@Overhead"
+"    @Title { Trends in investment since 1980 }"
+"    @RunningTitle { Investment }"
+"    @Tag { investment }"
+"    @InitialLanguage { English }"
+"@Begin"
+"..."
+"@End @Overhead"
+}
+If @Code "@Title" is given it will appear as a centred, bold display
+at the beginning of the overhead.  As usual, these options may be given
+in any order or omitted altogether.
+@PP
+The body of the overhead is quite arbitrary.  Typically one tends to
+use lists and displays more than paragraphs, but all the usual features
+are available.  Each overhead begins on a fresh page, but it may occupy
+more than one page.
+@PP
+@Code "@Overhead" also has a @Code "@Format" option which allows you to
+specify an arbitrary format for the body of the overhead (that is,
+everything except its title).  For example,
+@ID @Code "@Format { @CurveBox @HExpand @VExpand @Body }"
+encloses the body in a curvebox, with the box expanded to the full
+available width and height.  Unlike the similar option for figures
+and tables, however, this @Code "@Format" option unfortunately has
+not been set up to work with multi-page overheads, so if you use the
+format just given you have to make sure your overheads all fit on one
+page.  To draw boxes around the @I entire page, use the @Code "@PageBox"
+setup file options.
+@PP
+Lout does not provide any special support for overlays.  A good way to
+make them is to first produce one overhead containing all the layers
+simultaneously.  Once this is correct, enclose the entire body of the
+overhead in {@Code "white @Colour"}, make one copy of the text of the
+overhead for each layer, separating the copies with @Code "@NP"
+(new page) symbols, and, in each copy, enclose the parts that are
+to appear in that layer in {@Code "black @Colour"} (or any other
+colour).  This works because @Code "white @Colour" makes an object
+invisible without altering its size.
+@PP
+We turn now to the second major alternative, which is a series
+of lectures, like this:
+lecture. @Index @Code "@Lecture"
+@ID @OneRow @Code {
+"@SysInclude { slides }"
+"@OverheadTransparencies"
+"    ..."
+"//"
+"@Lecture ... @End @Lecture"
+"@Lecture ... @End @Lecture"
+"..."
+"@Lecture ... @End @Lecture"
+}
+@Code "@Lecture" is a large-scale structure symbol, again with
+the usual options:
+@ID @OneRow @Code {
+"@Lecture"
+"    @Title { Macro-Economic Policies for the Nineties }"
+"    @RunningTitle { Macro-economic policies }"
+"    @Tag { macro-economics }"
+"    @InitialLanguage { English }"
+"@Begin"
+"..."
+"@End @Lecture"
+}
+If @Code "@Title" is non-empty the series of overheads will begin with
+an overhead containing the title alone, centred on the page using the
+@Code "clines" paragraph breaking style.  This means that it makes
+sense to have a multi-line title.  Any text following the @Code "@Begin"
+will appear under the lecture title as you would expect.
+@PP
+Within the body of {@Code "@Lecture"}, place a series of overheads
+bracketed by @Code "@BeginOverheads" and {@Code "@EndOverheads"}:
+beginoverheads. @Index @Code "@BeginOverheads"
+endoverheads. @Index @Code "@EndOverheads"
+@ID @OneRow @Code {
+"@BeginOverheads"
+"@Overhead ... @End @Overhead"
+"@Overhead ... @End @Overhead"
+"..."
+"@Overhead ... @End @Overhead"
+"@EndOverheads"
+}
+The @Code "@Overhead" symbol is exactly as described earlier.
+@PP
+The features described in other chapters are available with
+overheads.  Endnotes and references appear automatically at the
+end of the overheads.  You can have a table of contents, by setting
+the @Code "@MakeContents" option of the setup file to {@Code Yes}.  It
+will appear automatically after any title overhead.  The setup file
+options have been set on the assumption that you want your lectures
+to appear in the table of contents, but not individual overheads.  It is not
+possible to have an index, and it is not possible to have multiple columns.
+@PP
+Within the @Code slides setup file there is an @Code "@OverheadSetup"
+symbol whose options control the appearance of features specific to
+overhead.setup. @Index @Code "@OverheadSetup"
+overheads (in other words, the features described in this section).  Here
+are some of these options and their default values:
+@ID @OneRow @Code {
+"@Use { @OverheadSetup"
+"  # @DateLine { No }"
+"  # @FirstOverheadNumber { 1 }"
+"  # @FirstLectureNumber { 1 }"
+"  # @ContentsWord { contents }"
+"  # @LectureNumbers { Arabic }"
+"  # @OverheadNumbers { Arabic }"
+"  # @TitlePageFont { Helvetica Base }"
+"  # @LectureHeadingFont { Bold 1.20f }"
+"  # @LectureHeadingFormat { @Centre number @DP @Centre title @DP }"
+"  # @OverheadHeadingFormat { @Centre title @DP }"
+"  # @OverheadHeadingFont { Bold }"
+"  # @LectureInContents { Yes }"
+"  # @OverheadInContents { No }"
+"  # @ReferencesInContents { Yes }"
+"}"
+}
+For an introduction to setup files and their options, consult
+Section {@NumberOf setup}.  The first four options are as for
+@Code "@OverheadTransparencies" as described above.  @Code "@ContentsWord"
+determines the table of contents heading; its default value, {@Code contents},
+produces `Contents' in the current language.  @Code "@LectureNumbers"
+and @Code "@OverheadNumbers" determine the style of numbering of lectures
+and overheads, and may be {@Code None}, {@Code Arabic}, {@Code Roman},
+{@Code UCRoman}, {@Code Alpha}, or {@Code UCAlpha} as usual.  Next come
+options for setting the font of the overall title page, the
+title page of each lecture, and so on, and finally options which
+determine which entries are made in any table of contents.
+@PP
+The @Code "@LectureHeadingFormat" option determines the
+format of the heading of each lecture.  Within it, the symbol @Code "number" 
+stands for the number of the lecture, including the `Lecture' word if
+there is one, and @Code "title" stands for the title of the lecture.  The
+default value centres the number and title, with display gaps below
+each one.  @Code "@OverheadHeadingFormat" is similar; it has the same
+symbols but the default value chooses not to use {@Code "number"}.
+@PP
+Other setup file options exist which permit you to have a box drawn
+around each overhead, and to change the page size, margins, and
+orientation.  These are described in Chapter {@NumberOf changes}.
+@PP
+Section {@NumberOf headers} describes the setup file options that
+control the appearance of page headers and footers.  With overheads,
+the values given to the {@Code "@MajorTitle"}, {@Code "@MinorTitle"},
+{@Code "@MajorNum"}, and {@Code "@MinorNum"} symbols within those
+options are as follows.  If @Code "@Lecture" is being used:
+@ID @Tab
+    @Fmta { @Col A ! @Col B }
+{
+@Rowa
+    A { @Code "@MajorTitle" }
+    B { The @Code "@RunningTitle" option of
+{@Code "@OverheadTransparencies"}, or its @Code "@Title" option
+if @Code "@RunningTitle" is absent; }
+@Rowa
+    A { @Code "@MinorTitle" }
+    B { The @Code "@RunningTitle" option of the current
+{@Code "@Lecture"}, or else its @Code "@Title" option if
+@Code "@RunningTitle" is absent; }
+@Rowa
+    A { @Code "@MajorNum" }
+    B { The number of the current {@Code "@Lecture"}; }
+@Rowa
+    A { @Code "@MinorNum" }
+    B { A two-part number, for example 5.2, containing the number of
+the current @Code "@Lecture" and the number within that lecture
+of the current overhead. }
+}
+If @Code "@Lecture" is not being used:
+@ID @Tab
+    @Fmta { @Col A ! @Col B }
+{
+@Rowa
+    A { @Code "@MajorTitle" }
+    B { The @Code "@RunningTitle" option of
+{@Code "@OverheadTransparencies"}, or its @Code "@Title" option
+if @Code "@RunningTitle" is absent; }
+@Rowa
+    A { @Code "@MinorTitle" }
+    B { Empty; }
+@Rowa
+    A { @Code "@MajorNum" }
+    B { Empty; }
+@Rowa
+    A { @Code "@MinorNum" }
+    B { The number of the current overhead. }
+}
+The first page occupied by any overhead is a @Code Start page; subsequent
+pages are @Code NonStart pages.  There are no @Code Intro pages.
+@End @Section
diff --git a/doc/user/typ_plai b/doc/user/typ_plai
new file mode 100644
index 0000000..a880ccb
--- /dev/null
+++ b/doc/user/typ_plai
@@ -0,0 +1,76 @@
+@Section
+   @Title { Plain text documents }
+   @Tag { plain }
+@Begin
+@PP
+Occasionally you may need to produce an output file containing plain text
+plain.text. @Index { plain text documents }
+rather than PostScript, for example for an online manual entry or to send
+as electronic mail.  Any document that can be produced by Lout in
+PostScript can be produced in plain text as well, by adding a @Code "-p"
+flag to the Unix command line:
+@ID @Code "lout -p simple"
+No other changes are required.  Here we are sending the output directly to
+the screen, but it can be redirected to a file, or piped through the
+@Code more command for viewing one page at a time, etc.
+@PP
+Of course, plain text is an extremely limited medium of communication
+compared with PostScript, and this forces Lout to make some rather
+drastic compromises:
+@BulletList gap { @ParaGap }
+@LI { Symbols like {@Code "@Bullet"}, which stand for unusual characters,
+produce printable characters which approximate the PostScript ones.  For
+example, {@Code "@Bullet"} produces {@Code "o"}.  However, the @Code "@Char"
+and @Code "@Sym" symbols often produce unprintable characters, and are best
+avoided; }
+@LI { All font and size changes are ignored, since plain text has only
+one font and size.  Every character is taken to be @Eq { 1 frac 10 } inch
+wide and @Eq { 1 frac 6 } inch high; }
+@LI { No underlines are printed; }
+@LI { No margin notes are printed; }
+@LI { Scaled objects are not printed unless the scale factor happens to be 1; }
+@LI { Rotated objects are not printed unless the angle happens to be zero
+degrees.  This means that page orientations (Section {@NumberOf pagesize})
+other than @Code Portrait do not work; }
+@LI { Ruled lines are not printed, and paint and colour options are
+ignored.  This spoils the graphics and graphs of Chapters
+{@NumberOf graphics}, {@NumberOf diagrams}, and {@NumberOf graphs}. }
+@EndList
+Despite the problems, many things work surprisingly well.  Tables, for example,
+look very good.  It does no harm to try things and see if they work out.
+@PP
+The worst problem with plain text is that characters cannot be placed at
+arbitrary points on the page.  A superscript, for example, is impossible to
+place correctly, so Lout uses a different layout for footnote labels (and
+makes a mess of equations, which are best avoided).  Because of this problem
+it's best to make all horizontal lengths multiples of @Eq {1 frac 10} inch
+(conveniently expressed as {@Code 1s}), and all vertical lengths multiples
+of @Eq { 1 frac 6 } inch (conveniently expressed as {@Code 1f}).  To help
+you do this, the setup files contain many entries that look like this
+example:
+@ID @Code "# @InitialBreak { {adjust 1.2fx hyphen} @OrIfPlain {ragged 1fx nohyphen} }"
+The meaning is that the value of @Code "@InitialBreak" will be
+@Code "adjust 1.2fx hyphen" usually, but will switch to
+{@Code "ragged 1fx nohyphen"}, which is better suited to plain text,
+if the @Code "-p" command line flag is used.  These setup file values
+allow you to switch from PostScript to plain text and back again without
+changing anything at all except the @Code "-p" command line flag.
+@PP
+If you use @Code "lout -P" instead of {@Code "lout -p"}, the plain text
+output will contain a form-feed character (control-L) after each page
+form.feed @Index { form-feed in plain text }
+except the last.  This character causes most printing devices to start
+a new page, which is very useful when your page height is not exactly
+right.
+@PP
+The @Code "@Document" symbol (Section {@NumberOf ordinary}) has an
+unpaginated. @Index @Code "@Unpaginated"
+@Code "@Unpaginated" option which, when set to {@Code "Yes"}, causes
+the plain text output to appear unpaginated, that is, in one long
+continous stream with no page breaks.  Its value is ignored if plain text
+output is not in effect, so it can be safely set to @Code "Yes" in
+documents intended for formatting both ways.  The usual margins apply;
+footnotes appear at the end; figures and tables do not work.  Lout
+stupidly reads the entire document before producing any output when
+this option is used, so if the document is long you might run out of memory.
+@End @Section
diff --git a/doc/user/typ_repo b/doc/user/typ_repo
new file mode 100644
index 0000000..b73671a
--- /dev/null
+++ b/doc/user/typ_repo
@@ -0,0 +1,359 @@
+@Section
+   @Title { Technical reports }
+   @Tag { reports }
+@Begin
+@PP
+To make a technical report,
+start off with the @Code "report" setup
+reports. @Index { reports }
+technical.reports. @Index { technical reports }
+report. @Index @Code "@Report"
+file and the @Code "@Report" symbol:
+@ID @OneRow @Code {
+"@SysInclude { report }"
+"@Report"
+"    @Title {}"
+"    @Author {}"
+"    @Institution {}"
+"    @DateLine { No }"
+"    @AtEnd {}"
+"    @CoverSheet { Yes }"
+"    @ContentsSeparate { No }"
+"    @InitialFont { Times Base 12p }"
+"    @InitialBreak { hyphen adjust 1.2fx }"
+"    @InitialSpace { lout }"
+"    @InitialLanguage { English }"
+"    @PageOrientation { Portrait }"
+"    @PageHeaders { Simple }"
+"    @ColumnNumber { 1 }"
+"    @FirstPageNumber { 1 }"
+"    @OptimizePages { No }"
+"    @AbstractDisplay { Yes }"
+"    @AbstractTitle { Abstract }"
+"    @Abstract {}"
+"//"
+}
+This shows all the options of {@Code "@Report"}
+@FootNote {
+Version 3.13 of Lout is not completely upwardly compatible with
+previous versions in its handling of technical reports.  The change
+concerns the abstract, and if you see the error message
+@ID @Code "symbol @Abstract unknown or misspelt"
+you probably need to convert your document.  To convert an older
+document to Version 3.13, move any @Code "@Abstract" from after the
+@Code "//" to before it, delete any options to the @Code "@Abstract"
+symbol, and delete any initial paragraph symbol within the abstract.
+You can use the @Code "@AbstractTitle" option described in this section
+to change the title of the abstract.
+}
+with their default values.  As usual with options, they may be given in
+any order, and only the ones whose values need to be changed need be
+given at all.  The meaning of the @Code "//" symbol is beyond our scope,
+but disaster will ensue if it is forgotten.
+@PP
+The @Code "@Title" option holds the title of the report.  It will be
+printed using the @Code clines paragraph breaking style (Section
+{@NumberOf paras}), which centres each line, so it makes sense
+to have multi-line titles:
+@ID @OneRow @Code {
+"@Report"
+"    @Title {"
+"The solution of real instances of"
+"the timetabling problem"
+"}"
+"    ..."
+}
+With a multi-line title, each line after the first should begin
+at the left margin, not indented.  It doesn't matter where the first
+line begins, because space following an open brace is ignored.
+@PP
+The @Code "@Author" and @Code "@Institution" options hold the author's
+name and institution or address, and will also be printed using the
+@Code clines style.  If there are several authors but only one
+institution, list all the authors in the @Code "@Author" option:
+@ID @Code "@Author { Tim B. Cooper and Jeffrey H. Kingston }"
+With more authors, or with more than one institution, it is best to
+ignore the @Code "@Institution" option and place all the information
+within the @Code "@Author" option, enclosing institution information
+in @Code "@I" symbols.  In extreme cases, a table with columns of
+authors might be necessary (Chapter {@NumberOf tables}).
+@PP
+@Code "@DateLine" may be set to {@Code No}, meaning no dateline,
+{@Code Yes}, meaning print the current date, or anything else, which is
+taken to be a date and printed:
+@ID @Code "@DateLine { 4 July, 1776 }"
+A good plan is to use @Code "@DateLine { Yes }" until
+the report is finalized.
+@PP
+The {@Code "@AtEnd"} option will come out on a single unnumbered
+page with no page headers or footers, and using the same margins as for
+even pages, after the very last page of the report; even after the
+index if there is one.  It is intended to make it possible to
+include a back cover, so @Code "@PageOf last.page" does not take
+account of any @Code "@AtEnd" page.
+@PP
+The remaining options (except {@Code "@Abstract"}) are setup file options
+(Section {@NumberOf setup}) that frequently need to be changed.  If your
+changes to the overall formatting are confined to these options, you can
+change them here and avoid having your own setup file.  If you already have
+your own setup file, change them in either place and omit them in
+the other.
+@PP
+If @Code "@CoverSheet" is {@Code Yes}, an unnumbered cover
+cover.sheet. @Index @Code "@CoverSheet"
+sheet will be produced containing the title, author, institution,
+abstract, and dateline.  Otherwise they will appear on the
+first page.  The `cover sheet' is in reality a sequence of Intro pages
+(Section {@NumberOf headers}), numbered by default with Roman numerals
+on pages after the first.
+@PP
+In order to get a table of contents, it is necessary to use your
+own setup file (Section {@NumberOf setup} explains how to do this)
+and to set the @Code "@MakeContents" option within it to
+{@Code Yes}.  The table of contents will ordinarily appear beginning
+on the first page, but if the @Code "@ContentsSeparate" option of
+@Code "@Report" is
+contents.separate @Index @Code "@ContentsSeparate"
+set to @Code "Yes" it will appear on separate pages.  This is only
+effective if @Code "@CoverSheet" is {@Code No}, since a separate cover
+sheet and separate pages for the table of contents would leave nothing on
+the first page.
+@PP
+@Code "@InitialFont" is the font of the bulk of the report,
+and should contain a family, a face, and a size.  The default
+value selects the Times family, the Base face, and the 12 point size.
+@PP
+@Code "@InitialBreak" controls the behaviour of paragraph breaking in
+the bulk of the report.  It should have three parts:  a paragraph
+breaking style ({@Code adjust}, {@Code ragged}, etc.), an inter-line
+spacing ({@Code "1.2fx"} for single spacing, {@Code "2.4fx"} for
+double spacing, and so on), and either @Code "hyphen" or
+@Code "nohyphen" for turning hyphenation on or off.  It may also
+have @Code "nobreakfirst" or @Code "nobreaklast" (or both), meaning
+to disallow a page break after the first line of a paragraph, or
+before the last, respectively.
+@PP
+@Code "@InitialSpace" determines how Lout treats white space between
+two objects, as described in Section
+{@NumberOf white}.  @Code "@InitialLanguage" determines the language
+of the bulk of the report.
+@PP
+@Code "@PageOrientation" determines the orientation of the page.  Its
+value may be {@Code Portrait} (the default), {@Code Landscape},
+{@Code ReversePortrait}, or {@Code ReverseLandscape}.  See
+Section {@NumberOf pagesize} for further details.
+@PP
+@Code "@PageHeaders" determines the appearance of page headers and
+footers.  Its value may be {@Code None},
+{@Code Simple}, {@Code Titles}, or {@Code NoTitles}.  Section
+{@NumberOf headers} has the details, but just briefly, {@Code None}
+produces no page headers, {@Code Simple} produces a centred page number
+between hyphens on every page except the cover sheet and the first
+page, @Code Titles produces full running titles as in the present
+document, and @Code "NoTitles" is like @Code "Titles" with the running
+titles omitted, leaving just the page numbers.
+@PP
+@Code "@ColumnNumber" is the number of columns per page in the bulk of
+the report, and may be anything from {@Code 1} (the default value) to
+{@Code 10}.  However, there is nothing analogous to the @Code "@FullWidth"
+symbol of ordinary documents.  Instead, the cover sheet, title material,
+and all figures and tables will be printed full width, and the rest will
+be set in columns.  There is a separate @Code "@IndexColumnNumber" option
+in the setup file which determines the number of columns in the index
+(Section {@NumberOf indexes}).
+@PP
+@Code "@FirstPageNumber" is the page number given to the first page.
+@PP
+Lout ordinarily places lines onto a page until space runs out, then moves
+to the next page and so on.  This often produces ugly empty spaces at
+the bottoms of pages preceding large unbreakable displays.  Setting the
+@Code "@OptimizePages" option to {@Code "Yes"} causes Lout to examine the
+overall situation and try to minimize the ugliness, using the @TeX
+optimal paragraph breaking algorithm.  It takes two runs to do this,
+with intermediate results stored in Lout's cross reference database
+(Section {@NumberOf cross}); so deleting file {@Code lout.li} will reset
+it, which might be wise after major changes.  It is possible for the
+optimizer to cycle, never settling on a single final best version; this
+is usually caused by footnotes or floating figures inserted at points
+which end up near page boundaries.
+@PP
+Finally we have three options that control the abstract.
+@Code "@AbstractDisplay" may be @Code { Yes } or {@Code No};
+it determines whether the abstract is displayed (occupying
+the full page width except for an indent at each side like a quoted
+display) or inline (occupying the column width).
+@Code "@AbstractTitle" is the title of the abstract; its default
+value is @Code Abstract or its equivalent in the current language.
+abstract. @Index @Code "@Abstract"
+Finally, @Code "@Abstract" contains the abstract itself; it may be
+empty or absent, in which case there will be no abstract.
+@PP
+The abstract may contain footnotes in the usual way.  Regrettably, each
+footnote in the abstract will generate one spurious `unresolved cross
+reference' error message that does not go away.  This slight problem
+might be fixed in the future.
+@PP
+After the compulsory {@Code "//"} comes the report body in the
+form of a sequence of sections:
+section.reports @SubIndex { in reports }
+@ID @OneRow @Code {
+"@Section"
+"    @Title { Introduction }"
+"@Begin"
+"@PP"
+"..."
+"@End @Section"
+}
+No @Code "@BeginSections" or @Code "@EndSections" symbols are needed.  The
+beginsections.reports @SubIndex { in reports }
+endsections.reports @SubIndex { in reports }
+general rule is that you need these bracketing symbols only when you are
+inside something else.  Sections lie inside
+@Code "@Text" in ordinary documents, but they don't lie inside anything
+else in technical reports.
+@PP
+A section may have subsections, between
+subsection.reports @SubIndex { in reports }
+beginsubsections.reports @SubIndex { in reports }
+endsubsections.reports @SubIndex { in reports }
+@Code "@BeginSubSections" and {@Code "@EndSubSections"}:
+@ID @OneRow @Code {
+"preceding text"
+"@BeginSubSections"
+"@SubSection ... @End @SubSection"
+"@SubSection ... @End @SubSection"
+"..."
+"@SubSection ... @End @SubSection"
+"@EndSubSections"
+}
+Within each subsection there may be sub-subsections, each introduced
+by {@Code "@SubSubSection"}, with the whole sequence bracketed by
+subsubsection.reports @SubIndex { in reports }
+beginsubsubsections.reports @SubIndex { in reports }
+endsubsubsections.reports @SubIndex { in reports }
+@Code "@BeginSubSubSections" and {@Code "@EndSubSubSections"}:
+@ID @OneRow @Code {
+"preceding text"
+"@BeginSubSubSections"
+"@SubSubSection ... @End @SubSubSection"
+"@SubSubSection ... @End @SubSubSection"
+"..."
+"@SubSubSection ... @End @SubSubSection"
+"@EndSubSubSections"
+}
+There are no sub-sub-subsections.
+@PP
+After the sections comes an optional sequence of appendices:
+appendix.reports @SubIndex { in technical reports }
+@ID @OneRow @Code {
+"@Appendix"
+"    @Title { Derivation of the renewal formula }"
+"@Begin"
+"@PP"
+"..."
+"@End @Appendix"
+}
+No @Code "@BeginAppendices" or @Code "@EndAppendices" symbols are needed,
+beginappendices.reports @SubIndex { in reports }
+endappendices.reports @SubIndex { in reports }
+because (like the sections above) these appendices do not lie inside
+any other large-scale structure symbol.  The appendices are numbered
+A, B, C, etc., as is conventional for them.  Within each appendix
+there may be a sequence of subappendices, obtained with the
+@Code "@SubAppendix" symbol and bracketed by @Code "@BeginSubAppendices"
+subappendix.reports @SubIndex { in reports }
+beginsubappendices.reports @SubIndex { in reports }
+endsubappendices.reports @SubIndex { in reports }
+and {@Code "@EndSubAppendices"}:
+@ID @OneRow @Code {
+"preceding text"
+"@BeginSubAppendices"
+"@SubAppendix ... @End @SubAppendix"
+"@SubAppendix ... @End @SubAppendix"
+"..."
+"@SubAppendix ... @End @SubAppendix"
+"@EndSubAppendices"
+}
+There are sub-subappendices following the same pattern, but no
+subsubappendix.reports @SubIndex { in reports }
+beginsubsubappendices.reports @SubIndex { in reports }
+endsubsubappendices.reports @SubIndex { in reports }
+sub-sub-subappendices.
+@PP
+The report ends with the last section or appendix; any reference list or
+index will be appended automatically.  Although we have described how to
+create reports as though everything was in one large file, in practice it
+is much better to divide the report into multiple files, following the
+method given in Section {@NumberOf organizing}.
+@PP
+In addition to the {@Code "@Title"} option, each large-scale structure
+symbol ({@Code "@Section"}, {@Code "@SubSection"}, {@Code "@SubSubSection"},
+{@Code "@Appendix"}, {@Code "@SubAppendix"},
+and {@Code "@SubSubAppendix"}) has a @Code "@Tag" option for cross
+referencing (Section {@NumberOf cross}), an @Code "@InitialLanguage"
+option for changing the language of that part of the document, and a
+@Code "@RunningTitle" option which will be used in place of @Code "@Title"
+in running headers if given.  @Code "@RunningTitle" is useful when the
+full title is rather long.
+@PP
+The features described in other chapters are all available within
+technical reports.  To get a table of contents, change the @Code
+"@MakeContents" option in the setup file to {@Code Yes}; the rest is
+automatic, and you don't need the @Code "@ContentsGoesHere" symbol from
+ordinary documents.  To get an index, again you need only change the
+@Code "@MakeIndex" setup file option to {@Code Yes}.  Endnotes and
+references appear at the end of the report.  Figures and tables are
+numbered 1, 2, 3, etc.
+@PP
+Within the @Code "report" setup file there is a @Code "@ReportSetup"
+symbol whose options control the appearance of features specific to
+report.setup @Index @Code "@ReportSetup"
+reports (in other words, the features described in this section).  Section
+{@NumberOf setup} explains setup files and their options in general; here
+is a representative sample of these options, showing their default values:
+@ID @OneRow @Code {
+"@Use { @ReportSetup"
+"    # @CoverSheet { Yes }"
+"    # @DateLine { No }"
+"    # @ReferencesBeforeAppendices { No }"
+"    # @AbstractWord { abstract }"
+"    # @ContentsWord { contents }"
+"    # @SectionNumbers { Arabic }"
+"    # @SectionHeadingFont { Bold }"
+"    # @SectionGap { 2.00v }"
+"    # @SectionInContents { Yes }"
+"}"
+}
+@Code "@CoverSheet" and @Code "@DateLine" are as for {@Code "@Report"};
+you can set them in either place as you prefer.  @Code
+"@ReferencesBeforeAppendices" determines whether the reference list is
+printed out before or after any appendices.  @Code "@AbstractWord"
+determines the value of the title of the abstract if none is given there;
+its default value, {@Code abstract}, produces `Abstract' in the current
+language.  @Code "@ContentsWord" is similar; its default value produces
+`Contents' in the current language.  The other four options
+control the appearance of sections, and there are similar options for
+controlling the other large-scale structure symbols.
+@PP
+@Code "@SectionNumbers" determines how sections will be numbered, and may
+be @Code { None }, @Code { Arabic }, @Code { Roman }, @Code { UCRoman },
+@Code { Alpha }, or @Code { UCAlpha }.  The default value is @Code Arabic
+for sections, and also for all large-scale structure symbols except
+appendices, for which it is {@Code UCAlpha}.  This produces the appendices
+numbered in upper-case letters (A, B, C, etc.) that were mentioned earlier.
+@PP
+@Code "@SectionHeadingFont" is the font used for section headings.  The
+default value shown above produces the bold face from the family of the
+initial font.  A family name and size is acceptable here as well:
+@ID @Code "@SectionHeadingFont { Helvetica Base +2p }"
+produces section headings in the Helvetica font, two points larger
+than the initial font size.
+@PP
+@Code "@SectionGap" determines how much space is left blank before each
+section title;  the default value shown above is twice the current
+inter-line spacing.  The special value @Code "2b" may be used to get a
+page break rather than a space.  @Code "@SectionInContents" determines
+whether or not an entry is made in the table of contents for each section;
+it may be @Code Yes or {@Code No}.  There are similar options for other
+large-scale structure symbols.
+@End @Section
diff --git a/doc/user/vbas b/doc/user/vbas
new file mode 100644
index 0000000..0004cfb
--- /dev/null
+++ b/doc/user/vbas
@@ -0,0 +1,3 @@
+vi bas bas_star bas_objs bas_spac bas_char bas_empt bas_font bas_head \
+       bas_par1 bas_par2 bas_line bas_hyph bas_unde bas_date bas_lang \
+       bas_supe bas_verb bas_drop bas_conv
diff --git a/doc/user/vfmt b/doc/user/vfmt
new file mode 100644
index 0000000..39d5efe
--- /dev/null
+++ b/doc/user/vfmt
@@ -0,0 +1 @@
+vi fmt fmt_setu fmt_size fmt_marg fmt_head
diff --git a/doc/user/vref b/doc/user/vref
new file mode 100644
index 0000000..55e3596
--- /dev/null
+++ b/doc/user/vref
@@ -0,0 +1 @@
+vi ref ref_sett ref_cite ref_labe ref_entr ref_chan ref_crea
diff --git a/doc/user/vstr b/doc/user/vstr
new file mode 100644
index 0000000..7f4e2d0
--- /dev/null
+++ b/doc/user/vstr
@@ -0,0 +1,2 @@
+vi str str_disp str_list str_foot str_marg str_theo str_figs str_larg \
+       str_cros str_cont str_indx str_colu str_defs
diff --git a/doc/user/vtbl b/doc/user/vtbl
new file mode 100644
index 0000000..24f6a4d
--- /dev/null
+++ b/doc/user/vtbl
@@ -0,0 +1,2 @@
+vi tbl tbl_intr tbl_cell tbl_rows tbl_marg tbl_widt tbl_inde tbl_rule \
+       tbl_span tbl_mult tbl_alig tbl_mark tbl_plai tbl_setu tbl_summ
diff --git a/doc/user/vtyp b/doc/user/vtyp
new file mode 100644
index 0000000..003ff0b
--- /dev/null
+++ b/doc/user/vtyp
@@ -0,0 +1,2 @@
+vi typ typ_ordi typ_repo typ_book typ_over typ_illu typ_plai \
+       typ_apdf typ_orga