1TBL(7)               BSD Miscellaneous Information Manual               TBL(7)
2

NAME

4     tbl — tbl language reference for mandoc
5

DESCRIPTION

7     The tbl language formats tables.  It is used within mdoc(7) and man(7)
8     pages.  This manual describes the subset of the tbl language accepted by
9     the mandoc(1) utility.
10
11     Each table is started with a roff(7) TS macro, consist of at most one
12     line of Options, one or more Layout lines, one or more Data lines, and
13     ends with a TE macro.  All input must be 7-bit ASCII.
14
15   Options
16     If the first input line of a table ends with a semicolon, it contains
17     case-insensitive options separated by spaces, tabs, or commas.  Other‐
18     wise, it is interpreted as the first Layout line.
19
20     The following options are available.  Some of them require arguments
21     enclosed in parentheses:
22
23     allbox  Draw a single-line box around each table cell.
24
25     box     Draw a single-line box around the table.  For GNU compatibility,
26             this may also be invoked with frame.
27
28     center  Center the table instead of left-adjusting it.  For GNU compati‐
29             bility, this may also be invoked with centre.
30
31     decimalpoint
32             Use the single-character argument as the decimal point with the n
33             layout key.  This is a GNU extension.
34
35     delim   Use the two characters of the argument as eqn(7) delimiters.
36             Currently unsupported.
37
38     doublebox
39             Draw a double-line box around the table.  For GNU compatibility,
40             this may also be invoked with doubleframe.
41
42     expand  Increase the width of the table to the current line length.  Cur‐
43             rently ignored.
44
45     linesize
46             Draw lines with the point size given by the unsigned integer
47             argument.  Currently ignored.
48
49     nokeep  Allow page breaks within the table.  This is a GNU extension and
50             currently ignored.
51
52     nospaces
53             Ignore leading and trailing spaces in data cells.  This is a GNU
54             extension and currently ignored.
55
56     nowarn  Suppress warnings about tables exceeding the current line length.
57             This is a GNU extension and currently ignored.
58
59     tab     Use the single-character argument as a delimiter between data
60             cells.  By default, the horizontal tabulator character is used.
61
62   Layout
63     The table layout follows an Options line or a roff(7) TS or T& macro.
64     Each layout line specifies how one line of Data is formatted.  The last
65     layout line ends with a full stop.  It also applies to all remaining data
66     lines.  Multiple layout lines can be joined by commas on a single physi‐
67     cal input line.
68
69     Each layout line consists of one or more layout cell specifications,
70     optionally separated by whitespace.  The following case-insensitive key
71     characters start a new cell specification:
72
73     c   Center the string in this cell.
74
75     r   Right-justify the string in this cell.
76
77     l   Left-justify the string in this cell.
78
79     n   Justify a number around its last decimal point.  If no decimal point
80         is found in the number, it is assumed to trail the number.
81
82     s   Horizontally span columns from the last non-s layout cell.  It is an
83         error if a column span follows a _ or = cell, or comes first on a
84         layout line.  The combined cell as a whole consumes only one cell of
85         the corresponding data line.
86
87     a   Left-justify a string and pad with one space.
88
89     ^   Vertically span rows from the last non-^ layout cell.  It is an error
90         to invoke a vertical span on the first layout line.  Unlike a hori‐
91         zontal span, a vertical span consumes a data cell and discards the
92         content.
93
94     _   Draw a single horizontal line in this cell.  This consumes a data
95         cell and discards the content.  It may also be invoked with -.
96
97     =   Draw a double horizontal line in this cell.  This consumes a data
98         cell and discards the content.
99
100     Each cell key may be followed by zero or more of the following case-
101     insensitive modifiers:
102
103     b   Use a bold font for the contents of this cell.
104
105     d   Move content down to the last row of this vertical span.  Currently
106         ignored.
107
108     e   Make this column wider to match the maximum width of any other column
109         also having the e modifier.
110
111     f   The next character selects the font to use for this cell.  See the
112         roff(7) manual for supported one-character font names.
113
114     i   Use an italic font for the contents of this cell.
115
116     m   Specify a cell start macro.  This is a GNU extension and currently
117         unsupported.
118
119     p   Set the point size to the following unsigned argument, or change it
120         by the following signed argument.  Currently ignored.
121
122     v   Set the vertical line spacing to the following unsigned argument, or
123         change it by the following signed argument.  Currently ignored.
124
125     t   Do not vertically center content in this vertical span, leave it in
126         the top row.  Currently ignored.
127
128     u   Move cell content up by half a table row.  Currently ignored.
129
130     w   Specify a minimum column width.
131
132     x   After determining the width of all other columns, distribute the rest
133         of the line length among all columns having the x modifier.
134
135     z   Do not use this cell for determining the width of this column.
136
137     |   Draw a single vertical line to the right of this cell.
138
139     ||  Draw a double vertical line to the right of this cell.
140
141     If a modifier consists of decimal digits, it specifies a minimum spacing
142     in units of n between this column and the next column to the right.  The
143     default is 3.  If there is a vertical line, it is drawn inside the spac‐
144     ing.
145
146   Data
147     The data section follows the last Layout line.  Each data line consists
148     of one or more data cells, delimited by tab characters.
149
150     If a data cell contains only the two bytes ‘\^’, the cell above spans to
151     this row, as if the layout specification of this cell were ^.
152
153     If a data cell contains only the single character ‘_’ or ‘=’, a single or
154     double horizontal line is drawn across the cell, joining its neighbours.
155     If a data cell contains only the two character sequence ‘\_’ or ‘\=’, a
156     single or double horizontal line is drawn inside the cell, not joining
157     its neighbours.  If a data line contains nothing but the single character
158     ‘_’ or ‘=’, a horizontal line across the whole table is inserted without
159     consuming a layout row.
160
161     In place of any data cell, a text block can be used.  It starts with T{
162     at the end of a physical input line.  Input line breaks inside the text
163     block neither end the text block nor its data cell.  It only ends if T}
164     occurs at the beginning of a physical input line and is followed by an
165     end-of-cell indicator.  If the T} is followed by the end of the physical
166     input line, the text block, the data cell, and the data line ends at this
167     point.  If the T} is followed by the tab character, only the text block
168     and the data cell end, but the data line continues with the data cell
169     following the tab character.  If T} is followed by any other character,
170     it does not end the text block, which instead continues to the following
171     physical input line.
172

