@Section
   @Title { Introduction }
   @Tag { tabintro }
@Begin
@PP
The Lout definitions for table formatting are kept in a file called
{@Code "tab"}, which you must include at the start of your document if
tab.file @Index { @Code "tab" file }
you want tables, like this:
@ID @OneRow @Code {
"@SysInclude { tab }"
"@SysInclude { doc }"
"@Doc @Text @Begin"
"..."
"@End @Text"
}
Files of definitions, like {@Code "tab"}, must be included before the
setup file.  Alternatively, if you are using your own setup file, you may
place the include commands within it; the place to put them is clearly
marked in all the standard setup files.
@PP
To begin with a very simple example, the input
tab. @Index @Code "@Tab"
@ID @OneRow @Code {
"@Tab"
"    @Fmta { @Col A  !  @Col B  !  @Col C }"
"{"
"    @Rowa A { Austen } B { Chaucer } C { Donne }"
"    @Rowa A { Balzac } B { Darwin } C { Goethe }"
"    @Rowa A { Byron } B { Dickens } C { Homer }"
"}"
}
produces the following table:
@CD
@Tab
    @Fmta { @Col A  !  @Col B  !  @Col 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 "@Tab" symbol, which introduces the table,
comes a @I { format option } & , {@Code "@Fmta"}, describing the format
format.option @Index { format option in tables }
of each row.  It says that each row contains three columns:
{@Code "@Col A"}, {@Code "@Col B"}, and {@Code "@Col C"}.  The format
option may have up to 26 columns, with names chosen freely
from the upper-case letters from @Code A to {@Code Z}.  The symbol
@Code "!" separates each pair of columns.
@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
the @Code "@Rowa" symbol and containing one entry for each column 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 columns, and break paragraphs in the entries to the right widths.
@PP
The result of the @Code "@Tab" 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 "@Tab" by @Code "@OneCol @Tab" 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 @Tab ..."
or else they go into the @Code "@Table" symbol (Section {@NumberOf figures}):
@ID @OneRow @Code {
"@Table"
"    @Caption { ... }"
"@Tab ..."
}
which centres them at the top of the following page and adds a
caption.  Note the difference between {@Code "@Tab"}, which builds a
table, and {@Code "@Table"}, which places an arbitrary object in an
appropriate place.
@End @Section
