Lout 3.32.

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

16 files changed, 326 insertions, 124 deletions

diff --git a/doc/user/README b/doc/user/README
index e65b183..2147e56 100644
--- a/doc/user/README
+++ b/doc/user/README
@@ -4,21 +4,25 @@ 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
+	lout -r6 all > user.ps
 
-in this directory.  Owing to some unfortunate page breaks in the
-early runs, this must be done six 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.
+in this directory.  The -r6 flag causes Lout to run over the
+document six times.  This is needed to completely resolve all
+cross references, although a readable PostScript file would be
+produced after one run if -r was omitted.  Auxiliary files with
+.li and .ld suffixes will be created in this directory.  Six runs
+is an unusually large number; it is owing to some unfortunate page
+breaks in the early runs that so many runs are needed.
 
 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 later runs for A4 size printing:
+error message output on the last run for A4 size printing:
 
-  lout file "str_foot" (from "str" line 8, from "all" line 38):
-     11,13: 1.0c object too high for 0.6c space; will try elsewhere
+  lout:
+	  : lout -r beginning run 6:
+  lout file "str_glos" (from "str" line 15, from "all" line 38):
+       8,1: 1.0c object too high for 1.0c space; will try elsewhere
   lout file "str_indx" (from "str" line 16, from "all" line 38):
       54,1: 0.3c object too high for 0.2c space; will try elsewhere
   lout file "gra_summ" (from "gra" line 44, from "all" line 46):
@@ -27,20 +31,19 @@ error message output on the later runs for A4 size printing:
      66,23: prg2lout 2,1: program text ended within comment
      68,35: prg2lout 2,1: program text ended within comment
 
-The first two warnings are about footnotes that did not fit onto
-the first available page.  The next is about a large table that had
-to be scaled down slightly to fit on the page.  The last two warnings
-point to two places where a C program text ended inside a comment,
-which in these cases was deliberate.  If you set the document in
-Letter size paper, you will get a somewhat different set of warning
-messages.
+The first two warnings are about footnotes that did not fit onto the
+first available page.  The next is about a large table that had to be
+scaled down slightly to fit on the page.  The last two warnings point
+to two places where a C program text ended inside a comment, which in
+these cases was deliberate.  If you set the document in Letter size
+paper, you will get a somewhat different set of warning messages.
 
 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.it.su.edu.au/jeff/lout/lout-3.31.user.ps.gz".
+stored at "ftp://ftp.it.su.edu.au/jeff/lout/lout-3.32.user.ps.gz".
 
 Jeffrey H. Kingston
-August 2005
+25 October 2006
diff --git a/doc/user/all b/doc/user/all
index 76a8366..37fc0d3 100644
--- a/doc/user/all
+++ b/doc/user/all
@@ -22,10 +22,10 @@ Lout
 Document Formatting System
 }
     @Author { Jeffrey H. Kingston }
-    @Edition { Version 3.31
-August, 2005 }
+    @Edition { Version 3.32
+October, 2006 }
     @Publisher {
-Copyright @CopyRight 1991, 2005 Jeffrey H. Kingston,
+Copyright @CopyRight 1991, 2006 Jeffrey H. Kingston,
 School of Information Technologies,
 The University of Sydney 2006, Australia.  ISBN 0 86758 951 5.
 }
