| blob | fe142208e8e6e08a4d2df3a1324bb108983327fe |
1 .\"
2 .\" Permission to use, copy, modify, and distribute this software for any
3 .\" purpose with or without fee is hereby granted, provided that the above
4 .\" copyright notice and this permission notice appear in all copies.
5 .\"
6 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
7 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
8 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
9 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
10 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
11 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
12 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
13 .\"
14 .\"
15 .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
16 .\" Copyright 2012 Nexenta Systems, Inc. All rights reserved.
17 .\"
18 .Dd Sep 3, 2011
19 .Dt TBL 5
20 .Os
21 .Sh NAME
22 .Nm tbl
23 .Nd tbl language reference for mandoc
24 .Sh DESCRIPTION
25 The
26 .Nm tbl
27 language is a table-formatting language.
28 It is used within
29 .Xr mdoc 5
30 and
31 .Xr man 5
32 .Ux
33 manual pages.
34 This manual describes the subset of the
35 .Nm
36 language accepted by the
37 .Xr mandoc 1
38 utility.
39 .Pp
40 Tables within
41 .Xr mdoc 5
42 or
43 .Xr man 5
44 are enclosed by the
45 .Sq TS
46 and
47 .Sq TE
48 macro tags, whose precise syntax is documented in
49 .Xr roff 5 .
50 Tables consist of a series of options on a single line, followed by the
51 table layout, followed by data.
52 .Pp
53 For example, the following creates a boxed table with digits centred in
54 the cells.
55 .Bd -literal -offset indent
56 \&.TS
57 tab(:) box;
58 c5 c5 c5.
59 1:2:3
60 4:5:6
61 \&.TE
62 .Ed
63 .Pp
64 When formatted, the following output is produced:
65 .Bd -filled -offset indent -compact
66 .TS
67 tab(:) box;
68 c5 c5 c5.
69 1:2:3
70 4:5:6
71 .TE
72 .Ed
73 .Pp
74 The
75 .Nm
76 implementation in
77 .Xr mandoc 1
78 is
79 .Ud
80 .Sh TABLE STRUCTURE
81 Tables are enclosed by the
82 .Sq TS
83 and
84 .Sq TE
85 .Xr roff 5
86 macros.
87 A table consists of an optional single line of table
88 .Sx Options
89 terminated by a semicolon, followed by one or more lines of
90 .Sx Layout
91 specifications terminated by a period, then
92 .Sx Data .
93 All input must be 7-bit ASCII.
94 Example:
95 .Bd -literal -offset indent
96 \&.TS
97 box tab(:);
98 c | c
99 | c | c.
100 1:2
101 3:4
102 \&.TE
103 .Ed
104 .Pp
105 Table data is
106 .Em pre-processed ,
107 that is, data rows are parsed then inserted into the underlying stream
108 of input data.
109 This allows data rows to be interspersed by arbitrary
110 .Xr roff 5 ,
111 .Xr mdoc 5 ,
112 and
113 .Xr man 5
114 macros such as
115 .Bd -literal -offset indent
116 \&.TS
117 tab(:);
118 c c c.
119 1:2:3
120 \&.Ao
121 3:2:1
122 \&.Ac
123 \&.TE
124 .Ed
125 .Pp
126 in the case of
127 .Xr mdoc 5
128 or
129 .Bd -literal -offset indent
130 \&.TS
131 tab(:);
132 c c c.
133 \&.ds ab 2
134 1:\e*(ab:3
135 \&.I
136 3:2:1
137 \&.TE
138 .Ed
139 .Pp
140 in the case of
141 .Xr man 5 .
142 .Ss Options
143 The first line of a table consists of space-separated option keys and
144 modifiers terminated by a semicolon.
145 If the first line does not have a terminating semicolon, it is assumed
146 that no options are specified and instead a
147 .Sx Layout
148 is processed.
149 Some options accept arguments enclosed by parenthesis.
150 The following case-insensitive options are available:
151 .Bl -tag -width Ds
152 .It Cm center
153 This option is not supported by
154 .Xr mandoc 1 .
155 This may also be invoked with
156 .Cm centre .
157 .It Cm delim
158 Accepts a two-character argument.
159 This option is not supported by
160 .Xr mandoc 1 .
161 .It Cm expand
162 This option is not supported by
163 .Xr mandoc 1 .
164 .It Cm box
165 Draw a single-line box around the table.
166 This may also be invoked with
167 .Cm frame .
168 .It Cm doublebox
169 Draw a double-line box around the table.
170 This may also be invoked with
171 .Cm doubleframe .
172 .It Cm allbox
173 This option is not supported by
174 .Xr mandoc 1 .
175 .It Cm tab
176 Accepts a single-character argument.
177 This character is used as a delimiter between data cells, which otherwise
178 defaults to the tab character.
179 .It Cm linesize
180 Accepts a natural number (all digits).
181 This option is not supported by
182 .Xr mandoc 1 .
183 .It Cm nokeep
184 This option is not supported by
185 .Xr mandoc 1 .
186 .It Cm decimalpoint
187 Accepts a single-character argument.
188 This character will be used as the decimal point with the
189 .Cm n
190 layout key.
191 .It Cm nospaces
192 This option is not supported by
193 .Xr mandoc 1 .
194 .El
195 .Ss Layout
196 The table layout follows
197 .Sx Options
198 or a
199 .Sq \&T&
200 macro invocation.
201 Layout specifies how data rows are displayed on output.
202 Each layout line corresponds to a line of data; the last layout line
203 applies to all remaining data lines.
204 Layout lines may also be separated by a comma.
205 Each layout cell consists of one of the following case-insensitive keys:
206 .Bl -tag -width Ds
207 .It Cm c
208 Centre a literal string within its column.
209 .It Cm r
210 Right-justify a literal string within its column.
211 .It Cm l
212 Left-justify a literal string within its column.
213 .It Cm n
214 Justify a number around its last decimal point.
215 If the decimal point is not found on the number, it's assumed to trail
216 the number.
217 .It Cm s
218 Horizontally span columns from the last
219 .No non- Ns Cm s
220 data cell.
221 It is an error if spanning columns follow a
222 .Cm \-
223 or
224 .Cm \(ba
225 cell, or come first.
226 This option is not supported by
227 .Xr mandoc 1 .
228 .It Cm a
229 Left-justify a literal string and pad with one space.
230 .It Cm ^
231 Vertically span rows from the last
232 .No non- Ns Cm ^
233 data cell.
234 It is an error to invoke a vertical span on the first layout row.
235 Unlike a horizontal spanner, you must specify an empty cell (if it not
236 empty, the data is discarded) in the corresponding data cell.
237 .It Cm \-
238 Replace the data cell (its contents will be lost) with a single
239 horizontal line.
240 This may also be invoked with
241 .Cm _ .
242 .It Cm =
243 Replace the data cell (its contents will be lost) with a double
244 horizontal line.
245 .It Cm \(ba
246 Emit a vertical bar instead of data.
247 .It Cm \(ba\(ba
248 Emit a double-vertical bar instead of data.
249 .El
250 .Pp
251 Keys may be followed by a set of modifiers.
252 A modifier is either a modifier key or a natural number for specifying
253 the minimum width of a column.
254 The following case-insensitive modifier keys are available:
255 .Cm z ,
256 .Cm u ,
257 .Cm e ,
258 .Cm t ,
259 .Cm d ,
260 .Cm b ,
261 .Cm i ,
262 .Cm r ,
263 and
264 .Cm f
265 .Po
266 followed by
267 .Cm b ,
268 .Cm i ,
269 .Cm r ,
270 .Cm 3 ,
271 .Cm 2 ,
272 or
273 .Cm 1
274 .Pc .
275 All of these are ignored by
276 .Xr mandoc 1 .
277 .Pp
278 For example, the following layout specifies a centre-justified column of
279 minimum width 10, followed by vertical bar, followed by a left-justified
280 column of minimum width 10, another vertical bar, then a column
281 justified about the decimal point in numbers:
282 .Pp
283 .Dl c10 | l10 | n
284 .Ss Data
285 The data section follows the last layout row.
286 By default, cells in a data section are delimited by a tab.
287 This behaviour may be changed with the
288 .Cm tab
289 option.
290 If
291 .Cm _
292 or
293 .Cm =
294 is specified, a single or double line, respectively, is drawn across the
295 data field.
296 If
297 .Cm \e-
298 or
299 .Cm \e=
300 is specified, a line is drawn within the data field (i.e. terminating
301 within the cell and not draw to the border).
302 If the last cell of a line is
303 .Cm T{ ,
304 all subsequent lines are included as part of the cell until
305 .Cm T}
306 is specified as its own data cell.
307 It may then be followed by a tab
308 .Pq or as designated by Cm tab
309 or an end-of-line to terminate the row.
310 .Sh COMPATIBILITY
311 This section documents compatibility between mandoc and other
312 .Nm
313 implementations, at this time limited to GNU tbl.
314 .Pp
315 .Bl -dash -compact
316 .It
317 In GNU tbl, comments and macros are disallowed prior to the data block
318 of a table.
319 The
320 .Xr mandoc 1
321 implementation allows them.
322 .El
323 .Sh SEE ALSO
324 .Xr mandoc 1 ,
325 .Xr man 5 ,
326 .Xr mandoc_char 5 ,
327 .Xr mdoc 5 ,
328 .Xr roff 5
329 .Rs
330 .%A M. E. Lesk
331 .%T Tbl\(emA Program to Format Tables
332 .%D June 11, 1976
333 .Re
334 .Sh HISTORY
335 The tbl utility, a preprocessor for troff, was originally written by M.
336 E. Lesk at Bell Labs in 1975.
337 The GNU reimplementation of tbl, part of the groff package, was released
338 in 1990 by James Clark.
339 A standalone tbl implementation was written by Kristaps Dzonsons in
340 2010.
341 This formed the basis of the implementation that is part of the
342 .Xr mandoc 1
343 utility.
344 .Sh AUTHORS
345 This
346 .Nm
347 reference was written by
348 .An Kristaps Dzonsons ,
349 .Mt kristaps@bsd.lv .