version 1.25, 2015/01/28 04:19:35 |
version 1.36, 2021/09/07 11:48:19 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2014,2015,2017,2018,2019 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
|
|
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Nm tbl |
.Nm tbl |
language is a table-formatting language. |
language formats tables. |
It is used within |
It is used within |
.Xr mdoc 7 |
.Xr mdoc 7 |
and |
and |
.Xr man 7 |
.Xr man 7 |
.Ux |
pages. |
manual pages. |
|
This manual describes the subset of the |
This manual describes the subset of the |
.Nm |
.Nm |
language accepted by the |
language accepted by the |
.Xr mandoc 1 |
.Xr mandoc 1 |
utility. |
utility. |
.Pp |
.Pp |
Tables within |
Each table is started with a |
.Xr mdoc 7 |
|
or |
|
.Xr man 7 |
|
are enclosed by the |
|
.Sq TS |
|
and |
|
.Sq TE |
|
macro tags, whose precise syntax is documented in |
|
.Xr roff 7 . |
|
Tables consist of a series of options on a single line, followed by the |
|
table layout, followed by data. |
|
.Pp |
|
For example, the following creates a boxed table with digits centered in |
|
the cells. |
|
.Bd -literal -offset indent |
|
\&.TS |
|
tab(:) box; |
|
c5 c5 c5. |
|
1:2:3 |
|
4:5:6 |
|
\&.TE |
|
.Ed |
|
.Pp |
|
When formatted, the following output is produced: |
|
.Bd -filled -offset indent -compact |
|
.TS |
|
tab(:) box; |
|
c5 c5 c5. |
|
1:2:3 |
|
4:5:6 |
|
.TE |
|
.Ed |
|
.Sh TABLE STRUCTURE |
|
Tables are enclosed by the |
|
.Sq TS |
|
and |
|
.Sq TE |
|
.Xr roff 7 |
.Xr roff 7 |
macros. |
.Ic \&TS |
A table consists of an optional single line of table |
macro, consist of at most one line of |
.Sx Options |
.Sx Options , |
terminated by a semicolon, followed by one or more lines of |
one or more |
.Sx Layout |
.Sx Layout |
specifications terminated by a period, then |
lines, one or more |
.Sx Data . |
.Sx Data |
|
lines, and ends with a |
|
.Ic \&TE |
|
macro. |
All input must be 7-bit ASCII. |
All input must be 7-bit ASCII. |
Example: |
|
.Bd -literal -offset indent |
|
\&.TS |
|
box tab(:); |
|
c | c |
|
| c | c. |
|
1:2 |
|
3:4 |
|
\&.TE |
|
.Ed |
|
.Pp |
|
Table data is |
|
.Em pre-processed , |
|
that is, data rows are parsed then inserted into the underlying stream |
|
of input data. |
|
This allows data rows to be interspersed by arbitrary |
|
.Xr roff 7 , |
|
.Xr mdoc 7 , |
|
and |
|
.Xr man 7 |
|
macros such as |
|
.Bd -literal -offset indent |
|
\&.TS |
|
tab(:); |
|
c c c. |
|
1:2:3 |
|
\&.Ao |
|
3:2:1 |
|
\&.Ac |
|
\&.TE |
|
.Ed |
|
.Pp |
|
in the case of |
|
.Xr mdoc 7 |
|
or |
|
.Bd -literal -offset indent |
|
\&.TS |
|
tab(:); |
|
c c c. |
|
\&.ds ab 2 |
|
1:\e*(ab:3 |
|
\&.I |
|
3:2:1 |
|
\&.TE |
|
.Ed |
|
.Pp |
|
in the case of |
|
.Xr man 7 . |
|
.Ss Options |
.Ss Options |
The first line of a table may contain options separated by spaces, tabs, |
If the first input line of a table ends with a semicolon, it contains |
or commas and terminated by a semicolon. |
case-insensitive options separated by spaces, tabs, or commas. |
If the first line does not have a terminating semicolon, it is assumed |
Otherwise, it is interpreted as the first |
that no options are specified and instead a |
|
.Sx Layout |
.Sx Layout |
is processed. |
line. |
Some options require arguments enclosed by parentheses. |
.Pp |
The following case-insensitive options are available: |
The following options are available. |
|
Some of them require arguments enclosed in parentheses: |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
.It Cm allbox |
.It Cm allbox |
Draw a single-line box around each table cell. |
Draw a single-line box around each table cell. |
Currently treated as a synonym for |
|
.Cm box . |
|
.It Cm box |
.It Cm box |
Draw a single-line box around the table. |
Draw a single-line box around the table. |
For GNU compatibility, this may also be invoked with |
For GNU compatibility, this may also be invoked with |
Line 179 Allow page breaks within the table. |
|
Line 94 Allow page breaks within the table. |
|
This is a GNU extension and currently ignored. |
This is a GNU extension and currently ignored. |
.It Cm nospaces |
.It Cm nospaces |
Ignore leading and trailing spaces in data cells. |
Ignore leading and trailing spaces in data cells. |
This is a GNU extension and currently ignored. |
This is a GNU extension. |
.It Cm nowarn |
.It Cm nowarn |
Suppress warnings about tables exceeding the current line length. |
Suppress warnings about tables exceeding the current line length. |
This is a GNU extension and currently ignored. |
This is a GNU extension and currently ignored. |
.It Cm tab |
.It Cm tab |
Use the single-character argument as a delimiter between data cells. |
Use the single-character argument as a delimiter between data cells. |
By default, the tab character is used. |
By default, the horizontal tabulator character is used. |
.El |
.El |
.Ss Layout |
.Ss Layout |
The table layout follows |
The table layout follows an |
.Sx Options |
.Sx Options |
or a |
line or a |
.Sq \&T& |
.Xr roff 7 |
macro invocation. |
.Ic \&TS |
Layout specifies how data rows are displayed on output. |
or |
Each layout line corresponds to a line of data; the last layout line |
.Ic \&T& |
applies to all remaining data lines. |
macro. |
Layout lines may also be separated by a comma. |
Each layout line specifies how one line of |
Each layout cell consists of one of the following case-insensitive keys: |
.Sx Data |
|
is formatted. |
|
The last layout line ends with a full stop. |
|
It also applies to all remaining data lines. |
|
Multiple layout lines can be joined by commas on a single physical |
|
input line. |
|
.Pp |
|
Each layout line consists of one or more layout cell specifications, |
|
optionally separated by whitespace. |
|
The following case-insensitive key characters start a new cell |
|
specification: |
.Bl -tag -width 2n |
.Bl -tag -width 2n |
.It Cm c |
.It Cm c |
Center a literal string within its column. |
Center the string in this cell. |
.It Cm r |
.It Cm r |
Right-justify a literal string within its column. |
Right-justify the string in this cell. |
.It Cm l |
.It Cm l |
Left-justify a literal string within its column. |
Left-justify the string in this cell. |
.It Cm n |
.It Cm n |
Justify a number around its last decimal point. |
Justify a number around its last decimal point. |
If the decimal point is not found on the number, it's assumed to trail |
If no decimal point is found in the number, |
the number. |
it is assumed to trail the number. |
.It Cm s |
.It Cm s |
Horizontally span columns from the last |
Horizontally span columns from the last |
.No non- Ns Cm s |
.Pf non- Cm s |
data cell. |
layout cell. |
It is an error if spanning columns follow a |
It is an error if a column span follows a |
.Cm \- |
.Cm _ |
or |
or |
.Cm \(ba |
.Cm = |
cell, or come first. |
cell, or comes first on a layout line. |
This option is not supported by |
The combined cell as a whole consumes only one cell |
.Xr mandoc 1 . |
of the corresponding data line. |
.It Cm a |
.It Cm a |
Left-justify a literal string and pad with one space. |
Left-justify a string and pad with one space. |
.It Cm ^ |
.It Cm \(ha |
Vertically span rows from the last |
Vertically span rows from the last |
.No non- Ns Cm ^ |
.Pf non- Cm \(ha |
data cell. |
layout cell. |
It is an error to invoke a vertical span on the first layout row. |
It is an error to invoke a vertical span on the first layout line. |
Unlike a horizontal spanner, you must specify an empty cell (if it not |
Unlike a horizontal span, a vertical span consumes a data cell |
empty, the data is discarded) in the corresponding data cell. |
and discards the content. |
.It Cm \- |
.It Cm _ |
Replace the data cell (its contents will be lost) with a single |
Draw a single horizontal line in this cell. |
horizontal line. |
This consumes a data cell and discards the content. |
This may also be invoked with |
It may also be invoked with |
.Cm _ . |
.Cm \- . |
.It Cm = |
.It Cm = |
Replace the data cell (its contents will be lost) with a double |
Draw a double horizontal line in this cell. |
horizontal line. |
This consumes a data cell and discards the content. |
.It Cm \(ba |
|
Emit a vertical bar instead of data. |
|
.It Cm \(ba\(ba |
|
Emit a double-vertical bar instead of data. |
|
.El |
.El |
.Pp |
.Pp |
Keys may be followed by a set of modifiers. |
Each cell key may be followed by zero or more of the following |
A modifier is either a modifier key or a natural number for specifying |
case-insensitive modifiers: |
the minimum width of a column. |
|
The following case-insensitive modifier keys are available: |
|
.Bl -tag -width 2n |
.Bl -tag -width 2n |
.It Cm b |
.It Cm b |
Use a bold font for the contents of this column. |
Use a bold font for the contents of this cell. |
.It Cm d |
.It Cm d |
Move cell content down to the last cell of a vertical span. |
Move content down to the last row of this vertical span. |
Currently ignored. |
Currently ignored. |
.It Cm e |
.It Cm e |
Make this column wider to match the maximum width |
Make this column wider to match the maximum width |
Line 259 of any other column also having the |
|
Line 178 of any other column also having the |
|
.Cm e |
.Cm e |
modifier. |
modifier. |
.It Cm f |
.It Cm f |
The next character selects the font to use for this column. |
The next one or two characters select the font to use for this cell. |
|
One-character font names must be followed by a blank or period. |
See the |
See the |
.Xr roff 7 |
.Xr roff 7 |
manual for supported one-character font names. |
manual for supported font names. |
.It Cm i |
.It Cm i |
Use an italic font for the contents of this column. |
Use an italic font for the contents of this cell. |
.It Cm m |
.It Cm m |
Specify a cell start macro. |
Specify a cell start macro. |
This is a GNU extension and currently unsupported. |
This is a GNU extension and currently unsupported. |
Line 277 Set the vertical line spacing to the following unsigne |
|
Line 197 Set the vertical line spacing to the following unsigne |
|
or change it by the following signed argument. |
or change it by the following signed argument. |
Currently ignored. |
Currently ignored. |
.It Cm t |
.It Cm t |
Do not vertically center cell content in the vertical span, |
Do not vertically center content in this vertical span, |
leave it at the top. |
leave it in the top row. |
Currently ignored. |
Currently ignored. |
.It Cm u |
.It Cm u |
Move cell content up by half a table line. |
Move cell content up by half a table row. |
Currently ignored. |
Currently ignored. |
.It Cm w |
.It Cm w |
Specify minimum column width. |
Specify a minimum column width. |
Currently ignored. |
|
.It Cm x |
.It Cm x |
After determining the width of all other columns, distribute the |
After determining the width of all other columns, distribute the |
rest of the line length among all columns having the |
rest of the line length among all columns having the |
Line 293 rest of the line length among all columns having the |
|
Line 212 rest of the line length among all columns having the |
|
modifier. |
modifier. |
.It Cm z |
.It Cm z |
Do not use this cell for determining the width of this column. |
Do not use this cell for determining the width of this column. |
|
.It Cm \&| |
|
Draw a single vertical line to the right of this cell. |
|
.It Cm || |
|
Draw a double vertical line to the right of this cell. |
.El |
.El |
.Pp |
.Pp |
For example, the following layout specifies a center-justified column of |
If a modifier consists of decimal digits, |
minimum width 10, followed by vertical bar, followed by a left-justified |
it specifies a minimum spacing in units of |
column of minimum width 10, another vertical bar, then a column using |
.Cm n |
bold font justified about the decimal point in numbers: |
between this column and the next column to the right. |
.Pp |
The default is 3. |
.Dl c10 | l10 | nfB |
If there is a vertical line, it is drawn inside the spacing. |
.Ss Data |
.Ss Data |
The data section follows the last layout row. |
The data section follows the last |
By default, cells in a data section are delimited by a tab. |
.Sx Layout |
This behaviour may be changed with the |
line. |
|
Each data line consists of one or more data cells, delimited by |
.Cm tab |
.Cm tab |
option. |
characters. |
If |
.Pp |
.Cm _ |
If a data cell contains only the two bytes |
|
.Ql \e\(ha , |
|
the cell above spans to this row, as if the layout specification |
|
of this cell were |
|
.Cm \(ha . |
|
.Pp |
|
If a data cell contains only the single character |
|
.Ql _ |
or |
or |
.Cm = |
.Ql = , |
is specified, a single or double line, respectively, is drawn across the |
a single or double horizontal line is drawn across the cell, |
data field. |
joining its neighbours. |
If |
If a data cell contains only the two character sequence |
.Cm \e- |
.Ql \e_ |
or |
or |
.Cm \e= |
.Ql \e= , |
is specified, a line is drawn within the data field (i.e. terminating |
a single or double horizontal line is drawn inside the cell, |
within the cell and not draw to the border). |
not joining its neighbours. |
If the last cell of a line is |
If a data line contains nothing but the single character |
.Cm T{ , |
.Ql _ |
all subsequent lines are included as part of the cell until |
or |
.Cm T} |
.Ql = , |
is specified as its own data cell. |
a horizontal line across the whole table is inserted |
It may then be followed by a tab |
without consuming a layout row. |
.Pq or as designated by Cm tab |
|
or an end-of-line to terminate the row. |
|
.Sh COMPATIBILITY |
|
This section documents compatibility between mandoc and other |
|
.Nm |
|
implementations, at this time limited to GNU tbl. |
|
.Pp |
.Pp |
.Bl -dash -compact |
In place of any data cell, a text block can be used. |
.It |
It starts with |
In GNU tbl, comments and macros are disallowed prior to the data block |
.Ic \&T{ |
of a table. |
at the end of a physical input line. |
|
Input line breaks inside the text block |
|
neither end the text block nor its data cell. |
|
It only ends if |
|
.Ic \&T} |
|
occurs at the beginning of a physical input line and is followed |
|
by an end-of-cell indicator. |
|
If the |
|
.Ic \&T} |
|
is followed by the end of the physical input line, the text block, |
|
the data cell, and the data line ends at this point. |
|
If the |
|
.Ic \&T} |
|
is followed by the |
|
.Cm tab |
|
character, only the text block and the data cell end, |
|
but the data line continues with the data cell following the |
|
.Cm tab |
|
character. |
|
If |
|
.Ic \&T} |
|
is followed by any other character, it does not end the text block, |
|
which instead continues to the following physical input line. |
|
.Sh EXAMPLES |
|
String justification and font selection: |
|
.Bd -literal -offset indent |
|
\&.TS |
|
rb c lb |
|
r ci l. |
|
r center l |
|
ri ce le |
|
right c left |
|
\&.TE |
|
.Ed |
|
.Bd -filled -offset indent |
|
.TS |
|
rb c lb |
|
r ci l. |
|
r center l |
|
ri ce le |
|
right c left |
|
.TE |
|
.Ed |
|
.Pp |
|
Some ports in |
|
.Ox 6.1 |
|
to show number alignment and line drawing: |
|
.Bd -literal -offset indent |
|
\&.TS |
|
box tab(:); |
|
r| l |
|
r n. |
|
software:version |
|
_ |
|
AFL:2.39b |
|
Mutt:1.8.0 |
|
Ruby:1.8.7.374 |
|
TeX Live:2015 |
|
\&.TE |
|
.Ed |
|
.Bd -filled -offset indent |
|
.TS |
|
box tab(:); |
|
r| l |
|
r n. |
|
software:version |
|
_ |
|
AFL:2.39b |
|
Mutt:1.8.0 |
|
Ruby:1.8.7.374 |
|
TeX Live:2015 |
|
.TE |
|
.Ed |
|
.sp 2v |
|
Spans and skipping width calculations: |
|
.Bd -literal -offset indent |
|
\&.TS |
|
box tab(:); |
|
lz s | rt |
|
lt| cb| \(ha |
|
\(ha | rz s. |
|
left:r |
|
l:center: |
|
:right |
|
\&.TE |
|
.Ed |
|
.Bd -filled -offset indent |
|
.TS |
|
box tab(:); |
|
lz s | rt |
|
lt| cb| ^ |
|
^ | rz s. |
|
left:r |
|
l:center: |
|
:right |
|
.TE |
|
.Ed |
|
.sp 2v |
|
Text blocks, specifying spacings and specifying and equalizing |
|
column widths, putting lines into individual cells, and overriding |
|
.Cm allbox : |
|
.Bd -literal -offset indent |
|
\&.TS |
|
allbox tab(:); |
|
le le||7 lw10. |
|
The fourth line:_:line 1 |
|
of this column:=:line 2 |
|
determines:\_:line 3 |
|
the column width.:T{ |
|
This text is too wide to fit into a column of width 17. |
|
T}:line 4 |
|
T{ |
|
No break here. |
|
T}::line 5 |
|
\&.TE |
|
.Ed |
|
.Bd -filled -offset indent |
|
.TS |
|
allbox tab(:); |
|
le le||7 lw10. |
|
The fourth line:_:line 1 |
|
of this column:=:line 2 |
|
determines:\_:line 3 |
|
the column width.:T{ |
|
This text is too wide to fit into a column of width 17. |
|
T}:line 4 |
|
T{ |
|
No break here. |
|
T}::line 5 |
|
.TE |
|
.Ed |
|
.sp 2v |
|
These examples were constructed to demonstrate many |
|
.Nm |
|
features in a compact way. |
|
In real manual pages, keep tables as simple as possible. |
|
They usually look better, are less fragile, and are more portable. |
|
.Sh COMPATIBILITY |
The |
The |
.Xr mandoc 1 |
.Xr mandoc 1 |
implementation allows them. |
implementation of |
.El |
.Nm |
|
doesn't support |
|
.Xr mdoc 7 |
|
and |
|
.Xr man 7 |
|
macros and |
|
.Xr eqn 7 |
|
equations inside tables. |
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr mandoc 1 , |
.Xr mandoc 1 , |
.Xr man 7 , |
.Xr man 7 , |
Line 358 The GNU reimplementation of tbl, part of the groff pac |
|
Line 427 The GNU reimplementation of tbl, part of the groff pac |
|
in 1990 by James Clark. |
in 1990 by James Clark. |
A standalone tbl implementation was written by Kristaps Dzonsons in |
A standalone tbl implementation was written by Kristaps Dzonsons in |
2010. |
2010. |
This formed the basis of the implementation that is part of the |
This formed the basis of the implementation that first appeared in |
|
.Ox 4.9 |
|
as a part of the |
.Xr mandoc 1 |
.Xr mandoc 1 |
utility. |
utility. |
.Sh AUTHORS |
.Sh AUTHORS |
This |
This |
.Nm |
.Nm |
reference was written by |
reference was written by |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv |
|
and |
|
.An Ingo Schwarze Aq Mt schwarze@openbsd.org . |
|
.Sh BUGS |
|
In |
|
.Fl T |
|
.Cm utf8 |
|
output mode, heavy lines are drawn instead of double lines. |
|
This cannot be improved because the Unicode standard only provides |
|
an incomplete set of box drawing characters with double lines, |
|
whereas it provides a full set of box drawing characters |
|
with heavy lines. |
|
It is unlikely this can be improved in the future because the box |
|
drawing characters are already marked in Unicode as characters |
|
intended only for backward compatibility with legacy systems, |
|
and their use is not encouraged. |
|
So it seems unlikely that the missing ones might get added in the future. |