diff --git a/doc/user/bas_conv b/doc/user/bas_conv
index cd971b0..492f306 100644
--- a/doc/user/bas_conv
+++ b/doc/user/bas_conv
@@ -28,7 +28,7 @@ initialspace. @Index { @Code "@InitialSpace" option }
 @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 {
+@ID @OneRow @Code {
 "@SysInclude { doc }"
 "@Document"
 "    @InitialSpace { lout }"
diff --git a/doc/user/bas_par2 b/doc/user/bas_par2
index b836648..2de99e9 100644
--- a/doc/user/bas_par2
+++ b/doc/user/bas_par2
@@ -196,10 +196,9 @@ 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:
+respected.  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"
@@ -232,7 +231,72 @@ The result is
      What winde
 Serves to'advance an honest minde.
 }
-as desired.  To set the entire document in a paragraph breaking style other
+as desired.
+@PP
+When using {@Code lines}, {@Code clines}, and {@Code "rlines @Break"},
+blank lines are respected and ordinarily appear at their full height.
+However, it often looks better to give somewhat
+blanklinescale. @Index { @Code blanklinescale }
+less than this to blank lines.  For this there is the {@Code blanklinescale}
+option to {@Code "@Break"}:
+@ID @OneRow @Code @Verbatim {
+@IndentedDisplay { lines blanklinescale 0.6 } @Break @I {
+Go, and catch a falling star,
+     Get with child a mandrake root,
+Tell me, where all past years are,
+     Or who cleft the Devil's foot,
+Teach me to hear Mermaides singing,
+Or to keep off envies stinging,
+     And finde
+     What winde
+Serves to'advance an honest minde.
+
+If thou be'st born to strange sights,
+     Things invisible to see,
+Ride ten thousand days and nights,
+     Till age snow white hairs on thee,
+Thou, when thou return'st, wilt tell me
+All strange wonders that befell thee,
+     And swear
+     No where
+Lives a woman true, and fair.
+}
+}
+As shown, @Code "blanklinescale" may appear at any point in the
+object to the left of {@Code "@Break"}, followed by a number
+indicating how much to scale the usual height of a blank line by.  The
+object to the left of @Code "@Break" has to be enclosed in braces as
+shown, to ensure that its extent is clear.  The result is
+@IndentedDisplay { lines blanklinescale 0.6 } @Break @I {
+Go, and catch a falling star,
+     Get with child a mandrake root,
+Tell me, where all past years are,
+     Or who cleft the Devil's foot,
+Teach me to hear Mermaides singing,
+Or to keep off envies stinging,
+     And finde
+     What winde
+Serves to'advance an honest minde.
+
+If thou be'st born to strange sights,
+     Things invisible to see,
+Ride ten thousand days and nights,
+     Till age snow white hairs on thee,
+Thou, when thou return'st, wilt tell me
+All strange wonders that befell thee,
+     And swear
+     No where
+Lives a woman true, and fair.
+}
+in which the verses are separated by considerably less than a full
+blank line; instead of a baseline-to-baseline gap of twice the
+interline space, as usual, the gap here is only 1.6 times the
+interline space.  Two blank lines would give 2.2 times the
+interline space, and so on.  There is no unit of measurement
+associated with {@Code "blanklinescale"}, because it is a scale
+factor, not a length.
+@PP
+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
diff --git a/doc/user/bgr_prec b/doc/user/bgr_prec
index 3bd0d57..d26b989 100644
--- a/doc/user/bgr_prec
+++ b/doc/user/bgr_prec
@@ -3,9 +3,13 @@
    @Tag { precise }
 @Begin
 @PP
-This section offers some tips on placing objects precisely where you
-want them.  This isn't a subject with any clear boundaries, so the
-section is mainly a list of examples, covering the use of the
+This section offers some tips on placing objects precisely where you want
+them relative to each other.  If your problem is to place objects precisely
+at some unusual point on the page, you probably need a margin note or the
+@Code "@Place" symbol, for which see Section {@NumberOf marginnotes}.
+@PP
+Precise object placement is not a subject with any clear boundaries, so
+this section is mainly a list of examples, covering the use of the
 @Code {"@OneCol"}, @Code {"@OneRow"}, @Code {"@Wide"}, @Code {"@High"},
 @Code {"@HExpand"}, @Code {"@VExpand"}, @Code {"@HShift"}, @Code {"@VShift"},
 @Code {"@VStrut"}, @Code {"@OverStrike"}, @Code {"@ZeroHeight"},
@@ -186,5 +190,7 @@ measurement).
 Some of the symbols described in this section are Lout primitives, described
 in full detail in the Expert's Guide @Cite { $kingston1995lout.expert };
 and that is also the place to look for more information about precise
-object placement.
+object placement.  In particular, the Lout primitives described there
+for horizontal and vertical concatenation, @Code "/" and {@Code "|"},
+offer possibilities beyond what has been described here.
 @End @Section
