1 files changed, 119 insertions, 0 deletions
diff --git a/doc/user/tbl_intr b/doc/user/tbl_intr
new file mode 100644
index 0000000..a46da18
--- /dev/null
+++ b/doc/user/tbl_intr
@@ -0,0 +1,119 @@
+@Section
+    @Title { Getting started }
+    @Tag { tbl_intr }
+@Begin
+@PP
+The Lout definitions for table formatting
+@FootNote {
+The @Code "tbl" package described here replaces the @Code "tab"
+package of Version 3.12 and earlier.  For backward compatibility
+the @Code "tab" package is still available and still works as
+described in older versions of this documentation.  Users of
+@Code "tab" will find simple uses of @Code "tbl" to be very similar,
+replacing @Code "@Tab" by {@Code "@Tbl"}, @Code "@Fmta" by
+{@Code "aformat"}, @Code "@Col" by {@Code "@Cell"}, and
+@Code "!" by {@Code "|"}.
+}
+are kept in a file called {@Code "tbl"}, which you must include at
+the start of your document if
+tbl.file @Index { @Code "tbl" file }
+you want tables, like this:
+@ID @OneRow @Code {
+"@SysInclude { tbl }"
+"@SysInclude { doc }"
+"@Doc @Text @Begin"
+"..."
+"@End @Text"
+}
+Specialized setup files, like {@Code "tbl"}, are included before the main
+setup file (@Code "doc" in this case).  Alternatively, if you are using
+your own setup file, you may place the include commands within it, near the
+start.
+@PP
+To begin with a very simple example, the table
+tbl. @Index @Code "@Tbl"
+@CD
+@Tbl
+    aformat { @Cell A  |  @Cell B  |  @Cell C }
+{
+@Rowa
+    A { Austen }
+    B { Chaucer }
+    C { Donne }
+@Rowa
+    A { Balzac }
+    B { Darwin }
+    C { Goethe }
+@Rowa
+    A { Byron }
+    B { Dickens }
+    C { Homer }
+}
+is produced by the following input:
+@ID @OneRow @Code {
+"@Tbl"
+"    aformat { @Cell A  |  @Cell B  |  @Cell C }"
+"{"
+"@Rowa"
+"    A { Austen }"
+"    B { Chaucer }"
+"    C { Donne }"
+"@Rowa"
+"    A { Balzac }"
+"    B { Darwin }"
+"    C { Goethe }"
+"@Rowa"
+"    A { Byron }"
+"    B { Dickens }"
+"    C { Homer }"
+"}"
+}
+Immediately after the @Code "@Tbl" symbol, which introduces the table,
+comes a @I { format option }, {@Code "aformat"}, describing the format of
+each row.  It says that each row contains three cells:  {@Code "@Cell A"},
+{@Code "@Cell B"}, and {@Code "@Cell C"}.  The format option may have up
+to 26 cells, with names chosen freely from the upper-case letters from
+@Code A to {@Code Z}.  The symbol @Code "|" separates each cell from the next.
+@PP
+After the format option comes the body of the table, enclosed in
+braces.  It consists entirely of a sequence of rows, each introduced by
+a @Code "@Rowa" symbol and containing one entry for each cell of the
+format option, as shown (the row may occupy any number of lines of the
+input file).  The entries may be arbitrary Lout objects, such as words,
+paragraphs, equations, figures, and so on without restriction.  An entry
+may be omitted altogether if it is empty.  Lout will choose suitable widths
+for the cells, and break paragraphs in the entries to the right widths.
+@PP
+The result of the @Code "@Tbl" symbol is an object.  As usual with
+Lout, this object may appear at any point in the document,
+@FootNote {
+In rare cases, when the table occupies an entire paragraph but is not
+displayed, a bug in the current version of Basser Lout causes the second
+column to appear much too far to the right.  Until the problem is fixed,
+the first thing to try if this occurs is to replace the very first
+row symbol ({@Code "@Rowa"}, {@Code "@Rowb"}, etc.) by {@Code "@FirstRowa"},
+{@Code "@FirstRowb"}, etc.
+# That should work, but if it doesn't, replacing
+# @Code "@Tbl" by @Code "@OneCol @Tbl" certainly will, although it also
+# prevents the table from breaking across page boundaries.
+}
+even within a paragraph or another table.  Most commonly, though, tables
+are displayed using the @Code "@IndentedDisplay" and @Code "@CentredDisplay"
+symbols (Section {@NumberOf displays}):
+@ID @Code "@CentredDisplay @Tbl ..."
+or else they go into the @Code "@Table" symbol (Section {@NumberOf figures}):
+@ID @OneRow @Code {
+"@Table"
+"    @Caption { ... }"
+"@Tbl ..."
+}
+which centres them at the top of the following page and adds a
+caption.  Note the difference between {@Code "@Tbl"}, which builds a
+table, and {@Code "@Table"}, which places an arbitrary object in an
+appropriate place.  It's important to remember that the result
+is an object like any other, because from time to time one wants such
+things as rotated tables whose entire contents are to be italicised:
+@ID @Code "90d @Rotate @I @Tbl ..."
+and it helps to remember that the full power of Lout can be
+brought to bear on the @I entire table.
+@End @Section