tbl(1M) tbl(1M)
NAME
tbl - prepare tables for nroff or troff
SYNOPSIS
tbl [-TX] [--] [file ...] [-]
DESCRIPTION
tbl is a preprocessor that prepares tables for nroff(1M) or troff(1M).
tbl assumes that lines between the .TS and .TE command lines describe
tables, thus they are re-formatted; lines outside these command lines
are copied to the standard output. (tbl does not alter the .TS and .TE
command lines.)
The -TX option forces tbl to use only full vertical line motions, mak-
ing the output more suitable for devices that cannot generate partial
vertical line motions (for example, line printers).
If no you give no file names as arguments, or if you specify - as
file, tbl reads the standard input, so it may be used as a filter.
When you use it with eqn(1M) or neqn(1M), put tbl first to minimize
the volume of data passed through pipes.
Macros
.TS Table start.
.TS H Table start with header definition which appears on each con-
tinuation page of the table.
.TH Defines the end of the table header.
.TE Table end.
.T& A new format within a table is initiated with .T& (see Exam-
ples).
Options
Follow .TS with global options. These options are globally valid for
the complete table and must be closed with a semicolon (;). The avail-
able global options are (lower or uppercase letters):
center Centers the table (default is left-adjust);
Note: The British spelling "centre" is not allowed.
expand Makes the table as wide as the current line length;
box Encloses the table in a box;
doublebox Encloses the table in a double box;
allbox Encloses each item of the table in a box;
Page 1 Reliant UNIX 5.44 Printed 11/98
tbl(1M) tbl(1M)
tab(x) Uses the character x instead of a tab to separate items
in a line of input data;
linesize(n) Sets line or rules (e.g. from box) in point size n.
Format descriptions
After global options come lines describing the format of each line of
the table. Each such format line describes one line of the table
itself, except that the last format line (which you must end with a
period) describes all remaining lines of the table. A single key
letter describes each column of each line of the table. You may follow
this key letter with specifiers that determine the font and point size
of the corresponding item, that indicate where vertical bars are to
appear between columns, and that determine column width, inter-column
spacing, etc. The available key-letters are (lower or uppercase
letters):
c Centers item within the column.
r Right-adjusts item within the column.
l Left-adjusts item within the column.
n Numerically adjusts item in the column. Numeric column entries
are justified as follows (see Examples):
- by the decimal point located at the furthest right position to
a digit;
- by the furthest digit to the right-hand side;
- by the optionally insertable control character \&
s Horizontally spanned column(s): entry of previous column is con-
tinued (see Examples).
a Alphabetical sub-column. The longest entry is centered, all
further ones are left-justified after this one (see Example 2).
^ Vertically spanned line(s): entry of upper line is continued and
vertically centered (see Examples).
^t Vertically spanned line(s): entry of upper line is continued and
started in the top line (see Example 4).
Replaces this entry with a horizontal line.
= Replaces this entry with a double horizontal line.
Page 2 Reliant UNIX 5.44 Printed 11/98
tbl(1M) tbl(1M)
Possible additional specifications:
B, I Set font for the column (B = bold, I = italic).
fn, fc, fcc
Set font for the column: Values for n (digit) or c or cc (1 or 2
characters) correspond to values set up via the request .fp n
(see Examples).
e All thus defined columns are formatted to equal width (see Exam-
ple 2).
u Entries are superscripted 1/2 line (see Example 2).
z Length of entry is ignored at calculation of column width,
nevertheless, the entry is printed in whole length (see Example
7).
w(n) Minimum width of column (see Examples).
pn Determination of the point size (analogous to .ps) (see Example 2
and 6).
vn Determination of the line height (analogous to .vs). Is of effect
only in text blocks marked T{ ... T} (see Example 2).
n A number n as additional specification determines the distance
between the columns in n-units (default is 3n) (see Example 3 and
5).
|, ||
Vertical single or double line between the columns.
Table entries
The format lines are followed by lines containing the actual data
(table entries) for the table, followed finally by .TE. Within such
data lines, data items are normally separated by tab characters.
Table entries consist of specifications for the columns defined in the
format description. Possible entries are (cf. Example 2):
text Text specification, may be empty.
T{ Text block which may be several lines long
text (see Examples).
T}
, = Single or double line across the whole column width (adjacent to
neighboring columns).
As individual entry: single or double line across the complete
table width (see Example 2).
Page 3 Reliant UNIX 5.44 Printed 11/98
tbl(1M) tbl(1M)
\ Single line across the width of the entry (not adjacent to neigh-
boring columns) (see Example 2).
\Rc Repeats a character c across the width of the entry (not adjacent
to neighboring columns) (see Example 2).
\^ Performs only in this line the format description of the above
located entry of the previous line; equivalent to the format
description ^.
\a Draws a dotted line to the end of a column (always use together
with the width specification w(n) of a column (see Example 2 and
6).
Note:
All table entries - except for simple text specifications - must not
contain any blanks before or after the column separation character.
No more than maximally 30 text blocks may be used in a table.
EXAMPLES
Example 1:
If we let -> represent a tab (which should be typed as a genuine tab),
then the input:
.TS
center box;
cB s s
cI | cI s
^ | c c
l | n n.
Household Population
Town->Households
->Number->Size
=
Bedminster->789->3.26
Bernards Twp.->3087->3.74
Bernardsville->2018->3.30
Bound Brook->3425->3.04
Bridgewater->7897->3.81
.TE
Page 4 Reliant UNIX 5.44 Printed 11/98
tbl(1M) tbl(1M)
yields (the output is different depending on nroff or troff format-
ting):
_______________________________
| Household Population |
|______________|_______________|
| | Households |
| Town | Number Size|
|||
| Bedminster | 789 3.26|
| Bernards Twp.| 3087 3.74|
| Bernardsville| 2018 3.30|
| Bound Brook | 3425 3.04|
| Bridgewater | 7897 3.81|
|______________|_______________|
Example 2:
The input
.TS
tab(#), center, box;
cf3p+2 s s s.
Spanned, centered main heading
.T&
l | cfI s s
^ | l || r || c.
"vertically centered" # centered italic heading
###
.sp
# leftttt # right # centered
# left # righttttt # ce
# left # rightt # centered
=
.T&
lw(30n) | ne | lue | rw(1c)e
aw(30n) | ne | le | rw(1c)ev+5.
.sp
left-justified main column# 0.05 # lefttt-up # right
alphab. sub-column# 26.04.87 # left # rightttt
short# 43\&57.2 ## right
# 0.675#\#\Rx
long text# 874 ##\R.
short#00.56
---- # ---- #=#T{
wrapped-around long text block;
text
T}
.TE
Page 5 Reliant UNIX 5.44 Printed 11/98
tbl(1M) tbl(1M)
yields:
__________________________________________________________________________
| Spanned, centered main heading |
|_______________________________|_________________________________________|
| | centered italic heading |
| | ____________|_____________|_____________|
| | | | |
| "vertically centered" | leftttt | right | centered |
| | left | righttttt | ce |
| | left | rightt | centered |
|||||
| | | | |
| left-justified main column | 0.05 | lefttt-up | right|
| alphab. sub-column | 26.04.87 | left | rightttt|
| short | 4357.2 | | right|
| | 0.675 | ___________| xxxxxxxxxxx|
| long text | 874 | ____________| ...........|
| short | 00.56 | | |
| ---- | ---- | | wrapped- |
| | | | around |
| | | | long text|
| | | | block; |
| | | | text |
|_______________________________|_____________|_____________|_____________|
Page 6 Reliant UNIX 5.44 Printed 11/98
tbl(1M) tbl(1M)
Example 3: Table with s ("span")
The input
.TS
tab(!), box, center;
cf2 s |cf2 s
l2 l |l2 l.
UNIX ! MS-DOS
ASCII ! ASCII ! Pixel ! Pixel
Mouse ! ! ! Scanner
! ! Color
.TE
yields:
_____________________________________
| UNIX | MS-DOS |
|________________|___________________|
| ASCII ASCII | Pixel Pixel |
| Mouse | Scanner|
| | Color |
|________________|___________________|
Page 7 Reliant UNIX 5.44 Printed 11/98
tbl(1M) tbl(1M)
Example 4: Table with vertically spanned lines at top (^t)
The input
.TS
tab(#), center;
lf3| l| lf3.
deciduous ## coniferous
.T&
l| l| l
l| ^t| l.
.sp .5
oak #T{
\f2Central European
.br
trees\f1
T}# spruce
elm ## larch
birch ## pine
beech ## silver fir
poplar ## juniper
chestnut ## yew
.TE
yields:
deciduous | | coniferous
__________|__________________|_____________
oak | Central European| spruce
elm | trees | larch
birch | | pine
beech | | silver fir
poplar | | juniper
chestnut | | yew
Page 8 Reliant UNIX 5.44 Printed 11/98
tbl(1M) tbl(1M)
Example 5: Table with automatic entry counting
The input
.TS
tab(#), center;
l1 l n1 l.
.nr X 0 1
\n+X) # Chandelier, Crystal, 12 Candles # 5500 # Kcs
\n+X) # Candlestick, Light Balls with Chains # 1800 # Kcs
\n+X) # Table Clock, Wooden # 700 # Kcs
.nr Y 0 1
.af Y a
\n+Y) # Tureen
\n+Y) # Oval Bowl
\n+Y) # Oval Bowl with a Handle
\n+Y) # Bowl, Triangular Form
\n+X) # Detto Amphora # 300 # Kcs
\n+X) # Detto Drinking Service # 1000 # Kcs
.nr YY 0 1
.af YY a
\n+(YY) # 1 Can
\n+(YY) # Cup with a Handle
\n+X) # Vase, Hand-ground # 400 # Kcs
\n+X) # Drinking-cups, 6 Pieces, Metal Edge # 240 # Kcs
\n+X) # Drinking-glasses, 4 Pieces, with Golfers # 120 # Kcs
.TE
Page 9 Reliant UNIX 5.44 Printed 11/98
tbl(1M) tbl(1M)
yields:
1) Chandelier, Crystal, 12 Candles 5500 Kcs
2) Candlestick, Light Balls with Chains 1800 Kcs
3) Table Clock, Wooden 700 Kcs
a) Tureen
b) Oval Bowl
c) Oval Bowl with a Handle
d) Bowl, Triangular Form
4) Detto Amphora 300 Kcs
5) Detto Drinking Service 1000 Kcs
a) 1 Can
b) Cup with a Handle
6) Vase, Hand-ground 400 Kcs
7) Drinking-cups, 6 Pieces, Metal Edge 240 Kcs
8) Drinking-glasses, 4 Pieces, with Golfers 120 Kcs
A table with "automatic" counting of table entries is created when the
nroff/troff requests .nr and .af are used. A numeric register is set
when the .nr request is used. The exact syntax of a numeric register
is: .nr Name N M where N specifies the start value and M the
increment/decrement value. In our example, the register is named "X",
the start value is 0 and the increment value is 1. The register "X" is
incremented by the value 1 with each interpolation (copying of the
register value) according to the syntax: \n+Name.
A Format is assigned to a register Name when the request .af Name For-
mat is used. This means in our example: first the "Y" is set, as
described above. Then format "a" is assigned to register "Y" (= alpha-
betic counting with lowercase Latin letters). Finally, register "Y" is
again incremented with each interpolation.
Attention: The registers must be set within the table.
Page 10 Reliant UNIX 5.44 Printed 11/98
tbl(1M) tbl(1M)
Example 6: Table with dotted lines (\a)
The input
.TS
tab(#), center;
lw(30n) cBp10 s s
lw(30n) c s s
lw(30n) cBp10 cBp10 cBp10
lw(30n) cBp10 s s
lw(30n) n n n.
#Annual Gross Balance, December 31st
#
#1988#1987#1986
#(Dollars in Millions)
.sp
Premiums\a#$\010,922.7#$\010,330.7#$\0\09,252.4
Investments\a#3,671.7#3,146.0#2,749.7
Income Taxes\a#24.4#91.6#71.9
Net Incomes\a#375.2#373.1#312.4
Assets\a#41,645.8#34,434.7#32,876.6
.TE
yields:
Annual Gross Balance, December 31st
_____________________________________
1988 1987 1986
(Dollars in Millions)
Premiums...................... $ 10,922.7 $ 10,330.7 $ 9,252.4
Investments................... 3,671.7 3,146.0 2,749.7
Income Taxes.................. 24.4 91.6 71.9
Net Incomes................... 375.2 373.1 312.4
Assets........................ 41,645.8 34,434.7 32,876.6
A dotted line after a table entry is achieved by entering \a. It is
important to enter the length of the column with w(n) and the entry of
\a at the same time. If this is not performed, the column setup will
be destroyed (in our example: 30n in the format descriptions).
Note: The entries \0 are not part of the tbl syntax, but normal
nroff/troff special functions which are used to create a blank charac-
ter with the width of the digit zero. They are only for aesthetic rea-
sons to ensure a correct spacing with the $ characters in the columns.
Page 11 Reliant UNIX 5.44 Printed 11/98
tbl(1M) tbl(1M)
Example 7: Table with overlapping columns (z)
The format description z causes the length of an entry to ignored when
the column width is calculated. The function can now be used to gen-
erate overlapping columns in place of parallel columns, as it is nor-
mally the case. The distribution of entries over various columns leads
to juxtaposition of entries, as can be seen in this example. The input
.TS
tab(!);
lw(5n)z lw(5n)z lw(10n)z l l1 lw(2n)z1 lw(5n)z.
!!!!Space
.sp
!!Dimensionality!!!!Non-Dimensionality
.sp
!Horizontality!!Verticality!!Surface
.sp
Prospectivity!!Laterality!!!Volume
.TE
yields:
Space
Dimensionality Non-Dimensionality
Horizontality Verticality Surface
Prospectivity Laterality Volume
NOTES
There are still some problems when using tbl to construct multi-page
boxed tables with continuation headings (.TS H, .TH). In some cases,
boxes are not properly constructed (distorted pages, loops) after
crossing a page boundary and the table drops into the page feed trap.
In this situation, the macro .ch #f must be entered at the point at
which the page feed occurs in the output (it disables the trap mechan-
ism).
In addition, with multi-page tables with boxes or vertical lines, the
macro .T# should be inserted at the point at which the page feed is to
take place.
SEE ALSO
nroff(1M), troff(1M).
REFERENCE
M. E. Lesk, TBL - A Program To Format Tables
D. Dougherty, T. O'Reilly, UNIX TEXT PROCESSING, Hayden Books, Indi-
anapolis, Indiana 46268 USA, ISBN 0-672-46291-5
Page 12 Reliant UNIX 5.44 Printed 11/98