diff --git a/doc/user/gra_erro b/doc/user/gra_erro
index 80a30ba..f71a251 100644
--- a/doc/user/gra_erro
+++ b/doc/user/gra_erro
@@ -35,7 +35,7 @@ graphs. @RawIndex { graphs (statistical) }
 graphs.save @SubIndex { @Code save option }
 save. @RawIndex { @Code "save" option }
 save.in.graphs @SubIndex { in graphs }
-@ID @Code @Verbatim {
+@ID @OneRow @Code @Verbatim {
 @Graph
     save { yes }
 ...
diff --git a/doc/user/preface b/doc/user/preface
index a97008b..431dbf8 100644
--- a/doc/user/preface
+++ b/doc/user/preface
@@ -18,7 +18,7 @@ gnu. @Index { GNU Public License }
 primary source is directory
 @ID @Code "ftp://ftp.it.usyd.edu.au/jeff/lout"
 containing a gzipped tar file of the current version
-(currently {@Code "lout-3.31.tar.gz"}), and various other things including
+(currently {@Code "lout-3.32.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/prg_chan b/doc/user/prg_chan
index 35c102f..a561e79 100644
--- a/doc/user/prg_chan
+++ b/doc/user/prg_chan
@@ -25,17 +25,19 @@ file.  Here is part of the @Code "@Use" clause from {@Code cprint}:
    bformat { @Cell { "    #" A } | @Cell { "{" B } | @Cell "}" }
 {
 @Rowa A { "@Use {  @CPSetup" }
-@Rowb A { "pipe" } B {          }
-@Rowb A { "numbered" } B { No         }
-@Rowb A { "style" } B { fixed         }
+@Rowb A { "pipe" }			B {		}
+@Rowb A { "numbered" }			B { No		}
+@Rowb A { "blanknumbered" }		B { Yes		}
+@Rowb A { "style" }			B { fixed	}
 
 @Rowa 
-@Rowb A { "fixedfont" }			B { Courier  }
-@Rowb A { "fixedsize" }			B { -1.0p         }
-@Rowb A { "fixedline" }			B { 1.0vx         }
-@Rowb A { "fixedspace" }		B { lout         }
-@Rowb A { "fixedtabin" }		B { 8		  }
-@Rowb A { "fixedtabout" }		B { 8s		  }
+@Rowb A { "fixedfont" }			B { Courier	}
+@Rowb A { "fixedsize" }			B { -1.0p	}
+@Rowb A { "fixedline" }			B { 1.0vx	}
+@Rowb A { "fixedblanklinescale" }	B { 1.0		}
+@Rowb A { "fixedspace" }		B { lout	}
+@Rowb A { "fixedtabin" }		B { 8		}
+@Rowb A { "fixedtabout" }		B { 8s		}
 
 @Rowa 
 @Rowb A { "fixedidentifiers" }		B { Base  }
@@ -55,10 +57,10 @@ file.  Here is part of the @Code "@Use" clause from {@Code cprint}:
 @Rowb A { "fixedcommentsformat" }	B { "@Body"  }
 @Rowb A { "fixedlinenumbersformat" }	B { "@Body"  }
 
-@Rowa 
-@Rowa A { "..." }
-
-@Rowa 
+#@Rowa 
+#@Rowa A { "..." }
+#
+#@Rowa 
 @Rowa A { "}" }
 }
 The @Code pipe option will be explained in Section {@NumberOf pipes}.  The
@@ -66,17 +68,17 @@ options whose name begins with @Code "fixed" apply only when
 @Code style is {@Code fixed}; there are corresponding options, not
 shown, which apply when @Code style is {@Code varying} and {@Code symbol}.
 @PP
-We can see in this extract that the default value of @Code style is
-{@Code fixed}, and of @Code "numbers" is {@Code No}.  We can also see the
-default font family, font face, font size, line spacing, spacing mode,
-and tab settings when the style is {@Code "fixed"}.  The font family
-name for @Code "fixed" style is {@Code "Courier"}, but for the other
-styles (not shown) it 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.
+This extract shows that the default value of @Code "numbered" is {@Code No},
+of @Code "blanknumbered" is {@Code Yes}, and of @Code style is {@Code fixed}.
+It also shows the default font family, font face, font size,
+line spacing, blank line scale factor, spacing mode, and tab settings when
+the style is {@Code "fixed"}.  The font family name for @Code "fixed" style
+is {@Code "Courier"}, but for the other styles (not shown) it 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
-The options from @Code "fixedidentifiers" to @Code "fixedlinenumbers" allow
-you to set the font face to use for each of these parts of your
+The options from @Code "fixedidentifiers" to @Code "fixedlinenumbers"
+allow you to set the font face to use for each of these parts of your
 program.  People who want fixed-width fonts do not usually want very
 exciting font faces either, so the default values above are all
 {@Code "Base"}, but for the {@Code varying} and {@Code symbol} styles,
@@ -127,7 +129,11 @@ import @CPSetup
 macro @NCP { @CP numbered { Yes } }
 }
 (or the equivalent for your language) in your @Code mydefs file, so that
-you can type @Code "@NCP" instead of {@Code "@CP numbered { Yes }"}.
+you can type @Code "@NCP" instead of {@Code "@CP numbered { Yes }"}.  On
+the other hand, it is quite safe to change @Code "blanknumbered" to
+{@Code "No"} or {@Code "NoPrint"} in the setup file; this will cause
+line numbers to be omitted from blank lines whenever there happen to
+be line numbers.
 @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
diff --git a/doc/user/prg_lone b/doc/user/prg_lone
index 950fa05..06bc497 100644
--- a/doc/user/prg_lone
+++ b/doc/user/prg_lone
@@ -34,10 +34,19 @@ 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.
 }
+@TI { {@Code -b}{@I number} } {
+Select a blank line scale factor, usually a number between 0.5 and 1.0,
+indicating the factor by which the usual amount of white space inserted
+to represent a blank line is to be reduced.  The default is @Code { 1.0 },
+meaning no reduction.
+}
 @TI { {@Code -L}{@I number} } {
 Add line numbers to the program print, starting with {@I number}, or
 1 if {@I number} is omitted.
 }
+@TI { {@Code -N} } {
+Do not print line numbers at the start of blank lines.
+}
 @TI { {@Code -S}{@I file} } {
 Use @I file as the setup file for printing your language.  This allows
 you to change all the options mentioned in subsequent sections, rather
diff --git a/doc/user/prg_opti b/doc/user/prg_opti
index 292f26a..6ae4e05 100644
--- a/doc/user/prg_opti
+++ b/doc/user/prg_opti
@@ -80,11 +80,14 @@ which allow a finer control over the style.  Here they all are, with their
 default values:
 @ID @OneRow @Code @Verbatim {
 @CP         [ or @Eiffel, @Blue, etc. ]
-    style { fixed }
+    pipe {}
     numbered { No }
+    blanknumbered { Yes }
+    style { fixed }
     font { Courier }
     size { -1.0p }
     line { 1.0vx }
+    blanklinescale { 1.0 }
     space { lout }
     tabin { 8 }
     tabout { 8s }
@@ -98,15 +101,32 @@ default values:
     ...
 }
 }
-We are already familiar with {@Code "style"}.  After that comes
-{@Code "numbered"}, whose value may be {@Code "No"} (the default),
-{@Code "Yes"}, or a number, and which determines whether or not
+Apart from {@Code "pipe"}, {@Code "numbered"} and {@Code "blanknumbered"},
+the default values shown are for @Code "style { fixed }" only; the other
+styles have other defaults (Section {@NumberOf cpsetup}).  For the
+{@Code "pipe"} option, see Section {@NumberOf pipes}.
+@PP
+The value of {@Code "numbered"} may be {@Code "No"} (the default),
+{@Code "Yes"}, or a number, and it determines whether or not
 programs. @RawIndex { programs }
 programs.numbered @SubIndex { @Code "numbered" option }
 numbered.programs @Index { @Code "numbered" option (programs) }
-line numbers are to be added and if so the value of the first
-one.  Next we have
-{@Code "font"}, which determines the font family to use, {@Code "size"},
+line numbers are to be added, and if so the value of the first one.
+If @Code "numbered" is {@Code "Yes"}, then the {@Code "blanknumbered"}
+option becomes relevant, and it determines whether blank lines are to
+programs. @RawIndex { programs }
+programs.blanknumbered @SubIndex { @Code "blanknumbered" option }
+blanknumbered.programs @Index { @Code "blanknumbered" option (programs) }
+receive line numbers or not.  It has three acceptable values:  {@Code "Yes"},
+the default value, meaning that blank lines are printed with line numbers,
+just like other lines; {@Code No}, meaning that blank lines are not
+assigned line numbers; and {@Code NoPrint}, meaning that blank lines
+are assigned line numbers but these numbers are not printed, so that
+the line numbers printed before and after a single blank line will
+differ by 2.
+@PP
+The {@Code "style"} option is already familiar.  Next comes {@Code "font"},
+which determines the font family to use, {@Code "size"},
 programs. @RawIndex { programs }
 programs.font @SubIndex { @Code "font" option }
 font.option. @RawIndex { @Code "font" option }
@@ -117,13 +137,18 @@ size.programs @Index { @Code "size" option (programs) }
 programs. @RawIndex { programs }
 programs.line @SubIndex { @Code "line" option }
 line.programs @Index { @Code "line" option (programs) }
-the font size to use, {@Code "line"}, the inter-line spacing, and
-{@Code "space"}, the spacing mode (as for the @Code "@Space" symbol
-of Section {@NumberOf white}).
+the font size to use, {@Code "line"}, the inter-line spacing,
+{@Code "blanklinescale"}, a scale factor by which the usual
+programs. @RawIndex { programs }
+programs.blanklinescale @SubIndex { @Code "blanklinescale" option }
+blanklinescale.programs @Index { @Code "blanklinescale" option (programs) }
+height of blank lines without printed line numbers is reduced (as in the
+option to the @Code "@Break" symbol of the same name), and {@Code "space"}, the
+spacing mode (as for the @Code "@Space" symbol of Section {@NumberOf white}).
 programs. @RawIndex { programs }
 programs.space @SubIndex { @Code "space" option }
 space.programs @Index { @Code "space" option (programs) }
-The default value for @Code "size" asks for one point smaller than in the
+The default value of @Code "size" asks for 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.
 @PP
@@ -150,7 +175,5 @@ programs.comments @SubIndex { @Code "comments" option }
 comments.programs @Index { @Code "comments" option (programs) }
 numbers, strings, and comments.  {@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}).
+options may all be set to different faces if desired.
 @End @Section
diff --git a/doc/user/prg_pipe b/doc/user/prg_pipe
index 3867a28..ea45fbd 100644
--- a/doc/user/prg_pipe
+++ b/doc/user/prg_pipe
@@ -60,4 +60,11 @@ pipe is
 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.
+@PP
+When using @Code "pipe" it is also possible to omit {@Code "@Include"}
+and use the pipe to get the file as well as select from it:
+@ID @OneRow @Code {
+"@Eiffel pipe { \"cat /usr/staff/jeff/Eiffel/hash.e | sed -n /^.insert/,/^..end/p | cut -c2-\" } {}"
+}
+This pipes nothing into the {@Code cat} command, which does no harm.
 @End @Section
diff --git a/doc/user/str_list b/doc/user/str_list
index 7888554..4f65e68 100644
--- a/doc/user/str_list
+++ b/doc/user/str_list
@@ -3,20 +3,20 @@
    @Tag { lists }
 @Begin
 @PP
-The @Code "@List" symbol introduces a sequence of items to be
+The @Code "@IndentedList" symbol introduces a sequence of items to be
+indentedlist. @Index @Code "@IndentedList"
+il. @Index @Code "@IL"
 lists. @Index { lists }
-list. @Index @Code "@List"
-l. @Index @Code "@L"
 made into a displayed list:
 @ID @OneRow @Code @Verbatim {
 preceding text
-@List
+@IndentedList
 @ListItem @I Emma
 @ListItem @I { Mansfield Park }
 @EndList
 following text
 }
-After the initial @Code "@List" symbol, each item is introduced by
+After the initial @Code "@IndentedList" 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
@@ -25,7 +25,7 @@ el. @Index @Code "@EL"
 result here is
 @ID @OneRow {
 preceding text
-@List
+@IndentedList
 @ListItem @I Emma
 @ListItem @I { Mansfield Park }
 @EndList
@@ -34,12 +34,10 @@ 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"},
+As the example shows, the @Code "@IndentedList" symbol causes the items to be
+indented.  Also available are {@Code "@LeftList"},
 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"
@@ -309,6 +307,42 @@ behind the scenes prevent this.  @Code "@ParagraphItem" has a
 @Code "style" option that works much like the @Code "style" option
 of {@Code "@List"} described just below.
 @PP
+Another useful variation is the @I { multi-column list }, in
+which the items are spread over several columns within the
+current column.  Any kind of list may be converted into a
+multi-column list.  For example, here is how to get a
+multi-column bullet list:
+@ID @OneRow @Code @Verbatim {
+@BulletList
+    colnum { 3 }
+    colgap { 1.0c }
+    colheight { 5.0c }
+}
+followed by the list items and @Code "@EndList" as usual.  This
+list will appear spread over three columns, with the items placed
+down the first column, then down the second, and so on.  The columns
+will have equal width, as wide as possible given that they are
+separated from each other by the gap given by {@Code "colgap"}.
+Ideally, one would want the columns to have equal height, just
+enough to hold all the items; but since Lout is not clever enough
+to do this, you must specify a fixed height for each column,
+using the @Code "colheight" option; and this height must be small
+enough to allow the entire list to fit onto one page, since it is
+effectively an unbreakable display.
+@PP
+The value of @Code "colnum" must be either 1, 2, 3, 4, or 5.  If
+it is 1 (the default value), @Code "colgap" and @Code "colheight"
+are not used and the result is an ordinary list.  The value of
+@Code "colgap" and @Code "colheight" may be any width; the default
+values are those shown above.  All the features available for
+ordinary lists and list items work in the usual way with
+multi-column lists:  one may keep a list item in one column by
+enclosing it in {@Code "@OneRow"}, cause a break to the next
+column using {@Code "@ListNewPage"}, and so on.  If there is not
+enough space in the columns to hold all the items (a real possibility
+since their height is fixed), any excess is dropped, sometimes with
+and sometimes without a confusing error message.
+@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"},
@@ -320,16 +354,24 @@ 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
+list. @Index @Code "@List"
+l. @Index @Code "@L"
 are all the options, together with their default values:
 @ID @OneRow @Code @Verbatim {
 @List
     type { num }
     style { num }
     labelwidth { 2f }
+    labelright { No }
+    labelrightgap { 2s }
     indent { 0c }
     rightindent { 0c }
     gap { 1v }
     start { 1 }
+    break { }
+    colnum { 1 }
+    colgap { 1.0c }
+    colheight { 5.0c }
 }
 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"
@@ -360,9 +402,16 @@ 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
+from {@Code "@TaggedList"}.  If @Code "labelright" is {@Code "Yes"}, it
+means that the label is to appear right-justified in this width, apart from
+a width @Code "labelrightgap" to the right of it to separate it from the
+content of the list item.  The default value of {@Code "labelrightgap"},
+{@Code "2s"}, is the width of two spaces.  If @Code "labelright" is
+{@Code No}, @Code "labelrightgap" is not used.
+@PP
+The @Code "indent" and @Code "rightindent"
+options determine the space left blank at the left and right margins.
+The value given to these 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"
@@ -391,6 +440,22 @@ item.  It must be decimal:
 looks strange, but it is the correct way to number the first
 item (xxv).
 @PP
+The @Code "break" option defines a break style (suitable for the
+@Code "@Break" symbol) which is to be applied to each item.  If
+you wanted each item in a ragged style, for example, you could
+just write
+@ID @OneRow @Code @Verbatim {
+@NumberedList
+    break { ragged }
+}
+rather than laboriously enclosing each item in @Code "ragged @Break".
+@PP
+The last three options, {@Code "colnum"}, {@Code "colgap"}, and
+{@Code "colheight"} work together to produce multi-column lists,
+as explained earlier.  When the default value of @Code "colnum"
+is used (i.e. 1), {@Code "colgap"} and {@Code "colheight"} are
+ignored and the result is an ordinary list.
+@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"}:
@@ -431,12 +496,14 @@ caused by radioactive materials stored adjacent to the facility.
 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
-to every list in the document unless overridden by an option,
-just like the usual default values.  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.
+{@Code "labelright"}, {@Code "labelrightgap"}, {@Code "indent"},
+{@Code "rightindent"}, {@Code "gap"}, and {@Code "break"} options, by
+setting options called {@Code "@ListLabelWidth"}, {@Code "@ListLabelRight"},
+{@Code "@ListLabelRightGap"}, {@Code "@ListIndent"},
+{@Code "@ListRightIndent"}, {@Code "@ListGap"}, and
+{@Code "@ListBreak"} options in the setup file (Section {@NumberOf setup}).
+These default values will then apply to every list in the document unless
+overridden by an option, just like the usual default values.  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/tbl_cell b/doc/user/tbl_cell
index e68fd0b..9d98023 100644
--- a/doc/user/tbl_cell
+++ b/doc/user/tbl_cell
@@ -128,6 +128,13 @@ Note the difference between a coloured background, obtained with
 {@Code "paint"}, and a coloured entry, obtained using the @Code "@Colour"
 symbol.
 @PP
+When an entry in a table consists of several paragraphs, it will usually
+be best to enclose it in {@Code "@OneRow"}, since otherwise @Code "@Tbl"
+is likely to take each paragraph as a separate row, leading to incorrect
+vertical spacing.  A convenient way to do this is
+@ID @Code "aformat { @Cell @OneRow A | @Cell @OneRow B }"
+and so on.
+@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"
diff --git a/doc/user/typ_orga b/doc/user/typ_orga
index 1e9aa36..ce49851 100644
--- a/doc/user/typ_orga
+++ b/doc/user/typ_orga
@@ -91,4 +91,18 @@ 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.
+@PP
+When some part of your document has to be repeated, one way to avoid
+entering it twice is to place that part in a separate file and use
+@Code "@Include" in two places to include it twice.  This works, but
+there are two caveats.  First, it may be better to use a definition
+(Section {@NumberOf definitions}), since that gives you an object
+with a name, which you can use with confidence anywhere at all.
+Second, Lout treats @Code "@Include" in a peculiar way when it
+appears in the setup part of a document (in definitions, databases,
+and the @Code "@Use" clauses that appear within setup files):  it
+reads the file as usual the first time, and silently skips it the
+other times.  This is done to simplify the handling of files of
+definitions that depend on other files of definitions, as described
+in the Expert's Guide @Cite { $kingston1995lout.expert }.
 @End @Section
diff --git a/doc/user/typ_over b/doc/user/typ_over
index cf3a189..aced99c 100644
--- a/doc/user/typ_over
+++ b/doc/user/typ_over
@@ -212,23 +212,27 @@ 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 }"
-"}"
+@ID @OneRow @Code @Verbatim {
+@Use { @OverheadSetup
+  # @DateLine { No }
+  # @FirstOverheadNumber { 1 }
+  # @FirstLectureNumber { 1 }
+  # @ContentsWord { contents }
+  # @LectureNumbers { Arabic }
+  # @OverheadNumbers { Arabic }
+  # @TitlePageFont { Helvetica Base }
+  # @AboveTitleGap { 0.5i }
+  # @AboveAuthorGap { 1.0i }
+  # @AboveInstitutionGap { 0.5i }
+  # @AboveDateLineGap { 0.5i }
+  # @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
@@ -238,9 +242,11 @@ 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.
+options for setting the font of the overall title page, the gap
+above the title, author, institution, and dateline that appear on that
+page; then options controlling the appearance of the headings at the
+start of each lecture and overhead, 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" 
diff --git a/doc/user/vprg b/doc/user/vprg
index 5922150..81c0abe 100644
--- a/doc/user/vprg
+++ b/doc/user/vprg
@@ -1,12 +1,2 @@
-gvim prg
-gvim prg_lone
-gvim prg_embe
-gvim prg_opti
-gvim prg_chan
-gvim prg_tabs
-gvim prg_form
-gvim prg_comm
-gvim prg_prog
-gvim prg_pipe
-gvim prg_erro
-gvim prg_perl
+gvt prg prg_lone prg_embe prg_opti prg_chan prg_tabs prg_form \
+  prg_comm prg_prog prg_pipe prg_erro prg_perl