TBL(1)                     OpenBSD Reference Manual                     TBL(1)

NAME
     tbl - format tables for troff

SYNOPSIS
     tbl [-Cv] [files ...]

DESCRIPTION
     tbl is a preprocessor for troff which is used to format tables.  These
     tables are composed from columns that can be independently justified,
     headings may be placed over single columns or groups of columns, and hor-
     izontal or vertical lines may be added as desired.

     tbl preprocesses the input files, (or standard input if no file is speci-
     fied) and prints its result to standard output.

     Each table is preceded by a `.TS' (table start) command, and followed by
     a `.TE' (table end) command.  tbl does not touch the reminder of the
     text.  The actual `.TS' and `.TE' lines are copied verbatim as well, so
     that further page layout macros may use these to place the resulting ta-
     bles.

     The format of tbl input is as follows:

         text
         .TS
         table specification
         .TE
         further text
         .TS
         table specification
         .TE
         more text
         ...

     And a table specification is as follows:

         .TS
         table options ;
         table format .
         data
         ...
         .TE

     Each table is formatted independently, and thus must contain a full sepa-
     rate specification.  The `table options' affect the entire table.  Alter-
     nately, the `table format' can be changed in the middle of a table, which
     yields the following template:

         .TS
         table options ;
         table format .
         table data
         ...
         .T&
         table format .
         more data
         ...
         .TE

   TABLE OPTIONS
     Options affecting the whole table may appear on a single line, immediate-
     ly following the `.TS' line.  The option names may be separated by
     spaces, tabulations, or commas, and must end in a semicolon.  Available
     options are:

     allbox       put a box around each item in the table.

     box          put a box around the whole table.

     center       center the table, instead of the default left-adjust.

     delim(ab)    use a and b as eqn(1) delimiters.

     doublebox    put a double box around the whole table.

     expand       make the table as wide as the current line length.

     linesize(n)  set lines and rules in n point type.

     tab(n)       use n spaces instead of a tabulation to separate items.

   TABLE FORMAT
     Each line in the format section corresponds to a single line of the
     table, except for the last line which corresponds to all remaining lines
     up to the next `.T&', if present.  Each column is represented by one let-
     ter from the following list, along with modifiers.  Good style mandates
     separating specifications for each column with spaces or tabs.

     l or L
       left-adjusted column entry.

     c or C
       centered column entry.

     r or R
       right-adjusted colum entry.

     n or N
       numerical column entry, to be aligned with other numerical entries so
       that unit digits match up.

     a or A
       alphabetic subcolumn.  Corresponding entries are left-aligned, and set
       so that the widest is centered within the column.

     s or S
       spanned heading.  The entry for the previous column continues on this
       column.

     ^
       vertically spanned heading.  The entry for the previous row continues
       on this row.

     _ or =
       horizontal rule, replacing the column entry.  `=' creates a double
       rule.  If an adjacent column also contains an horizontal rule or if
       there are vertical rules adjoing the column, the line is extended to
       meet the nearby lines.  Any data entry for this column will be ignored
       and a warning message be printed.

     | or ||
       single or double vertical rule.

     Some extra features are available as modifiers

     Inter-column spacing
       A number may follow a column format.  This number indicates the separa-
       tion between the column and the next column.  The default number is 3.
       The unit used is ens (one en is roughly the width of the letter `n').

     Non-centered vertical spanning
       Vertically spanned  items are normally centered over the rows they
       span.  If the column format is followed by t or T, the item will begin
       at the top line of the span.

     Font changes
       A string containing a font name or number preceded by f or F may be
       used to indicate that the corresponding column should be formatted in
       that font.  In UNIX tbl, all font names are at most two letters long.
       The letters b, b, I, and i are synonyms for fB and fI.  Individual data
       items within the table may override these specifications.

   TABLE DATA
     Each table line is normally entered as one line of data.  Long lines may
     be broken, by using \ as a continuation character.  Table entries are
     separated with tabulations (or with the character specified in the tabs
     option).  There a few exceptions:

     Embedded troff commands
       An input line beginning with a `.' followed by anything but a number is
       passed through to troff unchanged.  For instance, .sp can be used to
       produce extra space within a table.

     Horizontal rules
       A line containing only `_' or `=' produces a single or double horizon-
       tal rule that extends for the full width of the table.

     Single columns horizontal rules
       A table entry containing only `_' or `=' produces a single or double
       horizontal rule that extends for the width of the column.  If neces-
       sary, the rule is extended to meet matching horizontal or vertical
       rules adjoining this column.

GNU DIFFERENCES
     The version of tbl shipping with OpenBSD is part of groff(1), and fea-
     tures a few differences from classical UNIX.

     For instance, the output of GNU tbl cannot be processed with UNIX
     troff(1), but must be processed with GNU troff(1).

     Normally, tbl makes use of diversions to attempt to prevent bad breaks in
     the table.  This can interact with some macro packages' use of diver-
     sions, for instance with footnotes.  The nokeep option can be used to
     tell tbl not to try.

     The decimalpoint (c) option changes the character used as a decimal point
     instead of the default period.

     The f format modifier can be used with a long font name enclosed in
     parenthesis.

     A d format modifier has been added, meaning that a vertically spanning
     entry should be aligned at the bottom.

     There are no arrbitrary limits on the number of columns or the number of
     text blocks in a table.

BUGS
     This documentation is currently incomplete and only describes a subset of
     tbl.

SEE ALSO
     eqn(1), nroff(1)

OpenBSD 4.7                    February 25, 2003                             3
