tbl - format tables for troff
tbl [-Cv] [files ...]
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 horizontal
or vertical lines may be added as desired.
tbl preprocesses the input files, (or standard input if no
file is specified)
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 tables.
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 separate
specification. The `table options' affect the entire
table. Alternately,
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 [Toc] [Back]
Options affecting the whole table may appear on a single
line, immediately
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 leftadjust.
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 [Toc] [Back]
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 letter
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 leftaligned, 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 separation
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 [Toc] [Back]
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 horizontal
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 necessary,
the rule is extended to meet matching horizontal or
vertical
rules adjoining this column.
The version of tbl shipping with OpenBSD is part of
groff(1), and features
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 diversions,
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.
This documentation is currently incomplete and only describes a subset of
tbl.
eqn(1), nroff(1)
OpenBSD 3.6 February 25, 2003
[ Back ] |
