Lout 3.19 tag.3.19

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

17 files changed, 261 insertions, 134 deletions

diff --git a/doc/user/README b/doc/user/README
index 2363b0c..0fc5704 100644
--- a/doc/user/README
+++ b/doc/user/README
@@ -6,7 +6,7 @@ type the command
 
 	lout all > op
 
-in this directory.  This must be done five times to completely
+in this directory.  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.
@@ -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.18.user.ps.gz".
+stored at "ftp://ftp.cs.su.oz.au/jeff/lout/lout-3.19.user.ps.gz".
 
 Jeffrey H. Kingston
-23 February 2000
+9 March 2000
diff --git a/doc/user/all b/doc/user/all
index ef7fcdf..a4bb049 100644
--- a/doc/user/all
+++ b/doc/user/all
@@ -20,8 +20,8 @@ Lout
 Document Formatting System
 }
     @Author { Jeffrey H. Kingston }
-    @Edition { Version 3.18
-February, 2000 }
+    @Edition { Version 3.19
+March, 2000 }
     @Publisher {
 Copyright @CopyRight 1991, 2000 Jeffrey H. Kingston,
 Basser Department of Computer Science,
diff --git a/doc/user/equ_summ b/doc/user/equ_summ
index b1e6fbc..9f9bf66 100644
--- a/doc/user/equ_summ
+++ b/doc/user/equ_summ
@@ -516,6 +516,8 @@ ragged @Break {
 "ddots"		@Dbl @Eq {  ddots		}
 "del"		@Dbl @Eq {  del			}
 "grad"		@Dbl @Eq {  grad		}
+"triangleup"	@Dbl @Eq {  triangleup		}
+"triangledown"	@Dbl @Eq {  triangledown	}
 "..."		@Dbl @Eq {  ...			}
 ",...,"		@Dbl @Eq {  ,...,		}
 "half"		@Dbl @Eq {  half		}
diff --git a/doc/user/preface b/doc/user/preface
index 9b3e964..3634a89 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.cs.usyd.edu.au/jeff/lout"
 in which may be found a gzipped tar file containing the main distribution
-(currently {@Code "lout-3.18.tar.gz"}), and various other things including
+(currently {@Code "lout-3.19.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/str_indx b/doc/user/str_indx
index c9ea2de..3c15c09 100644
--- a/doc/user/str_indx
+++ b/doc/user/str_indx
@@ -161,20 +161,13 @@ trial of, 205--211
 trial of, 242
 trial of, 395
 }
-must be merged, what does Lout do?  It takes the second entry, discards
-any initial part that is the same as the first entry ({@Code "trial of,"}
-in this case), and, if anything remains, it adds a comma, a space, and
-the remainder to the first entry, producing
-@ID { trial of, 205--211, 242 }
-in this case.  This process is repeated on this and the third entry,
-producing
-@ID { trial of, 205--211, 242, 395 }
-in this case, and so on.  The entries are merged in the order in which
-their points of origin appear in the final printed document.
+must be merged, what does Lout do?  Without being too formal, it
+finds the shortest larger entry that contains everything in the
+given entries, more or less, preserving the order in which
+the entries' points of origin appear in the final printed document.
 @PP
-If nothing remains after discarding the common initial part, nothing is
-added to the growing merged entry; in effect, the entry that could
-contribute nothing new is deleted.  With this in mind, let us return to
+If the entries are not different at all, then the result will be
+the same as each of them.  With this in mind, let us return to
 our initial, ambitious example:
 @ID @OneRow lines @Break {
 Galileo Galilei
@@ -260,14 +253,17 @@ The remainder of this section describes how to change the appearance of
 the index by setting options in the setup file.  For setup files and
 their options in general, consult Section {@NumberOf setup}.
 @PP
-There are five setup file options for the index.  Here they are with
+There are eight setup file options for the index.  Here they are with
 their default values:
-@ID @OneRow @Code {
-"@MakeIndex { No }"
-"@IndexFont { }"
-"@IndexBreak { oragged 1.2fx }"
-"@IndexColumnNumber { 2 }"
-"@IndexColumnGap { 1.00c }"
+@ID @OneRow @Code @Verbatim {
+@MakeIndex { No }
+@IndexFont { }
+@IndexBreak { oragged 1.2fx }
+@IndexColumnNumber { 2 }
+@IndexColumnGap { 1.00c }
+@IndexCtd { Yes }
+@IndexCtdWord { continued }
+@IndexCtdFormat { @Body @I (@CtdWord) }
 }
 The @Code "@MakeIndex" option, which may be @Code Yes or {@Code No},
 makeindex. @Index @Code "@MakeIndex"
@@ -291,6 +287,31 @@ number of index columns per page, and the gap between them, and are
 exactly analogous to the @Code "@ColumnNumber" and @Code "@ColumnGap"
 options described in Section {@NumberOf columns}.
 @PP
+The last three options work together to control the appearance of
+running headers
+@FootNote {
+Index running headers are new in Version 3.19 of Lout.
+}
+in the index.  If an @Code "@Index" entry has @Code "@SubIndex" entries
+that run over to the next column, Lout will print an unobtrusive running
+header at the top of that column, something like this in English:
+@ID { procrastination @I (ctd.) }
+It will print two running headers if a @Code "@SubIndex" entry has
+@Code "@SubSubIndex" entries that run over, one for the main entry and an
+indented one for the sub-entry.  You can turn off these running headers by
+setting @Code "@IndexCtd" to {@Code No}.  A particular word is associated
+with index running headers; by default it is @Code "ctd." in English and
+its equivalent in other languages.  This is what the default value,
+{@Code "continued"}, of the @Code "@IndexCtdWord" option gives you; if you
+want some other word, change that option to the word you want.  Finally,
+you can control the format of the running headers using
+{@Code "@IndexCtdFormat"}.  Within this option, the symbol @Code "@Body"
+stands for the value of the index entry that is running over (minus any
+page numbers), and @Code "@CtdWord" stands for the word produced by the
+@Code "@IndexCtdWord" option.  The default value of {@Code "@IndexCtdFormat"},
+shown above, yields the index entry followed by @Code "@IndexCtdWord" in
+italics and parentheses.
+@PP
 Lout offers the possibility of having up to three independent indexes
 (useful for glossaries, author indexes, etc.).  The other two are called
 index A and index B, and they precede the main index in the
diff --git a/doc/user/tbl b/doc/user/tbl
index 5ed15e1..545e867 100644
--- a/doc/user/tbl
+++ b/doc/user/tbl
@@ -9,6 +9,7 @@ tables. @Index { tables }
    aindent { ctr }
    arulebelow { double }
    aformat { @StartHSpan @Cell @B X | | @HSpan }
+   bindent { align }
    bformat { @Cell rr { no } @I A | @Cell rl { no } B | @Cell C }
    rule { yes }
 {
@@ -39,14 +40,14 @@ Section {@NumberOf tbl_alig} for the details.
 @Include { tbl_intr } # introduction
 @Include { tbl_cell } # basic cell formatting: font, break, width, paint
 @Include { tbl_rows } # row formats and the @Row symbol
+@Include { tbl_rule } # rules
 @Include { tbl_marg } # margins
 @Include { tbl_widt } # width and height
 @Include { tbl_inde } # indenting and struts
-@Include { tbl_rule } # rules
-@Include { tbl_span } # spanning columns and rows
-@Include { tbl_mult } # multi-page tables
 @Include { tbl_alig } # aligned columns and headings over them
+@Include { tbl_span } # spanning columns and rows
 @Include { tbl_mark } # @MarkRow
+@Include { tbl_mult } # multi-page tables
 @Include { tbl_plai } # plain text tables
 @Include { tbl_setu } # setup file options
 @Include { tbl_summ } # summary
diff --git a/doc/user/tbl_alig b/doc/user/tbl_alig
index 0032e86..69e5588 100644
--- a/doc/user/tbl_alig
+++ b/doc/user/tbl_alig
@@ -28,21 +28,19 @@ each entry:
 @Rowa A { 5772^ }
 }
 }
-The equals signs of equations can be aligned in the same way (see the
-example at the start of this chapter).
+The equals signs of equations can be aligned in the same way.
 @PP
 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.
+we follow the rule, the @I heading gets aligned, which is wrong.  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:
+cell (Section {@NumberOf tbl_span}) with centring, like this:
 @FootNote { Lout does not currently accept single-column tables
 with {@Code "@StartHSpan"}, so we've had to add
 an empty second column. }
@@ -50,22 +48,22 @@ an empty second column. }
 @Tbl
     marginvertical { 0.5vx }
     aformat { @StartHSpan @Cell indent { ctr } @B A | }
-    bformat { @Cell A | }
+    bformat { @Cell indent { align } A | }
 {
-@Rowa A { Heading }
+@Rowa A { Head }
 @Rowb A { 5^.46 }
 @Rowb A { 3^.4159 }
 @Rowb A { 5772^ }
 }
 }
-The spanning quarantines the centred cell from the aligned cells,
-permitting @Code "indent { ctr }" to work:
+The spanning quarantines the centred cell, permitting
+@Code "indent { ctr }" to work:
 @CD @OneRow @Tbl
     marginvertical { 0.5vx }
     aformat { @StartHSpan @Cell indent { ctr } @B A | }
-    bformat { @Cell A | }
+    bformat { @Cell indent { align } A | }
 {
-@Rowa A { V } marginabove { 0i }
+@Rowa A { Head } marginabove { 0i }
 @Rowb A { 5^.46 }
 @Rowb A { 3^.4159 }
 @Rowb A { 5772^ } marginbelow { 0i }
@@ -74,7 +72,7 @@ But if the heading cell is wider than the aligned cells, you get this:
 @CD @OneRow @Tbl
     marginvertical { 0.5vx }
     aformat { @StartHSpan @Cell indent { ctr } @B A | }
-    bformat { @Cell A | }
+    bformat { @Cell indent { align } A | }
 {
 @Rowa A { A Wider Heading } marginabove { 0i }
 @Rowb A { 5^.46 }
@@ -87,17 +85,19 @@ respect to a heading.  In these cases you could forget about
 @Code "@StartHSpan" and treat the heading as an aligned entry,
 either by placing a @Code "^" within it or by using
 @ID @Code "@Cell 0.5w @HShift A"
-which places the alignment point in the centre of the entry.
-#@CD @OneRow @Tbl
-#    marginvertical { 0.5vx }
-#    aformat { @Cell 0.5w @HShift @B A }
-#    bformat { @Cell A }
-#{
-#@Rowa A { A Wider Heading } marginabove { 0i }
-#@Rowb A { 5^.46 }
-#@Rowb A { 3^.4159 }
-#@Rowb A { 5772^ } marginbelow { 0i }
-#}
-You can move the alignment point about by changing the 0.5.  Of course,
-all this is a poor substitute for the real thing.
+which places the alignment point in the centre of the entry:
+@CD @OneRow @Tbl
+    indent { align }
+    marginvertical { 0.5vx }
+    aformat { @Cell 0.5w @HShift @B A }
+    bformat { @Cell A }
+{
+@Rowa A { A Wider Heading } marginabove { 0i }
+@Rowb A { 5^.46 }
+@Rowb A { 3^.4159 }
+@Rowb A { 5772^ } marginbelow { 0i }
+}
+You can move the alignment point about by changing the 0.5 to something
+smaller or larger.  Of course, all this is a poor substitute for the
+real thing.
 @End @Section
diff --git a/doc/user/tbl_inde b/doc/user/tbl_inde
index 22f89cc..62080c0 100644
--- a/doc/user/tbl_inde
+++ b/doc/user/tbl_inde
@@ -7,20 +7,21 @@ By default, entries appear at the left within cells, not counting the
 cell margin.  The @Code indent option causes entries to be indented
 horizontally.  For example,
 @ID @OneRow @Code "@Cell indent { ctr }"
-horizontally centres the entry within the cell.  The other possible values
+horizontally centres the entry within the cell.  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"} (the default value), {@Code "right"},
+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"}, @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"} (the default), 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.  Looking at
 @CD @Tbl
+    mv { 0i }
     aformat { @Cell A | @Cell B | @Cell C }
 {
 @Rowa
@@ -39,10 +40,8 @@ which is the result of
     C { title }
 }
 }
-we see that the words are aligned correctly despite the absence of
-ascenders from the first two words, and of descenders from the first
-and last; and this despite the fact that these words are vertically
-placed at the top of the cell.  This is because by default
+we see that the words are aligned correctly despite these
+worries.  This is because by default
 @Code "@Tbl" adds a @I { vertical strut } to each entry:  an invisible
 object of zero width and height {@Code "1f"}, which covers for any absent
 ascenders and descenders.  The option
diff --git a/doc/user/tbl_intr b/doc/user/tbl_intr
index a46da18..51524cb 100644
--- a/doc/user/tbl_intr
+++ b/doc/user/tbl_intr
@@ -50,23 +50,23 @@ tbl. @Index @Code "@Tbl"
     C { Homer }
 }
 is produced by the following input:
-@ID @OneRow @Code {
-"@Tbl"
-"    aformat { @Cell A  |  @Cell B  |  @Cell C }"
-"{"
-"@Rowa"
-"    A { Austen }"
-"    B { Chaucer }"
-"    C { Donne }"
-"@Rowa"
-"    A { Balzac }"
-"    B { Darwin }"
-"    C { Goethe }"
-"@Rowa"
-"    A { Byron }"
-"    B { Dickens }"
-"    C { Homer }"
-"}"
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    aformat { @Cell A  |  @Cell B  |  @Cell C }
+{
+@Rowa
+    A { Austen }
+    B { Chaucer }
+    C { Donne }
+@Rowa
+    A { Balzac }
+    B { Darwin }
+    C { Goethe }
+@Rowa
+    A { Byron }
+    B { Dickens }
+    C { Homer }
+}
 }
 Immediately after the @Code "@Tbl" symbol, which introduces the table,
 comes a @I { format option }, {@Code "aformat"}, describing the format of
diff --git a/doc/user/tbl_marg b/doc/user/tbl_marg
index 89e63cd..ddbab55 100644
--- a/doc/user/tbl_marg
+++ b/doc/user/tbl_marg
@@ -61,7 +61,7 @@ We've used abbreviated versions of the options' names:  @Code "ml" for
 has such an abbreviated name, made from the first letters of the parts of
 its full name (Section {@NumberOf tbl_summ} lists all these names).  The
 result is
-@CD @Tbl
+@DP @RCD @Tbl
     paint { lightgrey }
     aformat { @Cell ml { 0i } A  |  @Cell B  |  @Cell mr { 0i } C }
 {
@@ -70,5 +70,5 @@ result is
     B { Column B }
     C { Column C }
 }
-with the painting showing the reduced margins.
+# with the painting showing the reduced margins.
 @End @Section
diff --git a/doc/user/tbl_mark b/doc/user/tbl_mark
index fcd4768..51d71e7 100644
--- a/doc/user/tbl_mark
+++ b/doc/user/tbl_mark
@@ -9,21 +9,21 @@ and right becomes an issue.  Examples are hard to find, but let's say
 that we need to construct a symbol
 @ID @AmberLight
 and include it in running text.  The obvious first attempt at a table
-with three rows produces
-#@ID @OneRow @Code @Verbatim {
-#@Tbl
-#   aformat { @Cell A }
-#   margin { 0i }
-#   strut { no }
-#{
-#@Rowa A { @OpenCircle }
-#@Rowa A { @ClosedCircle }
-#@Rowa A { @OpenCircle }
-#}
-#}
-#where @Code "@OpenCircle" and @Code "@ClosedCircle" produce open and
-#closed circles (they may be defined using the @Code "@Diag" package);
-#but this produces
+with three rows is
+@ID @OneRow @Code @Verbatim {
+@Tbl
+   aformat { @Cell A }
+   margin { 0i }
+   strut { no }
+{
+@Rowa A { @OpenCircle }
+@Rowa A { @ClosedCircle }
+@Rowa A { @OpenCircle }
+}
+}
+where @Code "@OpenCircle" and @Code "@ClosedCircle" produce open and
+closed circles (they may be defined using the @Code "@Diag" package);
+but this produces
 @Tbl
    aformat { @Cell A }
    margin { 0i }
@@ -47,7 +47,8 @@ def @AmberLight
          aformat { @Cell indentvertical { align } A }
          margin { 0i }
          strut { no }
-         paint { no }  rule { no }
+         paint { no }
+         rule { no }
      {
          @Rowa A { @OpenCircle }
          @MarkRowa A { @ClosedCircle }
diff --git a/doc/user/tbl_mult b/doc/user/tbl_mult
index 84ce363..3b83b8b 100644
--- a/doc/user/tbl_mult
+++ b/doc/user/tbl_mult
@@ -34,10 +34,95 @@ rightmost column to the full page width; one way to prevent this is to add
 a @Code "|" after the last cell within each {@Code format} option, creating
 an empty extra column.
 @PP
-The simplest way to get rules right in multi-page tables is to set
-@Code "rulehorizontal" to {@Code yes}.  This places a rule above every
-row including the first on each page, and a rule below every row including
-the last on each page.
+One practical problem with multi-page tables is that of getting a
+heading over every page after the first.  This is easy if you know where
+the page breaks are going to fall (if you are using {@Code "@NP"}, for
+example), but you usually don't.  To solve this problem, @Code {"@Tbl"}
+offers the @Code "@HeaderRowa" ... @Code "@HeaderRowh" and
+@Code "@EndHeaderRow" symbols.  For example, the multi-page table in
+Section {@NumberOf tbl_summ} is arranged like this:
+@ID @OneRow @Code @Verbatim {
+@Tbl
+    ...
+{
+@Rowd
+    A { Option names }
+    B { Default in PS, PDF }
+    C { Default in plain text }
+    D { Allowed values }
+    rulebelow { yes }
+@HeaderRowd
+    A { Option names (ctd.) }
+    B { Default in PS, PDF }
+    C { Default in plain text }
+    D { Allowed values }
+    rulebelow { yes }
+@Rowa
+    A { paint  p }
+    B { nopaint }
+    D { any colour from Section {@NumberOf colour} }
+...
+@Rowa
+    A { ruleplainchar  rpc }
+    C { . }
+    D { any simple word e.g. @Code + }
+    rulebelow { yes }
+@EndHeaderRow
+}
+}
+where we have omitted a lot of irrelevant things.  @Code "@HeaderRowd"
+is exactly like {@Code "@Rowd"}, except that the row is not printed at
+all where it occurs; instead, it is saved up and used as a running header
+on subsequent pages.
+@PP
+The @Code "@EndHeaderRow" symbol goes where a @Code "@Row" symbol might
+go.  Notice that it does not end with a letter between {@Code a} and
+{@Code h}, and that it has no options.  Its meaning is that the most
+recent running header is not wanted on pages after this point:  in other
+words, it cancels the previous @Code "@HeaderRowa" ... @Code "@HeaderRowh"
+symbol.  Forgetting @Code "@EndHeaderRow" is disastrous, because every page
+from this point on will then have the running header, even though the table
+ended long before.
+@PP
+There may be any number of header rows saved up at any moment, all to be
+printed at the top of subsequent pages.  Having @Code "@EndHeaderRow"
+allows them to be `nested.'  For example, just schematically,
+@ID @OneRow @Code @Verbatim {
+@HeaderRowa ...
+@HeaderRowb ...
+@EndHeaderRow
+@HeaderRowb ...
+@EndHeaderRow
+@EndHeaderRow
+}
+could be used in a table to say that the entire table has the first
+header row; and that the first part also has the second header row,
+but the second part of the table has a different second header row,
+but still the same first header row.
+@PP
+These header symbols have some peculiarities not likely to trouble the
+ordinary user, but worth pointing out.  Each copy of a running header
+will be identical to every other copy, so any attempt to use cross
+references to add (say) page numbers to the running header is doomed to
+disappointment.  (If you want to change the header, use
+@Code "@EndHeaderRow" followed by a new header row.)  Basser Lout
+copies running header rows into the table after each page break,
+with no check on whether the next page has enough space to
+accommodate them, so if your running headers are so high that
+there is no room for ordinary rows on the page after they are
+inserted, then the document will never end.  Finally, header
+rows are taken account of by Lout when deciding column widths,
+whether they are actually printed or not.
+@PP
+Another practical problem in multi-page tables is getting the rules
+right.  The simplest way to do this is to set @Code "rulehorizontal"
+to {@Code yes}.  This places a rule above every row including the
+first on each page, and a rule below every row including the last
+on each page.  There is nothing equivalent to running headers
+at the bottom of the page -- nothing that would allow you to
+insert a rule after the last line of each page, but not
+elsewhere.  (However, if you are using the @Code "@Table"
+symbol, its @Code "@Enclose" option can be used to do this.)
 @PP
 To prevent page breaks within a table, precede the @Code "@Tbl"
 symbol by {@Code "@OneRow"}:
@@ -46,7 +131,7 @@ symbol by {@Code "@OneRow"}:
 object into a single, unbreakable row.  Make sure your table is
 small enough to fit on one page when you do this, otherwise an error
 message will be printed and it will be scaled to fit.  Of course, we
-have just said that display symbols like @Code "@CD" do this anyway,
+said earlier that display symbols like @Code "@CD" do this anyway,
 but that might change some day.
 @PP
 To prevent a page break between two particular rows, but not in
diff --git a/doc/user/tbl_rows b/doc/user/tbl_rows
index 7d26b75..d7950b1 100644
--- a/doc/user/tbl_rows
+++ b/doc/user/tbl_rows
@@ -5,11 +5,11 @@
 @PP
 We've seen that the @Code aformat option of @Code "@Tbl" determines the
 format of the rows introduced by the @Code "@Rowa" symbol.  There are
-eight of these row format options: {@Code aformat},
+eight row format options: {@Code aformat},
 row.formats @Index { row formats in tables }
 {@Code bformat}, and so on up to {@Code hformat}, and for each there
 is a corresponding {@Code "@Row"} symbol:  {@Code "@Rowa"}, {@Code "@Rowb"},
-and so on up to {@Code "@Rowh"}:
+and so on:
 @ID @OneRow @Code @Verbatim {
 @Tbl
     aformat { @Cell @I A  |  @Cell @I B }
diff --git a/doc/user/tbl_rule b/doc/user/tbl_rule
index 383ffab..25858df 100644
--- a/doc/user/tbl_rule
+++ b/doc/user/tbl_rule
@@ -5,9 +5,9 @@
 @PP
 There is a @Code "rule" option for drawing a rule around a cell:
 @ID @OneRow @Code "@Cell rule { yes }"
-The other possible values are {@Code no} (the default),
-{@Code single} (the same as {@Code yes}), and {@Code double}, which
-draws a double rule.
+Other values are {@Code no} (the default),
+{@Code single} (the same as {@Code yes}), and {@Code double} (for a
+double rule).
 @PP
 There are @Code "rulehorizontal" and @Code "rulevertical" options which
 draw only horizontal or vertical rules, and also {@Code "ruleabove"},
@@ -83,7 +83,7 @@ above, below, left, and right rules:
     B { rulerightgap }
     C { rulerightcolour }
 }
-As usual, all these options have abbreviated names; and @Code { colour }
+All these options have alternative, abbreviated names; and @Code { colour }
 may be spelt @Code { color } wherever it appears.  Section
 {@NumberOf tbl_summ} has a complete summary of all spellings of all
 options.
@@ -91,19 +91,22 @@ options.
 To clarify exactly where the rules are drawn, let's start with
 a cell with no rules at all:
 @CD @Tbl
-    aformat { @Cell width { 3c } height { 1.5c } paint { lightgrey } A }
+    mv { 0i }
+    aformat { @Cell width { 3c } height { 1.2c } paint { lightgrey } A }
 {
 @Rowa
 }
 Above rules and left rules are drawn within the cell boundary, just
 touching it, with any above rule overstriking any left rule:
 @CD { @Tbl
-    aformat { @Cell width { 3c } height { 1.5c } paint { lightgrey } A }
+    mv { 0i }
+    aformat { @Cell width { 3c } height { 1.2c } paint { lightgrey } A }
 {
 @Rowa
 }
 @Background @Tbl
-    aformat { @Cell width { 3c } height { 1.5c } A }
+    mv { 0i }
+    aformat { @Cell width { 3c } height { 1.2c } A }
     ruleleft { yes }
     ruleabove { yes }
     rulehorizontalwidth { 0.8v }
@@ -116,18 +119,20 @@ touching it, with any above rule overstriking any left rule:
 }
 Below and right rules are drawn just outside the boundary of the
 cell, also touching it:
-@CD @Tbl aformat { @Cell A | @Cell | @Cell B }
+@CD @Tbl mv { 0i } aformat { @Cell A | @Cell | @Cell B }
 {
 @Rowa
     A {
         @Tbl
-            aformat { @Cell width { 3c } height { 1.5c } paint { lightgrey } A }
+            mv { 0i }
+            aformat { @Cell width { 3c } height { 1.2c } paint { lightgrey } A }
         {
         @Rowa
         }
         @Background
         @Tbl
-            aformat { @Cell width { 3c } height { 1.5c } A }
+            mv { 0i }
+            aformat { @Cell width { 3c } height { 1.2c } A }
             rulebelow { yes }
 	    rulehorizontalwidth { 0.8v }
 	    ruleverticalwidth { 0.5v }
@@ -139,13 +144,15 @@ cell, also touching it:
       }
     B {
         @Tbl
-            aformat { @Cell width { 3c } height { 1.5c } paint { lightgrey } A }
+            mv { 0i }
+            aformat { @Cell width { 3c } height { 1.2c } paint { lightgrey } A }
         {
         @Rowa
         }
         @Background
         @Tbl
-            aformat { @Cell width { 3c } height { 1.5c } A }
+            mv { 0i }
+            aformat { @Cell width { 3c } height { 1.2c } A }
             ruleright { yes }
 	    rulehorizontalwidth { 0.8v }
 	    ruleverticalwidth { 0.5v }
@@ -161,13 +168,15 @@ When a right rule is present, any above and below rules are extended
 by the width of the right rule, and they overstrike it:
 @CD {
 @Tbl
-    aformat { @Cell width { 3c } height { 1.5c } paint { lightgrey } A }
+    mv { 0i }
+    aformat { @Cell width { 3c } height { 1.2c } paint { lightgrey } A }
 {
 @Rowa
 }
 @Background
 @Tbl
-    aformat { @Cell width { 3c } height { 1.5c } A }
+    mv { 0i }
+    aformat { @Cell width { 3c } height { 1.2c } A }
     ruleabove { yes }
     ruleright { yes }
     rulebelow { yes }
@@ -186,7 +195,7 @@ rules of width @Code 0.8v drawn in black, and vertical rules of width
 rules produce clean corners, and also that a right rule and a neighbouring
 left rule exactly overstrike each other, as do a below rule and its
 neighbouring above rule.
-@PP
-For information about rules in plain text tables, consult Section
-{@NumberOf tbl_plai}.
+# @PP
+# For information about rules in plain text tables, consult Section
+# {@NumberOf tbl_plai}.
 @End @Section
diff --git a/doc/user/tbl_summ b/doc/user/tbl_summ
index 53f957e..f5d5343 100644
--- a/doc/user/tbl_summ
+++ b/doc/user/tbl_summ
@@ -37,6 +37,14 @@ PS, PDF }
 plain text }
     D { Allowed values }
     rulebelow { yes }
+@HeaderRowd
+    A { Option names (ctd.) }
+    B { Default in
+PS, PDF }
+    C { Default in
+plain text }
+    D { Allowed values }
+    rulebelow { yes }
 @Rowa
     A { paint  p }
     B { nopaint }
@@ -75,7 +83,7 @@ plain text }
     C { no }
     D { {@Code no}, {@Code yes}, or any length }
 @Rowa
-@Rowa
+    ma { 1v }
     A { margin  m }
     B { }
     C { }
@@ -103,7 +111,7 @@ plain text }
     A { marginbelow  mb }
     D { any length }
 @Rowa
-@Rowa
+    ma { 1v }
     A { rule  r }
     B { no }
     C { no }
@@ -127,7 +135,7 @@ plain text }
     A { ruleright  rr }
     D { {@Code no}, {@Code yes}, {@Code single}, or {@Code double} }
 @Rowa
-@Rowa
+    ma { 1v }
     A { rulewidth  rw }
     B { 0.05f }
     D { any length }
@@ -152,7 +160,7 @@ plain text }
     A { rulerightwidth  rrw }
     D { any length }
 @Rowa
-@Rowa
+    ma { 1v }
     A { rulegap  rg }
     B { 0.15f }
     D { any length }
@@ -177,7 +185,7 @@ plain text }
     A { rulerightgap  rrg }
     D { any length }
 @Rowa
-@Rowa
+    ma { 1v }
     A { rulecolour  rulecolor  rc }
     B { black }
     D { any colour from Section {@NumberOf colour} }
@@ -200,11 +208,12 @@ plain text }
     A { rulerightcolour  rulerightcolor  rrc }
     D { any colour from Section {@NumberOf colour} }
 @Rowa
-@Rowa
+    ma { 1v }
     A { ruleplainchar  rpc }
     C { . }
     D { any simple word e.g. @Code + }
     rulebelow { yes }
+@EndHeaderRow
 }
 @DP
 There are seven places where these options may be given, counting the
diff --git a/doc/user/tbl_widt b/doc/user/tbl_widt
index b2e39ad..f988962 100644
--- a/doc/user/tbl_widt
+++ b/doc/user/tbl_widt
@@ -21,8 +21,8 @@ Distributed widely throughout Australia except in the most arid
 parts; many varieties.
 }
 }
-This usually looks good, but if you need something else, the @Code width
-option may be used to give a particular width to a cell:
+This usually looks good, but if you need something else, there is
+the @Code width option:
 @ID @OneRow @Code "@Cell width { 3c }"
 Here we have asked for a cell width of three centimetres; this includes
 the cell margins.  When using @Code width to fine-tune the appearance of
diff --git a/doc/user/vtbl b/doc/user/vtbl
index 24f6a4d..164c3f6 100644
--- a/doc/user/vtbl
+++ b/doc/user/vtbl
@@ -1,2 +1,2 @@
-vi tbl tbl_intr tbl_cell tbl_rows tbl_marg tbl_widt tbl_inde tbl_rule \
-       tbl_span tbl_mult tbl_alig tbl_mark tbl_plai tbl_setu tbl_summ
+vi tbl	tbl_intr tbl_cell tbl_rows tbl_rule tbl_marg tbl_widt tbl_inde	\
+	tbl_alig tbl_span tbl_mark tbl_mult tbl_plai tbl_setu tbl_summ