Lout 3.18.

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

34 files changed, 1357 insertions, 294 deletions

diff --git a/doc/user/README b/doc/user/README
index fd69ccb..2363b0c 100644
--- a/doc/user/README
+++ b/doc/user/README
@@ -16,9 +16,9 @@ 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
+lout file "cpp_tabs" (from "cpp" line 80, from "all" line 45):
+   56,23: prg2lout 2,1: program text ended within comment
+   58,35: prg2lout 2,1: program text ended within 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.
@@ -31,7 +31,7 @@ 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".
+stored at "ftp://ftp.cs.su.oz.au/jeff/lout/lout-3.18.user.ps.gz".
 
 Jeffrey H. Kingston
-17 September 1999
+23 February 2000
diff --git a/doc/user/all b/doc/user/all
index 1b131f6..ef7fcdf 100644
--- a/doc/user/all
+++ b/doc/user/all
@@ -6,6 +6,7 @@
 @SysInclude { pas }
 @SysInclude { diag }
 @SysInclude { cprint }
+@SysInclude { eiffel }
 @SysInclude { book }
 # @Include { letterbook } # for testing Letter size formatting
 
@@ -19,10 +20,10 @@ Lout
 Document Formatting System
 }
     @Author { Jeffrey H. Kingston }
-    @Edition { Version 3.17
-September, 1999 }
+    @Edition { Version 3.18
+February, 2000 }
     @Publisher {
-Copyright @CopyRight 1991, 1999 Jeffrey H. Kingston,
+Copyright @CopyRight 1991, 2000 Jeffrey H. Kingston,
 Basser Department of Computer Science,
 The University of Sydney 2006, Australia.  ISBN 0 86758 951 5.
 }
diff --git a/doc/user/ap_qck b/doc/user/ap_qck
index 92ea7ad..092673d 100644
--- a/doc/user/ap_qck
+++ b/doc/user/ap_qck
@@ -56,8 +56,8 @@
 "    @PageHeaders { Simple }"
 "    @FirstPageNumber { 1 }"
 "    @ColumnNumber { 1 }"
+"    @Abstract { ... }"
 "//"
-"@Abstract ... @End @Abstract"
 "@Section ... @End @Section"
 "@Appendix ... @End @Appendix"
 }
diff --git a/doc/user/bas_lang b/doc/user/bas_lang
index 3b32a94..01fbf2d 100644
--- a/doc/user/bas_lang
+++ b/doc/user/bas_lang
@@ -45,6 +45,7 @@ Hungarian Magyar
 Italian Italiano
 Norwegian Norsk
 Polish Polski
+Portuguese Português
 Russian
 Slovenian Slovenia Slovenija
 Spanish Espa{@Char ntilde}ol
diff --git a/doc/user/bgr b/doc/user/bgr
index 9452ff0..86e0af4 100644
--- a/doc/user/bgr
+++ b/doc/user/bgr
@@ -10,6 +10,7 @@ get them.
 @BeginSections
 @Include { bgr_colo }
 @Include { bgr_boxs }
+@Include { bgr_outl }
 @Include { bgr_rota }
 @Include { bgr_scal }
 @Include { bgr_incl }
diff --git a/doc/user/bgr_outl b/doc/user/bgr_outl
new file mode 100644
index 0000000..af11eb1
--- /dev/null
+++ b/doc/user/bgr_outl
@@ -0,0 +1,16 @@
+@Section
+   @Title { Outlined words }
+   @Tag { outline }
+@Begin
+@PP
+The @@Outline symbol
+outline.sym @Index { @@Outline symbol }
+causes all the words in the following object (which may be
+arbitrary as usual) to be printed in outline.  For example,
+@ID @Code @Verbatim { @Outline @Box 24p @Font HELP }
+produces
+@ID @Outline @Box 24p @Font HELP
+There is no way to control the thickness of the outline, and
+@@Outline has no effect in PDF output.  On the other hand,
+it works with any font likely to be used in practice.
+@End @Section
diff --git a/doc/user/cpp b/doc/user/cpp
index 9b413ed..0e7748a 100644
--- a/doc/user/cpp
+++ b/doc/user/cpp
@@ -1,27 +1,86 @@
 @Chapter
-  @Title { C and C++ Programs }
+  @Title { Computer 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.
+This chapter describes how to typeset computer program text using Lout
+in conjunction with the @Code prg2lout
+prg2lout. @Index { @Code prg2lout filter program }
+@FootNote {
+Prior to Version 3.18 of Lout, this chapter described how to typeset
+programs written in the C programming language using the
+@Code c2lout filter, and Eiffel programs using the @Code eif2lout
+filter.  These have now been withdrawn and replaced by {@Code prg2lout},
+which handles multiple languages.  Ordinary Lout documents require no
+modifications as a result of this change.
+}
+filter program, which is always installed wherever Lout is.
 @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 }.
