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 cells contains only the single character ‘_’ or ‘=’, a single
151     or double horizontal line is drawn across the cell, joining its neigh‐
152     bours.  If a data cells contains only the two character sequence ‘\_’ or
153     ‘\=’, a single or double horizontal line is drawn inside the cell, not
154     joining its neighbours.  If a data line contains nothing but the single
155     character ‘_’ or ‘=’, a horizontal line across the whole table is
156     inserted without consuming a layout row.
157
158     In place of any data cell, a text block can be used.  It starts with T{
159     at the end of a physical input line.  Input line breaks inside the text
160     block neither end the text block nor its data cell.  It only ends if T}
161     occurs at the beginning of a physical input line and is followed by an
162     end-of-cell indicator.  If the T} is followed by the end of the physical
163     input line, the text block, the data cell, and the data line ends at this
164     point.  If the T} is followed by the tab character, only the text block
165     and the data cell end, but the data line continues with the data cell
166     following the tab character.  If T} is followed by any other character,
167     it does not end the text block, which instead continues to the following
168     physical input line.
169

EXAMPLES

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

COMPATIBILITY

262     The mandoc(1) implementation of tbl doesn't support mdoc(7) and man(7)
263     macros and eqn(7) equations inside tables.
264

SEE ALSO

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

HISTORY

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

AUTHORS

279     This tbl reference was written by Kristaps Dzonsons <kristaps@bsd.lv> and
280     Ingo Schwarze <schwarze@openbsd.org>.
281
282BSD                              June 20, 2019                             BSD
Impressum