EXAMPLES

174     String justification and font selection:
175
176           .TS
177           rb c  lb
178           r  ci l.
179           r       center  l
180           ri      ce      le
181           right   c       left
182           .TE
183
184               r   center   l
185              ri     ce     le
186           right     c      left
187
188     Some ports in OpenBSD 6.1 to show number alignment and line drawing:
189
190           .TS
191           box tab(:);
192           r| l
193           r  n.
194           software:version
195           _
196           AFL:2.39b
197           Mutt:1.8.0
198           Ruby:1.8.7.374
199           TeX Live:2015
200           .TE
201
202           ┌─────────┬───────────┐
203           │software │ version   │
204           ├─────────┴───────────┤
205           │     AFL       2.39b │
206           │    Mutt     1.8.0   │
207           │    Ruby   1.8.7.374 │
208           │TeX Live    2015     │
209           └─────────────────────┘
210
211     Spans and skipping width calculations:
212
213           .TS
214           box tab(:);
215           lz  s | rt
216           lt| cb| ^
217           ^ | rz  s.
218           left:r
219           l:center:
220           :right
221           .TE
222
223           ┌───────────┬───┐
224           │le│ft       │ r │
225           │l │ center │   │
226           │  │      right │
227           └──┴────────────┘
228
229     Text blocks, specifying spacings and specifying and equalizing column
230     widths, putting lines into individual cells, and overriding allbox:
231
232           .TS
233           allbox tab(:);
234           le le||7 lw10.
235           The fourth line:_:line 1
236           of this column:=:line 2
237           determines:_:line 3
238           the column width.:T{
239           This text is too wide to fit into a column of width 17.
240           T}:line 4
241           T{
242           No break here.
243           T}::line 5
244           .TE
245
246           ┌────────────────────┬───────────────────────┬┬─────────────┐
247           │The fourth line     ├───────────────────────┤│  line 1     │
248           ├────────────────────┼───────────────────────┼┼─────────────┤
249           │of this column      ├───────────────────────┤│  line 2     │
250           ├────────────────────┼───────────────────────┼┼─────────────┤
251           │determines          │ ────────────────────  ││  line 3     │
252           ├────────────────────┼───────────────────────┼┼─────────────┤
253           │the column width.   │ This  text  is  too   ││  line 4     │
254           │                    │ wide to fit into  a   ││             │
255           │                    │ column of width 17.   ││             │
256           ├────────────────────┼───────────────────────┼┼─────────────┤
257           │No break here.      │                       ││  line 5     │
258           └────────────────────┴───────────────────────┴┴─────────────┘
259
260     These examples were constructed to demonstrate many tbl features in a
261     compact way.  In real manual pages, keep tables as simple as possible.
262     They usually look better, are less fragile, and are more portable.
263

COMPATIBILITY

265     The mandoc(1) implementation of tbl doesn't support mdoc(7) and man(7)
266     macros and eqn(7) equations inside tables.
267

SEE ALSO

269     mandoc(1), man(7), mandoc_char(7), mdoc(7), roff(7)
270
271     M. E. Lesk, Tbl—A Program to Format Tables, June 11, 1976.
272

HISTORY

274     The tbl utility, a preprocessor for troff, was originally written by M.
275     E. Lesk at Bell Labs in 1975.  The GNU reimplementation of tbl, part of
276     the groff package, was released in 1990 by James Clark.  A standalone tbl
277     implementation was written by Kristaps Dzonsons in 2010.  This formed the
278     basis of the implementation that first appeared in OpenBSD 4.9 as a part
279     of the mandoc(1) utility.
280

AUTHORS

282     This tbl reference was written by Kristaps Dzonsons <kristaps@bsd.lv> and
283     Ingo Schwarze <schwarze@openbsd.org>.
284

BUGS

286     In -T utf8 output mode, heavy lines are drawn instead of double lines.
287     This cannot be improved because the Unicode standard only provides an
288     incomplete set of box drawing characters with double lines, whereas it
289     provides a full set of box drawing characters with heavy lines.  It is
290     unlikely this can be improved in the future because the box drawing char‐
291     acters are already marked in Unicode as characters intended only for
292     backward compatibility with legacy systems, and their use is not encour‐
293     aged.  So it seems unlikely that the missing ones might get added in the
294     future.
295
296BSD                              May 10, 2020                              BSD
Impressum