| TBL(7) | Miscellaneous Information Manual | TBL(7) |
NAME
tbl — tables in
manual pages
DESCRIPTION
The tbl language describes a table inside
a manual page written in mdoc(7) or
man(7). It began as a preprocessor that
turned tables into roff(7) requests;
oxdoc(1) reads it directly, as part of
the page.
A table starts with a TS line and ends
with a TE line. Between them are, in order:
- an optional line of options, ending in a semicolon;
- the layout: one or more rows of column descriptions, the last ending in a period;
- the data: one line per row, its cells separated by tabs.
.TS box tab(:); lb lb l n. Name:Size kernel:31 modules:7 .TE
The layout's rows describe the data's rows in turn, and its last
row describes all the rest. A line T& among the
data starts a new layout for the rows after it, up to the next period.
In man(7), a table is set off from the text before it by a blank line; in mdoc(7), it is not. A table's lines are not formatted as text: a macro line inside a table is reported and ignored, as described under DATA.
OPTIONS
Options are words, separated by spaces or commas, some with an argument in parentheses. Case does not matter.
allbox- Draw a box around the table and lines between all its cells.
box,frame- Draw a box around the table.
center,centre- Centre the table between the current indentation and the right margin. A table too wide for that space moves left of the indentation.
decimalpoint(c)- Align numbers at c instead of a period.
doublebox,doubleframe- Draw a double box around the table.
tab(c)- Separate cells with c instead of a tab.
The options delim,
expand, linesize,
nokeep, nospaces and
nowarn are accepted and have no effect.
LAYOUT
Each layout row is a list of column keys, each followed by its modifiers; spaces between them are optional. Rows are separated by commas or line ends, and the layout ends with a period.
Keys
l- Left-aligned text.
r- Right-aligned text.
c- Centred text.
n- A number: the numbers in the column are aligned at their decimal point, or
at ‘
\&’ where a cell contains one, or else after their last digit. A cell without a digit is centred. If the column is wider than its numbers need, they are centred in it together. a- Left-aligned text, indented by one column.
s- The cell to the left spans this column too.
^- The cell above spans this row too; this row's own data for the column is ignored.
_,-- A horizontal line across the cell.
=- A double horizontal line across the cell.
|- A vertical line between the columns on either side, or at the table's edge; two for a double line.
Modifiers
b- Bold.
i- Italic.
fname- The font name, one or two characters:
B,I,BI,R, or a number from 1 to 4. Fonts replace each other: the last one given counts. e- All columns marked
eare as wide as the widest of them. x- The column takes a share of the width the other columns leave on the line.
w(width)- The column is at least width wide, in the scaling units of man(7), columns by default. A width that is not a number is ignored.
- number
- The space after the column, in columns; three by default.
The modifiers d,
p, t,
u, v and
z are accepted and have no effect on a terminal.
DATA
Each data line is a row, its cells separated by the tab character. A cell's text is formatted as in a text line: escape sequences work, and spaces at its edges are kept. Cells beyond the layout row's columns are reported and ignored.
A line consisting of ‘_’ or
‘=’ alone draws a single or double
line across the table. A cell consisting of one of them draws a line across
the cell, reaching the vertical lines beside it;
‘\_’ draws one as wide as the column,
and ‘\^’ leaves the cell for the one
above to span.
A cell holding ‘T{’ at the
end of a line starts a text block: the lines after it, up to one starting
with ‘T}’, are filled into a paragraph
as wide as the column. More cells may follow
‘T}’ on its line. A text block's
column is at most a fraction of the line wide: the line divided by one more
than the number of columns.
A macro line in a table is not formatted.
br, sp,
ce and rj leave nothing; any
other macro leaves its arguments as text, as a row of their own or, inside a
text block, as part of the block. Definitions of strings, registers and
macros take effect, and macros the page defines are expanded first.
EXAMPLES
A table of numbers under a spanning heading:
.TS center tab(:); cb s l n. Daily intake (MJ) _ Carbohydrates:4.5 Fats:2.25 Protein:3 .TE
is shown as
| Daily intake (MJ) | |
| Carbohydrates | 4.5 |
| Fats | 2.25 |
| Protein | 3 |
A boxed table with a text block:
.TS
allbox tab(:);
lb lb
l lw(30).
Option:Meaning
-s:T{
Start in single-user mode, with a shell on the console.
T}
-h:Use the serial console.
.TE
is shown as
| Option | Meaning |
| -s | Start in single-user mode, with a shell on the console. |
| -h | Use the serial console. |
DIAGNOSTICS
In lint mode, oxdoc(1)
reports problems in tables at the levels
mandoc(1) uses: unknown options and
missing or wrong option arguments, invalid characters and unmatched
parentheses in the layout, an empty layout, a layout row starting with a
span, extra cells, data in a cell spanned from above, a text block still
open at TE, a table without data, and ignored
macros.
SEE ALSO
man(1), oxdoc(1), eqn(7), man(7), mdoc(7), roff(7)
M. E. Lesk, Tbl — A Program to Format Tables, Bell Laboratories, 1976.
HISTORY
The tbl preprocessor was written by
M. E. Lesk at Bell Laboratories and first appeared
in Version 7 AT&T UNIX. This manual was
written for OxideBSD.
BUGS
Equations inside tables are not supported. The
expand option has no effect.
| September 27, 2026 | OxideBSD |