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