| blob | d0238e41547ee1cd9321700413a213de65aefef2 |
1 .\" $Id: tbl.7,v 1.26 2015/01/29 00:33:57 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
5 .\"
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
9 .\"
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 .\"
18 .Dd $Mdocdate: January 29 2015 $
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 mandoc_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 centered 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 .Sh TABLE STRUCTURE
74 Tables are enclosed by the
75 .Sq TS
76 and
77 .Sq TE
78 .Xr mandoc_roff 5
79 macros.
80 A table consists of an optional single line of table
81 .Sx Options
82 terminated by a semicolon, followed by one or more lines of
83 .Sx Layout
84 specifications terminated by a period, then
85 .Sx Data .
86 All input must be 7-bit ASCII.
87 Example:
88 .Bd -literal -offset indent
89 \&.TS
90 box tab(:);
91 c | c
92 | c | c.
93 1:2
94 3:4
95 \&.TE
96 .Ed
97 .Pp
98 Table data is
99 .Em pre-processed ,
100 that is, data rows are parsed then inserted into the underlying stream
101 of input data.
102 This allows data rows to be interspersed by arbitrary
103 .Xr mandoc_roff 5 ,
104 .Xr mdoc 5 ,
105 and
106 .Xr man 5
107 macros such as
108 .Bd -literal -offset indent
109 \&.TS
110 tab(:);
111 c c c.
112 1:2:3
113 \&.Ao
114 3:2:1
115 \&.Ac
116 \&.TE
117 .Ed
118 .Pp
119 in the case of
120 .Xr mdoc 5
121 or
122 .Bd -literal -offset indent
123 \&.TS
124 tab(:);
125 c c c.
126 \&.ds ab 2
127 1:\e*(ab:3
128 \&.I
129 3:2:1
130 \&.TE
131 .Ed
132 .Pp
133 in the case of
134 .Xr man 5 .
135 .Ss Options
136 The first line of a table may contain options separated by spaces, tabs,
137 or commas and terminated by a semicolon.
138 If the first line does not have a terminating semicolon, it is assumed
139 that no options are specified and instead a
140 .Sx Layout
141 is processed.
142 Some options require arguments enclosed by parentheses.
143 The following case-insensitive options are available:
144 .Bl -tag -width Ds
145 .It Cm allbox
146 Draw a single-line box around each table cell.
147 Currently treated as a synonym for
148 .Cm box .
149 .It Cm box
150 Draw a single-line box around the table.
151 For GNU compatibility, this may also be invoked with
152 .Cm frame .
153 .It Cm center
154 Center the table instead of left-adjusting it.
155 For GNU compatibility, this may also be invoked with
156 .Cm centre .
157 .It Cm decimalpoint
158 Use the single-character argument as the decimal point with the
159 .Cm n
160 layout key.
161 This is a GNU extension.
162 .It Cm delim
163 Use the two characters of the argument as
164 .Xr eqn 5
165 delimiters.
166 Currently unsupported.
167 .It Cm doublebox
168 Draw a double-line box around the table.
169 For GNU compatibility, this may also be invoked with
170 .Cm doubleframe .
171 .It Cm expand
172 Increase the width of the table to the current line length.
173 Currently ignored.
174 .It Cm linesize
175 Draw lines with the point size given by the unsigned integer argument.
176 Currently ignored.
177 .It Cm nokeep
178 Allow page breaks within the table.
179 This is a GNU extension and currently ignored.
180 .It Cm nospaces
181 Ignore leading and trailing spaces in data cells.
182 This is a GNU extension and currently ignored.
183 .It Cm nowarn
184 Suppress warnings about tables exceeding the current line length.
185 This is a GNU extension and currently ignored.
186 .It Cm tab
187 Use the single-character argument as a delimiter between data cells.
188 By default, the tab character is used.
189 .El
190 .Ss Layout
191 The table layout follows
192 .Sx Options
193 or a
194 .Sq \&T&
195 macro invocation.
196 Layout specifies how data rows are displayed on output.
197 Each layout line corresponds to a line of data; the last layout line
198 applies to all remaining data lines.
199 Layout lines may also be separated by a comma.
200 Each layout cell consists of one of the following case-insensitive keys:
201 .Bl -tag -width 2n
202 .It Cm c
203 Center a literal string within its column.
204 .It Cm r
205 Right-justify a literal string within its column.
206 .It Cm l
207 Left-justify a literal string within its column.
208 .It Cm n
209 Justify a number around its last decimal point.
210 If the decimal point is not found on the number, it's assumed to trail
211 the number.
212 .It Cm s
213 Horizontally span columns from the last
214 .No non- Ns Cm s
215 data cell.
216 It is an error if spanning columns follow a
217 .Cm \-
218 or
219 .Cm \(ba
220 cell, or come first.
221 This option is not supported by
222 .Xr mandoc 1 .
223 .It Cm a
224 Left-justify a literal string and pad with one space.
225 .It Cm ^
226 Vertically span rows from the last
227 .No non- Ns Cm ^
228 data cell.
229 It is an error to invoke a vertical span on the first layout row.
230 Unlike a horizontal spanner, you must specify an empty cell (if it not
231 empty, the data is discarded) in the corresponding data cell.
232 .It Cm \-
233 Replace the data cell (its contents will be lost) with a single
234 horizontal line.
235 This may also be invoked with
236 .Cm _ .
237 .It Cm =
238 Replace the data cell (its contents will be lost) with a double
239 horizontal line.
240 .It Cm \(ba
241 Emit a vertical bar instead of data.
242 .It Cm \(ba\(ba
243 Emit a double-vertical bar instead of data.
244 .El
245 .Pp
246 Keys may be followed by a set of modifiers.
247 A modifier is either a modifier key or a natural number for specifying
248 the minimum width of a column.
249 The following case-insensitive modifier keys are available:
250 .Bl -tag -width 2n
251 .It Cm b
252 Use a bold font for the contents of this column.
253 .It Cm d
254 Move cell content down to the last cell of a vertical span.
255 Currently ignored.
256 .It Cm e
257 Make this column wider to match the maximum width
258 of any other column also having the
259 .Cm e
260 modifier.
261 .It Cm f
262 The next character selects the font to use for this column.
263 See the
264 .Xr mandoc_roff 5
265 manual for supported one-character font names.
266 .It Cm i
267 Use an italic font for the contents of this column.
268 .It Cm m
269 Specify a cell start macro.
270 This is a GNU extension and currently unsupported.
271 .It Cm p
272 Set the point size to the following unsigned argument,
273 or change it by the following signed argument.
274 Currently ignored.
275 .It Cm v
276 Set the vertical line spacing to the following unsigned argument,
277 or change it by the following signed argument.
278 Currently ignored.
279 .It Cm t
280 Do not vertically center cell content in the vertical span,
281 leave it at the top.
282 Currently ignored.
283 .It Cm u
284 Move cell content up by half a table line.
285 Currently ignored.
286 .It Cm w
287 Specify minimum column width.
288 Currently ignored.
289 .It Cm x
290 After determining the width of all other columns, distribute the
291 rest of the line length among all columns having the
292 .Cm x
293 modifier.
294 .It Cm z
295 Do not use this cell for determining the width of this column.
296 .El
297 .Pp
298 For example, the following layout specifies a center-justified column of
299 minimum width 10, followed by vertical bar, followed by a left-justified
300 column of minimum width 10, another vertical bar, then a column using
301 bold font justified about the decimal point in numbers:
302 .Pp
303 .Dl c10 | l10 | nfB
304 .Ss Data
305 The data section follows the last layout row.
306 By default, cells in a data section are delimited by a tab.
307 This behaviour may be changed with the
308 .Cm tab
309 option.
310 If
311 .Cm _
312 or
313 .Cm =
314 is specified, a single or double line, respectively, is drawn across the
315 data field.
316 If
317 .Cm \e-
318 or
319 .Cm \e=
320 is specified, a line is drawn within the data field (i.e. terminating
321 within the cell and not draw to the border).
322 If the last cell of a line is
323 .Cm T{ ,
324 all subsequent lines are included as part of the cell until
325 .Cm T}
326 is specified as its own data cell.
327 It may then be followed by a tab
328 .Pq or as designated by Cm tab
329 or an end-of-line to terminate the row.
330 .Sh COMPATIBILITY
331 The
332 .Xr mandoc 1
333 implementation of
334 .Nm
335 doesn't support
336 .Xr mdoc 5
337 and
338 .Xr man 5
339 macros and
340 .Xr eqn 5
341 equations inside tables.
342 .Sh SEE ALSO
343 .Xr mandoc 1 ,
344 .Xr man 5 ,
345 .Xr mandoc_char 5 ,
346 .Xr mandoc_roff 5 ,
347 .Xr mdoc 5
348 .Rs
349 .%A M. E. Lesk
350 .%T Tbl\(emA Program to Format Tables
351 .%D June 11, 1976
352 .Re
353 .Sh HISTORY
354 The tbl utility, a preprocessor for troff, was originally written by M.
355 E. Lesk at Bell Labs in 1975.
356 The GNU reimplementation of tbl, part of the groff package, was released
357 in 1990 by James Clark.
358 A standalone tbl implementation was written by Kristaps Dzonsons in
359 2010.
360 This formed the basis of the implementation that is part of the
361 .Xr mandoc 1
362 utility.
363 .Sh AUTHORS
364 This
365 .Nm
366 reference was written by
367 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .