.\" $OpenBSD: tbl.1,v 1.4 2003/03/01 23:53:03 wcobb Exp $
.\"
.\" Copyright (c) 2003 Marc Espie
.\"
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd February 25, 2003
.Dt TBL 1
.Os
.Sh NAME
.Nm tbl
.Nd format tables for troff
.Sh SYNOPSIS
.Nm tbl
.Op Fl Cv
.Op Ar files ...
.Sh DESCRIPTION
.Nm
is a preprocessor for
.Xr 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.
.Pp
.Nm
preprocesses the input
.Ar files ,
(or standard input if no file is specified)
and prints its result to standard output.
.Pp
Each table is preceded by a
.Sq .TS
(table start) command, and followed by a
.Sq .TE
(table end) command.
.Nm
does not touch the reminder of the text.
The actual
.Sq .TS
and
.Sq .TE
lines are copied verbatim as well, so that further page layout macros
may use these to place the resulting tables.
.Pp
The format of
.Nm
input is as follows:
.Bd -literal
    text
    \&.TS
    table specification
    \&.TE
    further text
    \&.TS
    table specification
    \&.TE
    more text
    \&...
.Ed
.Pp
And a table specification is as follows:
.Bd -literal
    \&.TS
    table options ;
    table format .
    data
    ...
    \&.TE
.Ed
.Pp
Each table is formatted independently, and thus must contain a full
separate specification.
The
.Sq table options
affect the entire table.
Alternately, the
.Sq table format
can be changed in the middle of a table,
which yields the following template:
.Bd -literal
    \&.TS
    table options ;
    table format .
    table data
    \&...
    \&.T&
    table format .
    more data
    \&...
    \&.TE
.Ed
.Pp
.Ss TABLE OPTIONS
Options affecting the whole table may appear on a single line,
immediately following the
.Sq .TS
line.
The option names may be separated by spaces, tabulations, or commas,
and must end in a semicolon.
Available options are:
.Bl -tag -width linesize(n)
.It allbox
put a box around each item in the table.
.It box
put a box around the whole table.
.It center
center the table, instead of the default left-adjust.
.It delim(ab)
use 
.Ar a 
and 
.Ar b 
as
.Xr eqn 1
delimiters.
.It doublebox
put a double box around the whole table.
.It expand
make the table as wide as the current line length.
.It linesize(n)
set lines and rules in 
.Ar n 
point type.
.It tab(n)
use 
.Ar n 
spaces instead of a tabulation to separate items.
.El
.Ss 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
.Sq .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.
.Bl -tag -width l or L
.It l or L
left-adjusted column entry.
.It c or C
centered column entry.
.It r or R
right-adjusted colum entry.
.It n or N
numerical column entry, to be aligned with other numerical entries so that
unit digits match up.
.It a or A
alphabetic subcolumn.
Corresponding entries are left-aligned, and set so that the widest is centered
within the column.
.It s or S
spanned heading. 
The entry for the previous column continues on this column.
.It ^
vertically spanned heading. 
The entry for the previous row continues on this row.
.It _ or =
horizontal rule, replacing the column entry.
.Sq =
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.
.It | or ||
single or double vertical rule.
.El
.Pp
Some extra features are available as modifiers
.Bl -tag -width l
.It "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 
.Po
one en is roughly the width of the letter
.Sq n
.Pc .
.It "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.
.It "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
.Ux
.Nm ,
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.
.El
.Ss 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
.Ar tabs
option).
There a few exceptions:
.Bl -tag -width l
.It "Embedded troff commands"
An input line beginning with a
.Sq \&.
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.
.It "Horizontal rules"
A line containing only
.Sq _
or
.Sq =
produces a single or double horizontal rule that extends for the
full width of the table.
.It "Single columns horizontal rules"
A table entry containing only
.Sq _
or
.Sq =
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.
.El
.Sh GNU DIFFERENCES
The version of
.Nm
shipping with
.Ox
is part of 
.Xr groff 1 , 
and features a few differences from classical
.Ux .
.Pp
For instance, the output of GNU
.Nm
cannot be processed with
.Ux
.Xr troff 1 ,
but must be processed with GNU
.Xr troff 1 .
.Pp
Normally,
.Nm
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
.Ar nokeep
option
can be used to tell
.Nm
not to try.
.Pp
The
.Ar decimalpoint (c)
option changes the character used as a decimal point instead of the default
period.
.Pp
The
.Ar f
format modifier can be used with a long font name enclosed in parenthesis.
.Pp
A
.Ar d
format modifier has been added, meaning that a vertically spanning entry
should be aligned at the bottom.
.Pp
There are no arrbitrary limits on the number of columns or the number of
text blocks in a table.
.Sh BUGS
This documentation is currently incomplete and only describes a subset of
.Nm tbl .
.Sh SEE ALSO
.Xr eqn 1 ,
.Xr nroff 1