+It is possible to simply print out one or more program files independently
+of any document.  Alternatively, the program text may be printed as part of
+a larger Lout document.  Either way, Lout does not lay out the programs in
+the sense of choosing line breaks and indenting; it uses whatever line
+breaks and indenting you give to the program.  What Lout does do is cope
+with characters in the program text that it would ordinarily either reject
+or interpret in some way (braces and so on), ensuring that you can include
+program texts with absolutely no modifications; plus, if you wish, Lout
+will print keywords in bold, identifiers in italics, etc.
+@PP
+At the time of writing, the available programming languages are:
+eiffel. @Index { Eiffel program printing }
+c. @Index { C and C++ program printing }
+blue. @Index { Blue program printing }
+@CD @Tbl
+    mv { 0.5vx }
+    af { Italic }
+    arb { yes }
+    aformat { @Cell A | @Cell B | @Cell C | @Cell D | @Cell E }
+    bformat { @Cell A | @Cell @Code B | @Cell @Code C | @Cell @Code D | @Cell E }
+{
+@Rowa
+    A { Language name }
+    B { Setup file name }
+    C { Lout symbol }
+    D { Default style }
+    E { ` ' escapes }
+@Rowb
+    A { C, C++ }
+    B { cprint }
+    C { "@CP" }
+    D { fixed }
+    E { No }
+@Rowb
+    A { Eiffel }
+    B { eiffel }
+    C { "@Eiffel" }
+    D { varying }
+    E { Yes }
+@Rowb
+    A { Blue }
+    B { blue }
+    C { "@Blue" }
+    D { varying }
+    E { Yes }
+}
+C and C++ are handled together since, for formatting purposes, they
+differ only in that C++ has some additional keywords plus an extra
+way to make comments.  Whenever we mention C from now on, we mean
+both C and C++.  The second to fifth columns of this table will be
+explained at various points later in this chapter.
+@PP
+The list of languages is likely to expand, because the @Code "prg2lout"
+program has been designed to make it easy to add new languages.  Consult
+the instructions at the top of the source file of that program if you
+want to try it yourself.
 @BeginSections
 @Include { cpp_lone }
 @Include { cpp_embe }
+@Include { cpp_opti }
 @Include { cpp_chan }
-@Include { cpp_comm }
 @Include { cpp_tabs }
-@Include { cpp_eiff }
+@Include { cpp_comm }
+@Include { cpp_prog }
+@Include { cpp_pipe }
+@Include { cpp_erro }
 @EndSections
 @End @Chapter
diff --git a/doc/user/cpp_chan b/doc/user/cpp_chan
index ddedd51..bee0493 100644
--- a/doc/user/cpp_chan
+++ b/doc/user/cpp_chan
@@ -1,27 +1,28 @@
 @Section
-   @Title { Changing the default values }
+   @Title { Changing the appearance of all programs simultaneously }
    @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.
+We have just seen that the {@Code "@CP"}, {@Code "@Eiffel"} etc. symbols
+have many options for changing the appearance of the program text.  However,
+most people would not want to have a different style for every program text
+in their document; they want to define the style once at the start, and have
+all their program texts come out in that style without laboriously setting
+options on every symbol.  You do this 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
+values are in the @Code "@Use" clause which occupies most of the setup
+file.  Here is the @Code "@Use" clause from {@Code cprint}:
 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 "}" }
+@ID @Code @Tbl
+   mv { 0.5vx }
+   aformat { @Cell A | @Cell B | @Cell C }
+   bformat { @Cell { "    #" A } | @Cell { "{" B } | @Cell "}" }
 {
 @Rowa A { "@Use {  @CPSetup" }
+@Rowb A { "pipe" } B {          }
 @Rowb A { "style" } B { fixed         }
 
 @Rowa 
@@ -65,13 +66,13 @@ the @Code "cpsetup." setup file:
 
 @Rowa A { "}" }
 }
-These show the default font families, font faces, font sizes, line
+This shows 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.
+document.  The @Code pipe option will be explained in Section {@NumberOf pipes}.
 @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"
@@ -80,4 +81,11 @@ except that you want bold keywords.  Then one line needs to be changed, to
 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 }"}.
+@PP
+The setup files for the other languages are identical to this one, except
+that the symbol after @Code "@Use" is different, and some of the
+default values may be different.  Changing an option affects only the
+language of that setup file; if you have multiple languages you can
+have multiple setup files and change their options quite independently
+of each other.
 @End @Section
diff --git a/doc/user/cpp_comm b/doc/user/cpp_comm
index f877c06..96ac110 100644
--- a/doc/user/cpp_comm
+++ b/doc/user/cpp_comm
@@ -1,20 +1,27 @@
 @Section
-   @Title { Lout inside C comments }
+   @Title { Embedding Lout commands within program 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
+It is possible to embed Lout text inside program comments.  How this
+is done could in principle vary from language to language, but in
+every language supported so far it is done by starting off the comment
+with an @Code "@" character.  If the language has several ways to get
+a comment, this will work every way.  The entire comment after the @Code "@"
+character should then 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
+at that point.  (In this case you can also simply include a formfeed
+formfeed. @Index { formfeed in program texts }
+character, control-L, without any comment; whatever the language, a formfeed
+in program text is taken to be a request to start a new page.)  Or, to
+make a heading in an Eiffel program, do this:
+@ID @Code "--@ @Display @Heading { treeprint() }"
+(Eiffel comments begin with @Code "--" and end at the end of the
+line.)  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.
+inside the C code.  You probably can't go further, however, at least
+not in C, 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
deleted file mode 100644
index d0ec6df..0000000
--- a/doc/user/cpp_eiff
+++ /dev/null
@@ -1,42 +0,0 @@
-@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
index 8ca2dfc..0cefc84 100644
--- a/doc/user/cpp_embe
+++ b/doc/user/cpp_embe
@@ -1,11 +1,11 @@
 @Section
-   @Title { Embedded mode }
+   @Title { Typesetting computer programs as part of a larger document }
    @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:
+When the program texts are to be part of a larger Lout document,
+the procedure is somewhat different.  You need to include the setup file
+appropriate to your language, like this:
 @ID @OneRow @Code {
 "@SysInclude { cprint }"
 "@SysInclude { doc }"
@@ -13,9 +13,13 @@ the procedure is somewhat different.  You need to include the
 "..."
 "@End @Text"
 }
-This file includes everything needed to set up for C program formatting.
+The @Code cprint setup file includes everything needed to set up for C
+program formatting; for the other languages, consult the second column
+of the table at the start of this chapter.
 @PP
-The C parts of the document are enclosed in @Code "@CP { ... }" like this:
+The program texts within the Lout document are enclosed in braces
+preceded by the Lout symbol from the third column of the table, like
+this for the C language:
 @ID @OneRow @Code {
 "@IndentedDisplay @CP {"
 "#include <stdio.h>"
@@ -31,9 +35,10 @@ The C parts of the document are enclosed in @Code "@CP { ... }" like this:
 "}"
 "}"
 }
-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
+Although computer programs violate the rules of legal Lout input in many ways,
+these rules are suspended by the {@Code "@CP"}, {@Code "@Eiffel"} etc. symbols,
+allowing the program text to be incorporated with absolutely no
+modifications.  The result is
 @ID @OneRow @CP {
 #include <stdio.h>
 
@@ -49,104 +54,29 @@ struct tnode *p;
 }
 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.
+{@Code "@CP"}, {@Code "@Eiffel"} and the rest may appear anywhere at
+all:  the result is an object in the usual way, which may go
+anywhere.  When including a program text within a paragraph, use
+@Code "@OneCol @CP { ... }" (or @Code "@OneCol @Eiffel { ... }" etc. for
+other languages) 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.
+In cases where the program text has unbalanced braces, it is necessary to
+use the alternative form @Code "@CP @Begin ... @End @CP" (or the
+equivalent for other languages), so that Lout does not confuse program
+braces with Lout braces.  In that case the program text must not
+contain {@Code "@End"}; and in either case the program text must not
+include @Code "@Include" or @Code "@SysInclude" unless you are really
+including a file at that point (which is allowed, and follows the
+rules given for @Code "@Verbatim" in Section {@NumberOf verbatim}).
 @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}.
+If your Lout document contains program texts in several languages,
+simply add one @Code "@SysInclude" line for each of them and proceed
+as before.  If your programming language is not currently supported,
+a viable alternative is
+@ID @Code "@F @Verbatim { ... }"
+These symbols cause the text between braces to be set verbatim in
+a fixed-width font, as explained elsewhere in this guide.  This fallback
+method will not handle tab and formfeed characters very well.  Again,
+use @Code "@Begin" and @Code "@End @Verbatim" instead of braces if
+your program text contains unbalanced braces.
 @End @Section
diff --git a/doc/user/cpp_erro b/doc/user/cpp_erro
new file mode 100644
index 0000000..ff89591
--- /dev/null
+++ b/doc/user/cpp_erro
@@ -0,0 +1,39 @@
+@Section
+   @Title { Error messages }
+   @Tag { cpp_erro }
+@Begin
+@PP
+In order to understand the error messages produced by program
+printing, it is necessary to understand that Lout's first step when
+given a program text is to pass it to the separate {@Code prg2lout}
+program for analysis.  This separate program is the source of most
+of the error messages associated with program printing.
+@PP
+The {@Code prg2lout} program is quite happy to format a fragment of a
+computer program:  there is no need to supply a complete routine, or
+a complete statement, or any such thing.  However, it will complain if
+you supply only a fragment of one lexical unit, such as a comment or
+string without its terminating delimiter.  It will also complain if
+there is a character that cannot be classified as part of an identifier,
+number, etc. according to the rules of the language as they have been
+given to @Code prg2lout by the implementer.  Irrespective of the
+language rules, @Code prg2lout always interprets spaces, tabs, newlines,
+and formfeed characters in the usual way.
+@PP
+If an error message is generated by {@Code prg2lout}, it will contain
+a line and column number counting from the start of the program text
+involved.  Lout will precede this error message with a file name,
+line number, and column number pointing to the Lout symbol
+({@Code "@CP"}, {@Code "@Eiffel"} etc.) whose program text caused the
+error message, like this:
+@ID @Code @Verbatim {
+lout file "cpp_tabs" (from "cpp" line 80, from "all" line 45):
+   56,23: prg2lout 2,1: program text ended within comment
+}
+This is an actual message produced when formatting this chapter.  The
+program text in question has only one line, containing an incomplete comment,
+so when @Code "prg2lout" tried to start the second line and found nothing,
+it complained as shown.  In general, then, you have to add
+{@Code "prg2lout"}'s line number to Lout's line number, and use some
+initiative, to find the precise point of the problem.
+@End @Section
diff --git a/doc/user/cpp_lone b/doc/user/cpp_lone
index 8d8e367..a377d86 100644
--- a/doc/user/cpp_lone
+++ b/doc/user/cpp_lone
@@ -1,21 +1,22 @@
 @Section
-   @Title { Stand-alone mode }
+   @Title { Typesetting computer programs independently of any document }
    @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:
+Printing of program files independently of any document is accomplished by
+the following Unix pipeline:
+@ID @Code "prg2lout  -l language  options  files  |  lout  -s  >  out.ps"
+where @Code language stands for any one of the programming language
+names in the first column of the table above.  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
+{@Code -pvarying}, and {@Code -psymbol}, with the default value
+varying with the language as given in the fourth column of the
+table above.  Consult Section {@NumberOf embedded} for examples
 of these styles.
 }
 @TI { @Code -n } {
diff --git a/doc/user/cpp_opti b/doc/user/cpp_opti
new file mode 100644
index 0000000..538bda2
--- /dev/null
+++ b/doc/user/cpp_opti
@@ -0,0 +1,105 @@
+@Section
+   @Title { Changing the appearance of a program }
+   @Tag { cpp_opti }
+@Begin
+@PP
+The {@Code "@CP"}, {@Code "@Eiffel"} etc. symbols have a number of
+options for changing the appearance of the printed program.  These
+options are the same for all symbols, although their default values
+may vary.  The @Code "style" option changes the printing style; its
+value may be {@Code "fixed"} (fixed-width font), {@Code "varying"}
+(varying-width font), or {@Code "symbol"} (varying-width font with
+mathematical symbols used for some operators).  Its default value
+depends on the language, and may be found in the fourth column of
+the table at the start of this chapter.  The example in the previous
+section was in @Code fixed style; we can switch styles 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);
+        }
+}
+}
+If we use @Code "style { symbol }" we get this:
+@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);
+        }
+}
+}
+with mathematical symbols replacing some of the operators.
+@PP
+The {@Code "@CP"}, {@Code "@Eiffel"} etc. symbols have additional options
+which allow a finer control over the style.  Here they all are, with their
+default values:
+@ID @OneRow @Code {
+"@CP         [ or @Eiffel, @Blue, etc. ]"
+"    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 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_pipe b/doc/user/cpp_pipe
new file mode 100644
index 0000000..afbb87e
--- /dev/null
+++ b/doc/user/cpp_pipe
@@ -0,0 +1,57 @@
+@Section
+   @Title { Reading and selecting program text from separate files }
+   @Tag { pipes }
+@Begin
+@PP
+We have said that program text within @Code "@CP { ... }" and the other
+symbols is passed directly to @Code prg2lout for analysis.  However,
+there is an exception.  The program text may contain an
+@Code "@Include" or @Code "@SysInclude" command, which, as for the
+@Code "@Verbatim" symbol (Section {@NumberOf verbatim}), causes Lout
+to take the program text from a file:
+@ID @Code {
+"@Eiffel"
+"{"
+"    @Include { \"/usr/staff/jeff/Eiffel/hash.e\" }"
+"}"
+}
+The included file is not examined for balanced braces or @Code "@End" or
+{@Code "@Include"}; it is treated entirely verbatim and passed straight
+on to {@Code prg2lout}.  There may be several @Code "@Include" commands,
+and any amount of program text as well, within @Code "@CP { ... }" and
+the rest.
+@PP
+When including files in this way it often happens that only part of an
+actual program file is wanted for display.  Rather than placing the
+wanted part in a separate file, which is error-prone and tedious when
+the program is changing, Unix users can use the @Code "pipe" option
+to pipe the entire file through an arbitrary sequence of Unix commands,
+which may be used to make the wanted selection before the program text
+is passed to {@Code prg2lout}.
+@PP
+For example, suppose that all your Eiffel routines begin with the
+routine name one tab stop from the left margin and end at the first
+following @Eiffel { end } indented two tab stops.  Then
+@ID @Code {
+"@Eiffel"
+"    pipe { \"sed -n /^.insert/,/^..end/p\" }"
+"{"
+"    @Include { \"/usr/staff/jeff/Eiffel/hash.e\" }"
+"}"
+}
+will select just the @Eiffel { insert } routine from the @Code { hash.e }
+file.  Assuming that your program text has been laid out in a
+disciplined manner, every line of the selection will begin with a
+tab character that is not wanted in this display, so an even better
+pipe is
+@ID @Code {
+"@Eiffel"
+"    pipe { \"sed -n /^.insert/,/^..end/p | cut -c2-\" }"
+"{"
+"    @Include { \"/usr/staff/jeff/Eiffel/hash.e\" }"
+"}"
+}
+since it cuts away the unwanted tab characters.  Unfortunately, we
+can't show the result of this on an actual example, since that would
+prevent this manual from being formatted on a non-Unix system.
+@End @Section
diff --git a/doc/user/cpp_prog b/doc/user/cpp_prog
new file mode 100644
index 0000000..a049e3d
--- /dev/null
+++ b/doc/user/cpp_prog
@@ -0,0 +1,35 @@
+@Section
+   @Title { Embedding program text within program comments }
+   @Tag { cpp_prog }
+@Begin
+@PP
+The standard reference for the Eiffel language @Cite { $meyer1992eiffel }
+specifies that identifiers within comments may or should be enclosed
+in ` and ' so that they may be noticed and printed in an italic
+font:
+@ID lines @Break @F @Verbatim {
+@ID @Eiffel {
+deposit(amount: REAL) is
+        -- deposit `amount' dollars
+}
+}
+produces
+@ID @Eiffel {
+deposit(amount: REAL) is
+	-- deposit `amount' dollars
+}
+This has been generalized in Lout:  arbitrary text within an
+Eiffel comment between ` and ' will be treated as Eiffel text and
+printed accordingly.  Some other languages may also offer this
+feature:  see the fifth column of the table at the start of this
+chapter.  In principle the precise means of getting it could vary
+from language to language, but the languages available at the moment
+either do not have it at all, or else they use ` and ' like Eiffel.
+@PP
+On the subject of Eiffel, the Eiffel reference @Cite { $meyer1992eiffel }
+has some quite detailed style guidelines, and these have been closely
+followed in the implementation of the @Code "@Eiffel" symbol.  In
+particular, @Code "@Eiffel" prints dots larger than usual when they
+denote feature calls, as the example @OneCol @Eiffel { account.deposit(20) }
+shows.
+@End @Section
diff --git a/doc/user/cpp_tabs b/doc/user/cpp_tabs
index 1157a51..3a04bfa 100644
--- a/doc/user/cpp_tabs
+++ b/doc/user/cpp_tabs
@@ -1,28 +1,31 @@
 @Section
-   @Title { Tab characters }
+   @Title { Dealing with tab characters in programs }
    @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
+Tab characters provide a convenient way to indent and align parts of
+tab.c @Index { tab characters in programs }
+computer 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
+The distance between two tab stops in the program text 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.
+informs Lout that tab stops occur every 4 characters in the program
+text.  All the symbols ({@Code "@CP"}, {@Code "@Eiffel"}, etc.) and
+their setup files have this option and the next; but to save repetition
+we will stick with C for the rest of this section.
 @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,
+The distance between two tab stops 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,
+words, a distance of one tab stop in the program text will be equivalent to a
+distance of half an inch on the printed page.  For example,
 @ID @Code "@CP style { varying } tabout { 3f }"
-might produce the following, where tab characters in the input file
+might produce the following, where tab characters in the program text
 have been used for indenting and also to align the comments:
 @ID @OneRow @CP style { varying } tabout { 3f } {
 struct tnode {			/* the basic node */
@@ -37,7 +40,7 @@ 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
+If @Code "tabout" is too small, there is a danger that the
 alignment might fail.  For example,
 @ID @Code "@CP style { varying } tabout { 0.2i }"
 produces
@@ -56,7 +59,8 @@ 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
+When typesetting computer program texts independently of any document,
+there are @Code "-t" and @Code "-T" options to the @Code "prg2lout"
+program 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
index 4029cec..6462c88 100644
--- a/doc/user/dia
+++ b/doc/user/dia
@@ -6,6 +6,13 @@
 This chapter describes how to use the @@Diag symbol
 diag. @Index { @@Diag }
 @FootNote {
+Starting with Version 3.18 of Lout, the @@Diag symbol was enhanced with
+the {@Code "@ANode"}, {@Code "@BNode"}, and {@Code "@CNode"} symbols
+described in Section {@NumberOf dia_node}, and with the symbols for
+syntax diagrams described in Section {@NumberOf dia_synt}.  These
+enhancements are upwardly compatible, unless the user has defined
+symbols with these same names and used them within diagrams.
+@LP
 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
@@ -29,7 +36,7 @@ diag. @Index @Code "@Diag"
 // @Arrow from { E } to { D }
 }
 @@Diag offers nodes and links, arrows, labels, positioning using coordinates,
-and tree diagrams.
+tree diagrams, and syntax diagrams.
 @BeginSections
 @Include { dia_intr }
 @Include { dia_node }
@@ -38,6 +45,7 @@ and tree diagrams.
 @Include { dia_labe }
 @Include { dia_posi }
 @Include { dia_tree }
+@Include { dia_synt }
 @Include { dia_erro }
 @Include { dia_defi }
 @Include { dia_geom }
diff --git a/doc/user/dia_node b/doc/user/dia_node
index b72c6e2..8980978 100644
--- a/doc/user/dia_node
+++ b/doc/user/dia_node
@@ -79,10 +79,53 @@ 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.
+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
+Sometimes a diagram contains several different node types, each with
+its own combination of options (for example, the syntax diagrams of
+Section {@NumberOf dia_synt} have three node types).  To handle these
+cases there are three alternative versions of the @Code "@Node"
+symbol, called {@Code "@ANode"}, {@Code "@BNode"}, and
+anode.fig @Index { @Code "@ANode" in @Code "@Diag" }
+bnode.fig @Index { @Code "@BNode" in @Code "@Diag" }
+cnode.fig @Index { @Code "@CNode" in @Code "@Diag" }
+{@Code "@CNode"}.  These have exactly the same options as
+{@Code "@Node"}, but the @I default values of these options
+are different, in that they come from @Code "@Diag" options,
+or else setup file options, that have an extra letter in front
+of their name:  @Code { a }, @Code { b }, or @Code { c }.  Here is
+a small example (see later in this section for the @Code font option):
+@ID @OneRow {
+@Code @Verbatim {
+@Diag
+    aoutline { box }
+    afont { Italic }
+    boutline { curvebox }
+    bfont { Bold }
+{
+    @ANode identifier
+    @DP
+    @BNode keyword
+}
+}
+||7ct
+@Diag
+    aoutline { box }
+    afont { Italic }
+    boutline { curvebox }
+    bfont { Bold }
+{
+    @ANode identifier
+    @DP
+    @BNode keyword
+}
+}
+Note that when giving an option directly to {@Code "@ANode"},
+{@Code "@BNode"}, and {@Code "@CNode"}, the initial @Code { a },
+@Code { b }, or @Code { c } used with @Code "@Diag" and in the
+setup file is omitted.
 @PP
 To save time in simple cases, @Code "@Diag" provides nine other
 node symbols called
diff --git a/doc/user/dia_summ b/doc/user/dia_summ
index b9dc9e9..4539785 100644
--- a/doc/user/dia_summ
+++ b/doc/user/dia_summ
@@ -1212,6 +1212,93 @@ 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
+Here are all the syntax diagrams symbols, used within {@Code "@SyntaxDiag"}
+usually but also available within {@Code "@Diag"}.  To begin with we have
+the six starter symbols:
+@CD @SyntaxDiag {
+@Tbl
+    aformat { @Cell @Code A | @Cell B | @Cell | @Cell @Code C |
+	      @Cell D | @Cell | @Cell @Code E | @Cell F }
+{
+@Rowa
+    A { "@StartRight ..." }
+    B { @StartRight @ACell "..." }
+    C { "@StartUp ..." }
+    D { @StartUp @ACell "..." }
+    E {
+"@StartRightRight"
+      "A { ... }"
+      "B { ... }"
+}
+    F { @StartRightRight A { @ACell A } B { @ACell B } }
+@Rowa
+    A { "@StartLeft ..." }
+    B { @StartLeft @ACell "..." }
+    C { "@StartDown ..." }
+    D { @StartDown @ACell "..." }
+    E {
+"@StartRightDown"
+      "A { ... }"
+      "B { ... }"
+}
+    F { @StartRightDown A { @ACell A } B { @ACell B } }
+}
+}
+And here are all the syntax diagram types, shown in all four directions
+(right, up, left, and down).  @Code "@Sequence" and @Code "@Select" may
+have up to twelve options, {@Code "A"} to {@Code "L"}.
+@IndentedList
+
+@LI @SyntaxDiag { @Four code { "@ACell ..." } @ACell "..." }
+
+@LI @SyntaxDiag { @Four code { "@BCell ..." } @BCell "..." }
+
+@LI @SyntaxDiag { @Four code { "@CCell ..." } @CCell "..." }
+
+@LI @SyntaxDiag { @Four code { "@Skip"      } @Skip        }
+
+@LI @SyntaxDiag { @Four code {
+"@Sequence"
+      "A { ... }"
+      "B { ... }"
+      "C { ... }"
+} @Sequence A { @ACell A } B { @ACell B } C { @ACell C } }
+
+@LI @SyntaxDiag { @Four code {
+"@Select"
+      "A { ... }"
+      "B { ... }"
+      "C { ... }"
+} @Select A { @ACell A } B { @ACell B } C { @ACell C } }
+
+@LI @SyntaxDiag { @Four code { "@Optional ..." } @Optional @ACell "..." }
+
+@LI @SyntaxDiag { @Four code { "@OptionalDiverted ..." }
+	@OptionalDiverted @ACell "..." }
+
+@LI @SyntaxDiag { @Four code { "@Diverted ..." } @Diverted @ACell "..." }
+
+@LI @SyntaxDiag { @Four code {
+"@Loop"
+      "A { ... }"
+      "B { ... }"
+} @Loop A { @ACell A } B { @ACell B } }
+
+@LI @SyntaxDiag { @Four code { "@Repeat ..." } @Repeat @ACell "..." }
+
+@LI @SyntaxDiag { @Four code {
+"@LoopOpposite"
+      "A { ... }"
+      "B { ... }"
+} @LoopOpposite A { @ACell A } B { @ACell B } }
+
+@LI @SyntaxDiag { @Four code { "@RepeatOpposite ..." }
+	@RepeatOpposite @ACell "..." }
+
+@LI @SyntaxDiag { @Four code { "@RepeatDiverted ..." }
+	@RepeatDiverted @ACell "..." }
+
+@EndList
 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
@@ -1240,8 +1327,16 @@ options:
   B { 0.5f }
   C { any length from Section {@NumberOf objects} }
 @Rowa
-  A { "   treevsep" }
-  B { 0.5f }
+  A { "   syntaxgap" }
+  B { 0.35f }
+  C { any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   syntaxbias" }
+  B { 1.0f }
+  C { any length from Section {@NumberOf objects} }
+@Rowa
+  A { "   syntaxradius" }
+  B { 0.3f }
   C { any length from Section {@NumberOf objects} }
 }
 @DP
diff --git a/doc/user/dia_synt b/doc/user/dia_synt
new file mode 100644
index 0000000..6cef550
--- /dev/null
+++ b/doc/user/dia_synt
@@ -0,0 +1,573 @@
+@Section
+    @Tag { dia_synt }
+    @Title { Syntax diagrams }
+@Begin
+@PP
+A variant of the @@Diag symbol, called {@Code "@SyntaxDiag"},
+syntax.diag @Index { @Code "@SyntaxDiag" symbol }
+syntax.diagrams @Index { syntax diagrams }
+railroad.diagrams @Index { railroad diagrams }
+produces syntax diagrams (sometimes called railroad diagrams):
+@CD @SyntaxDiag
+    title { call-chain }
+{
+    @StartRight @Sequence
+        A { @Optional @Sequence
+                A { @BCell "super" }
+                B { @CCell "!" }
+          }
+        B { @Loop
+                A { @Sequence
+                        A { @ACell identifier }
+                        B { @Optional @Sequence
+                                A { @CCell "(" }
+                                B { @Loop
+                                        A { @ACell expression }
+                                        B { @CCell "," }
+                                  }
+                                C { @CCell ")" }
+                          }
+                  }
+                B { @CCell "." }
+          }
+}
+These are used to define the syntax of computer programming languages,
+although they could be put to other uses.  We'll explain how to get
+syntax diagrams first.  At the end of this section is an explanation of
+how to change the formats of things, which people who use these diagrams
+for other purposes will probably need to do.
+@PP
+A syntax diagram can be @I { right-moving }, which means it starts
+at the left and heads right (like the example above), or it can be
+@I { down-moving }, starting at the top and heading downwards.  The
+@Code "@StartRight" and @Code "@StartDown" symbols are used at the start
+of the diagram to say which of these directions is wanted:
+@ID @OneRow @Code @Verbatim {
+@SyntaxDiag
+    title { call-chain }
+{
+    @StartRight ...
+}
+}
+where @Code { ... } stands for the rest of the diagram, as we are about
+to describe.  For completeness there are also @Code "@StartLeft" and
+@Code "@StartUp" symbols, but diagrams never start off in these directions.
+@PP
+The @Code title option is optional; if given, the effect is as shown
+(this option is also available with {@Code "@Diag"}).  Subsequent
+examples will omit the enclosing {@Code "@SyntaxDiag { ... }"}.
+@PP
+The basic components of syntax diagrams are @I { category cells },
+shown as boxes in the example above and obtained with the
+@Code "@ACell" symbol; @I { keyword cells }, shown as curved boxes
+and obtained with {@Code "@BCell"}; and @I { punctuation cells },
+containing punctuation symbols small enough to be enclosed in circles,
+and obtained with {@Code "@CCell"}.  After each symbol, place whatever
+has to go inside the cell:
+@ID @OneRow {
+@Code @Verbatim { @StartRight @BCell loop }
+|7ct
+@SyntaxDiag {
+@StartRight @BCell loop
+}
+}
+Lout will insert the appropriate arrows, taking account of which
+direction (right, up, left, or down) the diagram is currently
+moving.  This is true for all the syntax diagram symbols; we
+won't mention it again.
+@FootNote {
+This wonderfully useful effect is achieved by a dirty trick, one
+of whose consequences is that if you see an error message
+similar to `@Code { replacing unknown "@Case" option 0p by 1p }'
+it means you've forgotten the initial @Code "@StartRight" or
+whatever.
+}
+@PP
+Occasionally, instead of a cell one wants the horizontal or
+vertical line to continue uninterrupted.  For this there is
+the @Code "@Skip" symbol:
+@ID @OneRow {
+@Code @Verbatim { @StartDown @Skip }
+|7ct
+@SyntaxDiag {
+@StartDown @Skip
+}
+}
+Some examples of its use in practice appear below.
+@PP
+There are three main ways to build up larger syntax diagrams out
+of smaller ones:  @I { sequencing }, @I { selection }, and
+@I { looping }.  For sequencing there is the @Code "@Sequence" symbol:
+@ID @OneRow {
+@Code @Verbatim {
+@StartRight @Sequence
+    A { @BCell loop }
+    B { @ACell statements }
+    C { @BCell end }
+}
+||7ct
+@SyntaxDiag {
+@StartRight @Sequence
+    A { @BCell loop }
+    B { @ACell statements }
+    C { @BCell end }
+}
+}
+This is what the sequence looks like in the other three directions:
+@CD @OneRow @SyntaxDiag {
+@Tbl
+    mh { 1f }
+    mv { 0i }
+    iv { top }
+    aformat { @Cell ml { 0i } @StartUp A | @Cell @StartLeft A |
+	      @Cell mr { 0i } @StartDown A }
+{
+@Rowa A {
+@Sequence
+    A { @BCell loop }
+    B { @ACell statements }
+    C { @BCell end }
+}
+} }
+Whatever the direction, the arrows go from option @Code A to option @Code B
+to option @Code C and so on.  You can have up to twelve items in the
+sequence, in options @Code A to {@Code L}; if more than twelve are needed,
+just place another sequence inside any one of these options:  where one
+syntax diagram is allowed, any syntax diagram is allowed, provided there
+is enough space on the page (Lout makes a total mess of any diagram that
+is too wide to fit on the page).
+@PP
+After sequencing comes selection, which is obtained with the
+@Code "@Select" symbol:
+@ID @OneRow {
+@Code @Verbatim {
+@StartRight @Select
+    A { @ACell asst }
+    B { @ACell call-chain }
+    C { @Sequence
+           A { @BCell assert }
+           B { @ACell condition }
+      }
+}
+||7ct
+@SyntaxDiag {
+@StartRight @Select
+    A { @ACell asst }
+    B { @ACell call-chain }
+    C { @Sequence
+           A { @BCell assert }
+           B { @ACell condition }
+      }
+}
+}
+This example shows right-moving selection of three alternatives,
+the third being a sequence of things.  Here is the same example
+in the other three directions:
+@CD @OneRow @SyntaxDiag {
+@Tbl
+    mh { 1f }
+    mv { 0i }
+    iv { top }
+    aformat { @Cell ml { 0i } @StartUp A | @Cell @StartLeft A |
+	      @Cell mr { 0i } @StartDown A }
+{
+@Rowa A {
+@Select
+    A { @ACell asst }
+    B { @ACell call-chain }
+    C { @Sequence
+           A { @BCell assert }
+           B { @ACell condition }
+      }
+} } }
+When building up complex diagrams like this, it pays to keep the indenting
+perfect in the source document.  As with sequences, there can be
+up to twelve alternatives, in options from @Code A to {@Code L}.
+@PP
+To say that something is @I optional is to select either that thing or
+nothing:
+@ID @OneRow {
+@Code @Verbatim {
+@StartRight @Select
+    A { @Skip }
+    B { @ACell parameters }
+}
+||7ct
+@SyntaxDiag {
+@StartRight @Select
+    A { @Skip }
+    B { @ACell parameters }
+}
+}
+Since this case is so common, there is an @Code "@Optional" symbol for it:
+@ID @OneRow {
+@Code @Verbatim {
+@StartRight @Optional
+@ACell parameters
+}
+||7ct
+@SyntaxDiag {
+@StartRight @Optional
+@ACell parameters
+}
+}
+@Code "@Optional" is exactly like @Code "@Select" with option @Code A
+set to @Code "@Skip" and option @Code B set to the syntax diagram
+following the @Code "@Optional" symbol.  Here is the same example in
+the other three directions:
+@CD @OneRow @SyntaxDiag {
+@Tbl
+    mh { 1f }
+    mv { 0i }
+    iv { top }
+    aformat { @Cell ml { 0i } @StartUp A | @Cell @StartLeft A |
+	      @Cell mr { 0i } @StartDown A }
+{
+@Rowa A {
+@Optional @ACell parameters
+} } }
+There is another kind of `optional' layout, {@Code "@OptionalDiverted"}:
+@ID @OneRow {
+@Code @Verbatim {
+@StartDown @OptionalDiverted
+@Sequence
+    A { @BCell creation }
+    B { @ACell parameters }
+}
+||7ct
+@SyntaxDiag {
+@StartDown @OptionalDiverted @Sequence
+    A { @BCell creation }
+    B { @ACell parameters }
+}
+}
+Here is the same example in the other three directions:
+@CD @OneRow @SyntaxDiag {
+@Tbl
+    mh { 1f }
+    mv { 0i }
+    iv { top }
+    aformat { @Cell ml { 0i } @StartRight A | @Cell @StartUp A |
+	      @Cell mr { 0i } @StartLeft A }
+{
+@Rowa A {
+@OptionalDiverted @Sequence
+    A { @BCell creation }
+    B { @ACell parameters }
+} } }
+The optional material goes in a direction perpendicular to what
+it would have otherwise:  right-moving if previously up or down, and
+down-moving if previously left or right.
+@PP
+Another, related symbol is {@Code "@Diverted"}; it is similar to
+@Code "@OptionalDiverted" but without the path which produces nothing:
+@ID @OneRow {
+@Code @Verbatim {
+@StartDown @Diverted @Sequence
+    A { @BCell creation }
+    B { @ACell parameters }
+}
+||7ct
+@SyntaxDiag {
+@StartDown @Diverted @Sequence
+    A { @BCell creation }
+    B { @ACell parameters }
+}
+}
+Here is the same example in the other three directions:
+@CD @OneRow @SyntaxDiag {
+@Tbl
+    mh { 1f }
+    mv { 0i }
+    iv { top }
+    aformat { @Cell ml { 0i } @StartRight A | @Cell @StartUp A |
+	      @Cell mr { 0i } @StartLeft A }
+{
+@Rowa A {
+@Diverted @Sequence
+    A { @BCell creation }
+    B { @ACell parameters }
+} } }
+This symbol is a great aid to packing a big syntax diagram into a
+compact shape.
+@PP
+That covers sequencing and selection; now for looping.  The @Code "@Loop"
+symbol produces a loop, with option @Code A going forwards and option
+@Code B centred and going backwards:
+@ID @OneRow {
+@Code @Verbatim {
+@StartRight @Loop
+    A { @Sequence
+           A { @ACell identifier }
+           B { @CCell : }
+           C { @ACell type }
+      }
+    B { @CCell , }
+}
+||7ct
+@SyntaxDiag {
+@StartRight @Loop
+    A { @Sequence
+           A { @ACell identifier }
+           B { @CCell : }
+           C { @ACell type }
+      }
+    B { @CCell , }
+}
+}
+Here is the same example in the other three directions:
+@CD @OneRow @SyntaxDiag {
+@Tbl
+    mh { 1f }
+    mv { 0i }
+    iv { top }
+    aformat { @Cell ml { 0i } @StartUp A | @Cell @StartLeft A |
+	      @Cell mr { 0i } @StartDown A }
+{
+@Rowa A {
+@Loop
+    A { @Sequence
+           A { @ACell identifier }
+           B { @CCell : }
+           C { @ACell type }
+      }
+    B { @CCell , }
+} } }
+One common case of looping is to have nothing on the way back.  We could
+get this by placing @Code "@Skip" in option {@Code B} of {@Code "@Loop"},
+but there is an even easier way, the {@Code "@Repeat"} symbol:
+@ID @OneRow {
+@Code @Verbatim {
+@StartRight @Repeat
+@ACell statement
+}
+||7ct
+@SyntaxDiag {
+@StartRight @Repeat
+@ACell statement
+}
+}
+Here is the same example in the other three directions:
+@CD @OneRow @SyntaxDiag {
+@Tbl
+    mh { 1f }
+    mv { 0i }
+    iv { top }
+    aformat { @Cell ml { 0i } @StartUp A | @Cell @StartLeft A |
+	      @Cell mr { 0i } @StartDown A }
+{
+@Rowa A {
+@Repeat
+@ACell statement
+} } }
+Occasionally it looks better to have the empty returning arrow go on
+the opposite side of the forward part; for that, there are
+@Code "@LoopOpposite" and @Code "@RepeatOpposite" symbols:
+@ID @OneRow {
+@Code @Verbatim {
+@StartRight @LoopOpposite
+    A { @Sequence
+           A { @ACell identifier }
+           B { @CCell : }
+           C { @ACell type }
+      }
+    B { @CCell , }
+}
+||7ct
+@SyntaxDiag {
+@StartRight @LoopOpposite
+    A { @Sequence
+           A { @ACell identifier }
+           B { @CCell : }
+           C { @ACell type }
+      }
+    B { @CCell , }
+}
+}
+Here is the same example in the other three directions:
+@CD @OneRow @SyntaxDiag {
+@Tbl
+    mh { 1f }
+    mv { 0i }
+    iv { top }
+    aformat { @Cell ml { 0i } @StartUp A | @Cell @StartLeft A |
+	      @Cell mr { 0i } @StartDown A }
+{
+@Rowa A {
+@LoopOpposite
+    A { @Sequence
+           A { @ACell identifier }
+           B { @CCell : }
+           C { @ACell type }
+      }
+    B { @CCell , }
+} } }
+@Code "@RepeatOpposite" is particularly useful around a large
+{@Code "@Select"}:
+@ID @OneRow {
+@Code @Verbatim {
+@StartRight @RepeatOpposite
+@Select
+    A { @ACell asst }
+    B { @ACell call-chain }
+    C { @BCell return }
+    D { @Sequence
+           A { @BCell assert }
+           B { @ACell condition }
+      }
+    E { @ACell conditional }
+    F { @ACell selection }
+    G { @ACell loop }
+}
+||7ct
+@SyntaxDiag {
+@StartRight @RepeatOpposite
+@Select
+    A { @ACell asst }
+    B { @ACell call-chain }
+    C { @BCell return }
+    D { @Sequence
+           A { @BCell assert }
+           B { @ACell condition }
+      }
+    E { @ACell conditional }
+    F { @ACell selection }
+    G { @ACell loop }
+}
+}
+since it clearly distinguishes the loop from the selection.
+@PP
+Finally, the @Code "@RepeatDiverted" symbol combines the two ideas
+of repetition and diversion:
+@ID @OneRow {
+@Code @Verbatim {
+@StartDown @RepeatDiverted
+@ACell statement
+}
+||7ct
+@SyntaxDiag {
+@StartDown @RepeatDiverted
+@ACell statement
+}
+}
+Here is the same example in the other three directions:
+@CD @OneRow @SyntaxDiag {
+@Tbl
+    mh { 1f }
+    mv { 0i }
+    iv { top }
+    aformat { @Cell ml { 0i } @StartRight A | @Cell @StartUp A |
+	      @Cell mr { 0i } @StartLeft A }
+{
+@Rowa A {
+@RepeatDiverted
+@ACell statement
+} } }
+There is no {@Code "@LoopDiverted"} symbol, for good reason.
+@PP
+Every syntax diagram, from the simplest to the most complex, has
+one arrow going into it, and one coming out.  There are no exceptions
+to this rule.  In most syntax diagrams, these two arrows lie on the
+same (invisible) line and point in the same direction, and this is
+the direction that we say the diagram is moving.  There are two symbols
+that produce syntax diagrams that lack this second property.  Because
+of this lack, these symbols cannot be used at arbitrary places in a
+complex diagram; they can only be used instead of the @Code "@StartRight"
+or @Code "@StartDown" symbols at the beginning of a diagram.  The first
+symbol, {@Code "@StartRightDown"}, prints its option @Code A right-moving
+and its option @Code B down-moving like this:
+@ID @OneRow {
+@Code @Verbatim {
+@StartRightDown
+    A { @ACell A }
+    B { @ACell B }
+}
+||7ct
+@SyntaxDiag {
+@StartRightDown
+    A { @ACell A }
+    B { @ACell B }
+}
+}
+The second symbol, {@Code "@StartRightRight"}, prints both options
+right-moving like this:
+@ID @OneRow {
+@Code @Verbatim {
+@StartRightRight
+    A { @ACell A }
+    B { @ACell B }
+}
+||7ct
+@SyntaxDiag {
+@StartRightRight
+    A { @ACell A }
+    B { @ACell B }
+}
+}
+As usual, the options to these symbols may contain arbitrarily complex
+syntax diagrams.
+@PP
+Finally, a few words about changing things.  The @Code "@SyntaxDiag"
+symbol used the {@Code "@ANode"}, {@Code "@BNode"}, and {@Code "@CNode"}
+symbols of @@Diag to construct its three types of cells.  In fact, the
+@Code "@SyntaxDiag" symbol is nothing more than this:
+@ID @OneRow @Code @Verbatim {
+@Diag
+    avalign { mark }
+    avstrut { yes }
+    amargin { 0.2f }
+    aoutline { box }
+    afont { Italic }
+    bvalign { mark }
+    bvstrut { yes }
+    bmargin { 0.2f }
+    boutline { curvebox }
+    bfont { Bold }
+    cvalign { mark }
+    cvstrut { yes }
+    cmargin { 0.2f }
+    coutline { circle }
+    chsize { 1f }
+    arrowlength { 0.4f }
+}
+So any of the other @Code "@Diag" options can be used freely with
+{@Code "@SyntaxDiag"}; and the format of the three cell types can be
+changed by using @Code "@Diag" instead of {@Code "@SyntaxDiag"}, and
+choosing new values for these (and other) options.
+@PP
+If there are more than three cell types, it is necessary to fall back
+on the {@Code "@XCell"} symbol, which produces a cell without nominating
+any particular cell type.  After @Code "@XCell" there must be a regular
+@Code "@Diag" node, like this:
+@ID @OneRow {
+@Code @Verbatim {
+@StartRight @XCell @Ellipse INIT
+}
+|7ct
+@SyntaxDiag {
+@StartRight @XCell @Ellipse INIT
+}
+}
+This way there is no limit to the number of different kinds of cells.  Also,
+since (for example) @Code "@ACell" is merely an abbreviation for
+@ID @OneRow @Code @Verbatim { @XCell @ANode }
+any node options may follow {@Code "@ACell"}, {@Code "@BCell"}, and
+{@Code "@CCell"}.  The appearance of the arrows can be changed in the usual
+way, by setting options as has been done above for {@Code "arrowlength"}.
+@PP
+There are three options specifically related to syntax diagrams:
+@ID @OneRow @Code @Verbatim {
+@SyntaxDiag
+    syntaxgap { 0.35f }
+    syntaxbias { 1.0f }
+    syntaxradius { 0.3f }
+}
+The @Code syntaxgap option determines the spacing between the various
+elements; changing it causes the syntax diagrams to be set tighter or
+looser in a consistent way.  The default value shown is 0.35 times the
+current font size.  The @Code syntaxbias and @Code syntaxradius
+options affect the appearance of curved lines, as in @Code "@RVLCurve"
+and its relatives.  These options are also available with {@Code "@Diag"},
+and in the setup file.  Note however that these options cannot be given to
+individual elements in a syntax diagram, only to the diagram as a whole.
+@End @Section
diff --git a/doc/user/equ_summ b/doc/user/equ_summ
index bcfbeb3..b1e6fbc 100644
--- a/doc/user/equ_summ
+++ b/doc/user/equ_summ
@@ -37,6 +37,9 @@ and full names.  The auxiliary symbols are:
 @Rowa
     A { @Code "big x" }
     B { Make @Code x larger }
+@Rowa
+    A { @Code "small x" }
+    B { Make @Code x smaller }
 }
 Here are all the parameterized symbols, shown in groups of equal
 precedence, with the precedence itself at right:
@@ -262,6 +265,7 @@ ragged @Break {
 "propto"	@Dbl @Eq {  propto		}
 "models"	@Dbl @Eq {  models		}
 "doteq"		@Dbl @Eq {  doteq		}
+"trieq"		@Dbl @Eq {  trieq		}
 "perp"		@Dbl @Eq {  perp		}
 "notsub"	@Dbl @Eq {  notsub		}
 "notin"		@Dbl @Eq {  notin		}
@@ -504,6 +508,7 @@ ragged @Break {
 "exists"	@Dbl @Eq {  exists		}
 "neg"		@Dbl @Eq {  neg			}
 "circle"	@Dbl @Eq {  circle		}
+"filledcircle"	@Dbl @Eq {  filledcircle	}
 "square"	@Dbl @Eq {  square		}
 "ldots"		@Dbl @Eq {  ldots		}
 "cdots"		@Dbl @Eq {  cdots		}
diff --git a/doc/user/johnson b/doc/user/johnson
new file mode 100644
index 0000000..aaedd4c
--- /dev/null
+++ b/doc/user/johnson
@@ -0,0 +1,19 @@
+@SysInclude { fig }
+@SysInclude { diag }
+@SysInclude { eq }
+@SysInclude { tbl }
+@SysInclude { doc }
+@Doc @Text @Begin
+@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 }
+}
+@End @Text
diff --git a/doc/user/johnson.out b/doc/user/johnson.out
new file mode 100644
index 0000000..ead54ef
--- /dev/null
+++ b/doc/user/johnson.out
@@ -0,0 +1,66 @@
+
+
+
+
+
+
+               ...................................................
+               .                .                                .
+               . Johnson        . Johnson suddenly uttered, in   .
+               . suddenly       . a strong determined tone, an   .
+               . uttered,       . apophegm, at which many will   .
+               . in a strong    . start:  `Patriotism is the     .
+               . determined     . last refuge of a scoundrel.'   .
+               . tone, an       .                                .
+               . apophegm, at   .                                .
+               . which many     ..................................
+               . will start:    .               .                .
+               . `Patriotism    . Johnson       . Johnson        .
+               . is the last    . suddenly      . suddenly       .
+               . refuge of a    . uttered,      . uttered,       .
+               . scoundrel.'    . in a strong   . in a strong    .
+               .                . determined    . determined     .
+               .                . tone, an      . tone, 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, in   .                .
+               . a strong determined tone, an   .                .
+               . apophegm, at which many will   .                .
+               . start:  `Patriotism is the     .                .
+               . last refuge of a scoundrel.'   .                .
+               .                                .                .
+               .                                .                .
+               ...................................................
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/user/mydefs b/doc/user/mydefs
index 2ef9639..727bb27 100644
--- a/doc/user/mydefs
+++ b/doc/user/mydefs
@@ -39,6 +39,7 @@
    def @@OneCol            { @Code "@OneCol"            }
    def @@OneRow            { @Code "@OneRow"            }
    def @@Open              { @Code "@Open"              }
+   def @@Outline           { @Code "@Outline"             }
    def @@PAdjust           { @Code "@PAdjust"           }
    def @@PrependGraphic    { @Code "@PrependGraphic"    }
    def @@Rotate            { @Code "@Rotate"            }
@@ -189,7 +190,7 @@ which many will start:  `Patriotism is the last refuge of a scoundrel.'
    def @AmberLight
    {
        @OneRow @Tbl
-           aformat { @Cell A }
+           aformat { @Cell indentvertical { align } A }
            marginhorizontal { 0i }
            marginvertical { 0i }
            strut { no }
@@ -201,3 +202,13 @@ which many will start:  `Patriotism is the last refuge of a scoundrel.'
             @Rowa A { @OpenCircle }
         }
    }
+
+   import @DiagSetup @Diag
+   def @Four named code { } right x
+   {
+       3.8c @Wide @Code code    ||0.3c
+       2.7c @Wide @StartRight x ||0.3c
+       2.7c @Wide @StartUp    x ||0.3c
+       2.7c @Wide @StartLeft  x ||0.3c
+       2.2c @Wide @StartDown  x
+   }
diff --git a/doc/user/preface b/doc/user/preface
index eada554..9b3e964 100644
--- a/doc/user/preface
+++ b/doc/user/preface
@@ -16,9 +16,9 @@ with the software.
 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"
+@ID @Code "ftp://ftp.cs.usyd.edu.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
+(currently {@Code "lout-3.18.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
diff --git a/doc/user/tbl b/doc/user/tbl
index 230c69e..5ed15e1 100644
--- a/doc/user/tbl
+++ b/doc/user/tbl
@@ -27,6 +27,13 @@ matrix atleft { ( } atright { ) } { n above k } a sup k b sup n-k
 }
 As the example shows, the tables may contain spanning columns, aligned
 columns, and rules, and the cells may contain arbitrary objects.
+@FootNote {
+There has been a slight change to {@Code "@Tbl"}, starting with Version
+3.18:  if you want columns whose entries are aligned (on decimal points,
+equals signs, etc.), or the analogous thing with rows, you have to ask
+for it now, whereas before it happened automatically.  See
+Section {@NumberOf tbl_alig} for the details.
+}
 @BeginSections
 
 @Include { tbl_intr } # introduction
diff --git a/doc/user/tbl_alig b/doc/user/tbl_alig
index 24b6864..0032e86 100644
--- a/doc/user/tbl_alig
+++ b/doc/user/tbl_alig
@@ -7,19 +7,21 @@ 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 }
+    aformat { @Cell indent { align } 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
+To produce this you need two steps.  First, indicate that you want
+an aligned column, using @Code "indent { align }" on the relevant
+cell; and second, place 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 }
+    aformat { @Cell indent { align } A }
 {
 @Rowa A { 5^.46 }
 @Rowa A { 3^.4159 }
@@ -27,12 +29,17 @@ each entry:
 }
 }
 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.
+example at the start of this chapter).
 @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
+Owing to problems behind the scenes, in a column in which one cell is
+labelled {@Code "indent { align }"}, all the other cells have to be
+so labelled, otherwise Lout make a mess of things.  This is a problem
+when we want to get a heading over the top of an aligned column:  if
+we follow the rule, the @I heading gets aligned, which is wrong; but
+if we don't, Lout makes a mess of things.  There is no ideal solution
+to this problem.
+@PP
+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:
@@ -51,14 +58,14 @@ an empty second column. }
 @Rowb A { 5772^ }
 }
 }
-The spanning frees the heading from alignment, permitting
-@Code "indent { ctr }" to work:
+The spanning quarantines the centred cell from the aligned cells,
+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 }
+@Rowa A { V } marginabove { 0i }
 @Rowb A { 5^.46 }
 @Rowb A { 3^.4159 }
 @Rowb A { 5772^ } marginbelow { 0i }
diff --git a/doc/user/tbl_inde b/doc/user/tbl_inde
index 75a3471..22f89cc 100644
--- a/doc/user/tbl_inde
+++ b/doc/user/tbl_inde
@@ -10,19 +10,18 @@ horizontally.  For example,
 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
+of this option are {@Code "left"} (the default value), {@Code "right"},
+{@Code "align"} (Section {@NumberOf tbl_alig}), 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
+renamed {@Code "top"}, @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 }
diff --git a/doc/user/tbl_mark b/doc/user/tbl_mark
index 8761979..fcd4768 100644
--- a/doc/user/tbl_mark
+++ b/doc/user/tbl_mark
@@ -44,7 +44,7 @@ import @TblSetup
 def @AmberLight
 {
     @OneRow @Tbl
-         aformat { @Cell A }
+         aformat { @Cell indentvertical { align } A }
          margin { 0i }
          strut { no }
          paint { no }  rule { no }
diff --git a/doc/user/tbl_plai b/doc/user/tbl_plai
index 0813717..d887b86 100644
--- a/doc/user/tbl_plai
+++ b/doc/user/tbl_plai
@@ -7,35 +7,40 @@ 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.'    .               .
-.                                 .               .
-.                                 .               .
+.                .                                .
+. Johnson        . Johnson suddenly uttered, in   .
+. suddenly       . a strong determined tone, an   .
+. uttered,       . apophegm, at which many will   .
+. in a strong    . start:  `Patriotism is the     .
+. determined     . last refuge of a scoundrel.'   .
+. tone, an       .                                .
+. apophegm, at   .                                .
+. which many     ..................................
+. will start:    .               .                .
+. `Patriotism    . Johnson       . Johnson        .
+. is the last    . suddenly      . suddenly       .
+. refuge of a    . uttered,      . uttered,       .
+. scoundrel.'    . in a strong   . in a strong    .
+.                . determined    . determined     .
+.                . tone, an      . tone, 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, in   .                .
+. a strong determined tone, 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
diff --git a/doc/user/tbl_span b/doc/user/tbl_span
index 5621961..ec568dc 100644
--- a/doc/user/tbl_span
+++ b/doc/user/tbl_span
@@ -134,12 +134,12 @@ 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 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
diff --git a/doc/user/tbl_summ b/doc/user/tbl_summ
index 6fed734..53f957e 100644
--- a/doc/user/tbl_summ
+++ b/doc/user/tbl_summ
@@ -58,10 +58,12 @@ plain text }
     D { any length e.g. @Code 3c }
 @Rowa
     A { indent  i }
-    D { {@Code left}, {@Code ctr}, {@Code mctr}, {@Code right}, or any length }
+    B { @Code left }
+    D { {@Code left}, {@Code ctr}, {@Code align}, {@Code mctr}, {@Code right}, or any length }
 @Rowa
     A { indentvertical  iv }
-    D { {@Code top}, {@Code ctr}, {@Code mctr}, {@Code foot}, or any length }
+    B { @Code top }
+    D { {@Code top}, {@Code ctr}, {@Code align}, {@Code mctr}, {@Code foot}, or any length }
 @Rowa
     A { strut  s }
     B { yes }
diff --git a/doc/user/vcpp b/doc/user/vcpp
new file mode 100644
index 0000000..b7c18ca
--- /dev/null
+++ b/doc/user/vcpp
@@ -0,0 +1 @@
+vi cpp cpp_lone cpp_embe cpp_opti cpp_chan cpp_tabs cpp_comm cpp_prog cpp_pipe cpp_erro