version 1.1, 2011/01/04 23:32:21 |
version 1.39, 2022/08/28 13:52:59 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
|
.\" 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 options terminated |
macro, consist of at most one line of |
by a semicolon, followed by one or more lines of layout specification |
.Sx Options , |
terminated by a period, then table data. |
one or more |
|
.Sx Layout |
|
lines, one or more |
|
.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: |
.Ss Options |
.Bd -literal -offset indent |
If the first input line of a table ends with a semicolon, it contains |
\&.TS |
case-insensitive options separated by spaces, tabs, or commas. |
box tab(:); |
Otherwise, it is interpreted as the first |
c | c |
.Sx Layout |
| c | c. |
line. |
1:2 |
|
3:4 |
|
\&.TE |
|
.Ed |
|
.Pp |
.Pp |
Table data is |
The following options are available. |
.Em pre-processed , |
Some of them require arguments enclosed in parentheses: |
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 Table Options |
|
The first line of a table consists of its options, which consists of |
|
space-separated keys and modifiers terminated by a semicolon. |
|
If the first line does not have a terminating semicolon, it is assumed |
|
that no options are specified and instead a layout is processed. |
|
Some options accept arguments enclosed by paranthesis. |
|
The following case-insensitive options are available: |
|
.Bl -tag -width Ds |
.Bl -tag -width Ds |
.It Cm center |
.It Cm allbox |
This option is not supported by |
Draw a single-line box around each table cell. |
.Xr mandoc 1 . |
|
This may also be invoked with |
|
.Cm centre . |
|
.It Cm delim |
|
Accepts a two-character argument. |
|
This option is not supported by |
|
.Xr mandoc 1 . |
|
.It Cm expand |
|
This option is not supported by |
|
.Xr mandoc 1 . |
|
.It Cm box |
.It Cm box |
Draw a single-line box around the table. |
Draw a single-line box around the table. |
This may also be invoked with |
For GNU compatibility, this may also be invoked with |
.Cm frame . |
.Cm frame . |
|
.It Cm center |
|
Center the table instead of left-adjusting it. |
|
For GNU compatibility, this may also be invoked with |
|
.Cm centre . |
|
.It Cm decimalpoint |
|
Use the single-character argument as the decimal point with the |
|
.Cm n |
|
layout key. |
|
This is a GNU extension. |
|
.It Cm delim |
|
Use the two characters of the argument as |
|
.Xr eqn 7 |
|
delimiters. |
|
Currently unsupported. |
.It Cm doublebox |
.It Cm doublebox |
Draw a double-line box around the table. |
Draw a double-line box around the table. |
This may also be invoked with |
For GNU compatibility, this may also be invoked with |
.Cm doubleframe . |
.Cm doubleframe . |
.It Cm allbox |
.It Cm expand |
This option is not supported by |
Increase the width of the table to the current line length. |
.Xr mandoc 1 . |
Currently ignored. |
.It Cm tab |
|
Accepts a single-character argument. |
|
This character is used a delimiter between data cells, which otherwise |
|
defaults to the tab character. |
|
.It Cm linesize |
.It Cm linesize |
Accepts a natural number (all digits). |
Draw lines with the point size given by the unsigned integer argument. |
This option is not supported by |
Currently ignored. |
.Xr mandoc 1 . |
|
.It Cm nokeep |
.It Cm nokeep |
This option is not supported by |
Allow page breaks within the table. |
.Xr mandoc 1 . |
This is a GNU extension and currently ignored. |
.It Cm decimalpoint |
|
Accepts a single-character argument. |
|
This character will be used as the decimal point with the |
|
.Cm n |
|
layout key. |
|
This option is not supported by |
|
.Xr mandoc 1 . |
|
.It Cm nospaces |
.It Cm nospaces |
This option is not supported by |
Ignore leading and trailing spaces in data cells. |
.Xr mandoc 1 . |
This is a GNU extension. |
|
.It Cm nowarn |
|
Suppress warnings about tables exceeding the current line length. |
|
This is a GNU extension and currently ignored. |
|
.It Cm tab |
|
Use the single-character argument as a delimiter between data cells. |
|
By default, the horizontal tabulator character is used. |
.El |
.El |
.Ss Table Layout |
.Ss Layout |
The table layout follows table options, except in the case of |
The table layout follows an |
.Sx \&T& , |
.Sx Options |
where it immediately procedes invocation. |
line or a |
Layout specifies how data rows are displayed on output. |
.Xr roff 7 |
Each layout line corresponds to a line of data; the last layout line |
.Ic \&TS |
applies to all remaining data lines. |
or |
Layout lines may also be separated by a comma. |
.Ic \&T& |
Each layout cell consists of one of the following case-insensitive keys: |
macro. |
.Bl -tag -width Ds |
Each layout line specifies how one line of |
|
.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 |
.It Cm c |
.It Cm c |
Centre 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 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 |
This option is not supported by |
Horizontally span columns from the last |
.Xr mandoc 1 . |
.Pf non- Cm s |
|
layout cell. |
|
It is an error if a column span follows a |
|
.Cm _ |
|
or |
|
.Cm = |
|
cell, or comes first on a layout line. |
|
The combined cell as a whole consumes only one cell |
|
of the corresponding data line. |
.It Cm a |
.It Cm a |
This option is not supported by |
Left-justify a string and pad with one space. |
.Xr mandoc 1 . |
.It Cm \(ha |
.It Cm ^ |
Vertically span rows from the last |
This option is not supported by |
.Pf non- Cm \(ha |
.Xr mandoc 1 . |
layout cell. |
.It Cm \- |
It is an error to invoke a vertical span on the first layout line. |
Replace the data cell (its contents will be lost) with a single |
Unlike a horizontal span, a vertical span consumes a data cell |
horizontal line. |
and discards the content. |
This may also be invoked with |
.It Cm _ |
.Cm _ . |
Draw a single horizontal line in this cell. |
|
This consumes a data cell and discards the content. |
|
It may also be invoked with |
|
.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 |
For example, following layout specifies a centre-justified column of |
Each cell key may be followed by zero or more of the following |
minimum width 10, followed by vertical bar, followed by a left-justified |
case-insensitive modifiers: |
column of minimum width 10, another vertical bar, then a column |
.Bl -tag -width 2n |
justified about the decimal point in numbers: |
.It Cm b |
|
Use a bold font for the contents of this cell. |
|
.It Cm d |
|
Move content down to the last row of this vertical span. |
|
Currently ignored. |
|
.It Cm e |
|
Make this column wider to match the maximum width |
|
of any other column also having the |
|
.Cm e |
|
modifier. |
|
.It Cm f |
|
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 |
|
.Xr roff 7 |
|
manual for supported font names. |
|
.It Cm i |
|
Use an italic font for the contents of this cell. |
|
.It Cm m |
|
Specify a cell start macro. |
|
This is a GNU extension and currently unsupported. |
|
.It Cm p |
|
Set the point size to the following unsigned argument, |
|
or change it by the following signed argument. |
|
Currently ignored. |
|
.It Cm v |
|
Set the vertical line spacing to the following unsigned argument, |
|
or change it by the following signed argument. |
|
Currently ignored. |
|
.It Cm t |
|
Do not vertically center content in this vertical span, |
|
leave it in the top row. |
|
Currently ignored. |
|
.It Cm u |
|
Move cell content up by half a table row. |
|
Currently ignored. |
|
.It Cm w |
|
Specify a minimum column width. |
|
.It Cm x |
|
After determining the width of all other columns, distribute the |
|
rest of the line length among all columns having the |
|
.Cm x |
|
modifier. |
|
.It Cm z |
|
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 |
.Pp |
.Pp |
.Dl c10 | l10 | n |
If a modifier consists of decimal digits, |
.Pp |
it specifies a minimum spacing in units of |
Keys may be followed by a set of modifiers. |
.Cm n |
A modifier is either a modifier key or a natural number for specifying |
between this column and the next column to the right. |
spacing. |
The default is 3. |
The following case-insensitive modifier keys are available: |
If there is a vertical line, it is drawn inside the spacing. |
.Cm z , |
.Ss Data |
.Cm u , |
The data section follows the last |
.Cm e , |
.Sx Layout |
.Cm t , |
line. |
.Cm d , |
Each data line consists of one or more data cells, delimited by |
.Cm f , |
|
.Cm b , |
|
.Cm i , |
|
.Cm b , |
|
and |
|
.Cm i . |
|
All of these are ignored by |
|
.Xr mandoc 1 . |
|
.Ss Table Data |
|
The data section follows the last layout row. |
|
By default, cells in a data section are delimited by a tab. |
|
This behaviour may be changed with the |
|
.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 on its own line. |
a horizontal line across the whole table is inserted |
.Sh COMPATIBILITY |
without consuming a layout row. |
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 |
|
.Pp |
|
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 |
|
.Pp |
|
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:\e_: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 |
|
.Pp |
|
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 mandoc_char 7 , |
|
.Xr roff 7 , |
|
.Xr man 7 , |
.Xr man 7 , |
.Xr mdoc 7 |
.Xr mandoc_char 7 , |
|
.Xr mdoc 7 , |
|
.Xr roff 7 |
.Rs |
.Rs |
.%A M. E. Lesk |
.%A M. E. Lesk |
.%T Tbl\(emA Program to Format Tables |
.%T Tbl \(em A Program to Format Tables |
.%D June 11, 1976 |
.%D June 11, 1976 |
.Re |
.Re |
.Sh HISTORY |
.Sh HISTORY |
Line 302 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 partial |
This |
.Nm |
.Nm |
reference was written by |
reference was written by |
.An Kristaps Dzonsons Aq 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. |