aboutsummaryrefslogtreecommitdiffstats
path: root/doc/user
diff options
context:
space:
mode:
authorJeffrey H. Kingston <jeff@it.usyd.edu.au>2010-09-14 19:21:41 +0000
committerJeffrey H. Kingston <jeff@it.usyd.edu.au>2010-09-14 19:21:41 +0000
commit71bdb35d52747e6d7d9f55df4524d57c2966be94 (patch)
tree480ee5eefccc40d5f3331cc52d66f722fd19bfb9 /doc/user
parentb41263ea7578fa9742486135c762803b52794105 (diff)
downloadlout-71bdb35d52747e6d7d9f55df4524d57c2966be94.tar.gz
Lout 3.17.
git-svn-id: http://svn.savannah.nongnu.org/svn/lout/trunk@2 9365b830-b601-4143-9ba8-b4a8e2c3339c
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/README37
-rw-r--r--doc/user/all47
-rw-r--r--doc/user/ap_byp98
-rw-r--r--doc/user/ap_qck369
-rw-r--r--doc/user/bas31
-rw-r--r--doc/user/bas_char325
-rw-r--r--doc/user/bas_conv75
-rw-r--r--doc/user/bas_date84
-rw-r--r--doc/user/bas_drop44
-rw-r--r--doc/user/bas_empt26
-rw-r--r--doc/user/bas_font629
-rw-r--r--doc/user/bas_head32
-rw-r--r--doc/user/bas_hyph37
-rw-r--r--doc/user/bas_lang85
-rw-r--r--doc/user/bas_line43
-rw-r--r--doc/user/bas_objs141
-rw-r--r--doc/user/bas_par1105
-rw-r--r--doc/user/bas_par2261
-rw-r--r--doc/user/bas_spac103
-rw-r--r--doc/user/bas_star129
-rw-r--r--doc/user/bas_supe17
-rw-r--r--doc/user/bas_unde27
-rw-r--r--doc/user/bas_verb49
-rw-r--r--doc/user/bgr17
-rw-r--r--doc/user/bgr_boxs121
-rw-r--r--doc/user/bgr_colo48
-rw-r--r--doc/user/bgr_incl47
-rw-r--r--doc/user/bgr_rota35
-rw-r--r--doc/user/bgr_scal53
-rw-r--r--doc/user/cpp27
-rw-r--r--doc/user/cpp_chan83
-rw-r--r--doc/user/cpp_comm20
-rw-r--r--doc/user/cpp_eiff42
-rw-r--r--doc/user/cpp_embe152
-rw-r--r--doc/user/cpp_lone36
-rw-r--r--doc/user/cpp_tabs62
-rw-r--r--doc/user/dia46
-rw-r--r--doc/user/dia_cons7
-rw-r--r--doc/user/dia_defi361
-rw-r--r--doc/user/dia_erro45
-rw-r--r--doc/user/dia_geom208
-rw-r--r--doc/user/dia_intr108
-rw-r--r--doc/user/dia_labe433
-rw-r--r--doc/user/dia_link261
-rw-r--r--doc/user/dia_node512
-rw-r--r--doc/user/dia_posi224
-rw-r--r--doc/user/dia_summ1680
-rw-r--r--doc/user/dia_tags168
-rw-r--r--doc/user/dia_tree379
-rw-r--r--doc/user/draft.eps289
-rw-r--r--doc/user/equ28
-rw-r--r--doc/user/equ_defs53
-rw-r--r--doc/user/equ_disp126
-rw-r--r--doc/user/equ_intr61
-rw-r--r--doc/user/equ_spac81
-rw-r--r--doc/user/equ_summ721
-rw-r--r--doc/user/equ_symb357
-rw-r--r--doc/user/equ_tequ41
-rw-r--r--doc/user/equ_vert164
-rw-r--r--doc/user/fmt16
-rw-r--r--doc/user/fmt_head313
-rw-r--r--doc/user/fmt_marg121
-rw-r--r--doc/user/fmt_setu210
-rw-r--r--doc/user/fmt_size91
-rw-r--r--doc/user/gra46
-rw-r--r--doc/user/gra_capt72
-rw-r--r--doc/user/gra_data267
-rw-r--r--doc/user/gra_erro40
-rw-r--r--doc/user/gra_func179
-rw-r--r--doc/user/gra_intr51
-rw-r--r--doc/user/gra_keys104
-rw-r--r--doc/user/gra_over179
-rw-r--r--doc/user/gra_plac51
-rw-r--r--doc/user/gra_summ466
-rw-r--r--doc/user/gra_tick205
-rw-r--r--doc/user/letterbook356
-rw-r--r--doc/user/mydefs203
-rw-r--r--doc/user/pascal162
-rw-r--r--doc/user/preface66
-rw-r--r--doc/user/ref31
-rw-r--r--doc/user/ref_chan200
-rw-r--r--doc/user/ref_cite90
-rw-r--r--doc/user/ref_crea139
-rw-r--r--doc/user/ref_entr293
-rw-r--r--doc/user/ref_labe65
-rw-r--r--doc/user/ref_sett95
-rw-r--r--doc/user/str19
-rw-r--r--doc/user/str_colu40
-rw-r--r--doc/user/str_cont83
-rw-r--r--doc/user/str_cros112
-rw-r--r--doc/user/str_defs134
-rw-r--r--doc/user/str_disp94
-rw-r--r--doc/user/str_figs270
-rw-r--r--doc/user/str_foot150
-rw-r--r--doc/user/str_indx314
-rw-r--r--doc/user/str_larg177
-rw-r--r--doc/user/str_list392
-rw-r--r--doc/user/str_marg156
-rw-r--r--doc/user/str_theo108
-rw-r--r--doc/user/su_crest.eps1156
-rw-r--r--doc/user/tbl48
-rw-r--r--doc/user/tbl_alig96
-rw-r--r--doc/user/tbl_cell97
-rw-r--r--doc/user/tbl_inde58
-rw-r--r--doc/user/tbl_intr119
-rw-r--r--doc/user/tbl_marg74
-rw-r--r--doc/user/tbl_mark65
-rw-r--r--doc/user/tbl_mult57
-rw-r--r--doc/user/tbl_plai84
-rw-r--r--doc/user/tbl_rows59
-rw-r--r--doc/user/tbl_rule192
-rw-r--r--doc/user/tbl_setu65
-rw-r--r--doc/user/tbl_span195
-rw-r--r--doc/user/tbl_summ255
-rw-r--r--doc/user/tbl_widt84
-rw-r--r--doc/user/typ27
-rw-r--r--doc/user/typ_apdf21
-rw-r--r--doc/user/typ_book420
-rw-r--r--doc/user/typ_illu85
-rw-r--r--doc/user/typ_ordi313
-rw-r--r--doc/user/typ_orga93
-rw-r--r--doc/user/typ_over314
-rw-r--r--doc/user/typ_plai76
-rw-r--r--doc/user/typ_repo359
-rw-r--r--doc/user/vbas3
-rw-r--r--doc/user/vfmt1
-rw-r--r--doc/user/vref1
-rw-r--r--doc/user/vstr2
-rw-r--r--doc/user/vtbl2
-rw-r--r--doc/user/vtyp2
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