| blob | 4ecc354c4ea357a467bd0fe883d256b09e847fb3 |
1 .\" $Id: tbl.7,v 1.37 2021/09/18 12:34:27 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2014,2015,2017,2018,2019 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: September 18 2021 $
19 .Dt TBL 7
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 formats tables.
28 It is used within
29 .Xr mdoc 7
30 and
31 .Xr man 7
32 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 Each table is started with a
40 .Xr roff 7
41 .Ic \&TS
42 macro, consist of at most one line of
43 .Sx Options ,
44 one or more
45 .Sx Layout
46 lines, one or more
47 .Sx Data
48 lines, and ends with a
49 .Ic \&TE
50 macro.
51 All input must be 7-bit ASCII.
52 .Ss Options
53 If the first input line of a table ends with a semicolon, it contains
54 case-insensitive options separated by spaces, tabs, or commas.
55 Otherwise, it is interpreted as the first
56 .Sx Layout
57 line.
58 .Pp
59 The following options are available.
60 Some of them require arguments enclosed in parentheses:
61 .Bl -tag -width Ds
62 .It Cm allbox
63 Draw a single-line box around each table cell.
64 .It Cm box
65 Draw a single-line box around the table.
66 For GNU compatibility, this may also be invoked with
67 .Cm frame .
68 .It Cm center
69 Center the table instead of left-adjusting it.
70 For GNU compatibility, this may also be invoked with
71 .Cm centre .
72 .It Cm decimalpoint
73 Use the single-character argument as the decimal point with the
74 .Cm n
75 layout key.
76 This is a GNU extension.
77 .It Cm delim
78 Use the two characters of the argument as
79 .Xr eqn 7
80 delimiters.
81 Currently unsupported.
82 .It Cm doublebox
83 Draw a double-line box around the table.
84 For GNU compatibility, this may also be invoked with
85 .Cm doubleframe .
86 .It Cm expand
87 Increase the width of the table to the current line length.
88 Currently ignored.
89 .It Cm linesize
90 Draw lines with the point size given by the unsigned integer argument.
91 Currently ignored.
92 .It Cm nokeep
93 Allow page breaks within the table.
94 This is a GNU extension and currently ignored.
95 .It Cm nospaces
96 Ignore leading and trailing spaces in data cells.
97 This is a GNU extension.
98 .It Cm nowarn
99 Suppress warnings about tables exceeding the current line length.
100 This is a GNU extension and currently ignored.
101 .It Cm tab
102 Use the single-character argument as a delimiter between data cells.
103 By default, the horizontal tabulator character is used.
104 .El
105 .Ss Layout
106 The table layout follows an
107 .Sx Options
108 line or a
109 .Xr roff 7
110 .Ic \&TS
111 or
112 .Ic \&T&
113 macro.
114 Each layout line specifies how one line of
115 .Sx Data
116 is formatted.
117 The last layout line ends with a full stop.
118 It also applies to all remaining data lines.
119 Multiple layout lines can be joined by commas on a single physical
120 input line.
121 .Pp
122 Each layout line consists of one or more layout cell specifications,
123 optionally separated by whitespace.
124 The following case-insensitive key characters start a new cell
125 specification:
126 .Bl -tag -width 2n
127 .It Cm c
128 Center the string in this cell.
129 .It Cm r
130 Right-justify the string in this cell.
131 .It Cm l
132 Left-justify the string in this cell.
133 .It Cm n
134 Justify a number around its last decimal point.
135 If no decimal point is found in the number,
136 it is assumed to trail the number.
137 .It Cm s
138 Horizontally span columns from the last
139 .Pf non- Cm s
140 layout cell.
141 It is an error if a column span follows a
142 .Cm _
143 or
144 .Cm =
145 cell, or comes first on a layout line.
146 The combined cell as a whole consumes only one cell
147 of the corresponding data line.
148 .It Cm a
149 Left-justify a string and pad with one space.
150 .It Cm \(ha
151 Vertically span rows from the last
152 .Pf non- Cm \(ha
153 layout cell.
154 It is an error to invoke a vertical span on the first layout line.
155 Unlike a horizontal span, a vertical span consumes a data cell
156 and discards the content.
157 .It Cm _
158 Draw a single horizontal line in this cell.
159 This consumes a data cell and discards the content.
160 It may also be invoked with
161 .Cm \- .
162 .It Cm =
163 Draw a double horizontal line in this cell.
164 This consumes a data cell and discards the content.
165 .El
166 .Pp
167 Each cell key may be followed by zero or more of the following
168 case-insensitive modifiers:
169 .Bl -tag -width 2n
170 .It Cm b
171 Use a bold font for the contents of this cell.
172 .It Cm d
173 Move content down to the last row of this vertical span.
174 Currently ignored.
175 .It Cm e
176 Make this column wider to match the maximum width
177 of any other column also having the
178 .Cm e
179 modifier.
180 .It Cm f
181 The next one or two characters select the font to use for this cell.
182 One-character font names must be followed by a blank or period.
183 See the
184 .Xr roff 7
185 manual for supported font names.
186 .It Cm i
187 Use an italic font for the contents of this cell.
188 .It Cm m
189 Specify a cell start macro.
190 This is a GNU extension and currently unsupported.
191 .It Cm p
192 Set the point size to the following unsigned argument,
193 or change it by the following signed argument.
194 Currently ignored.
195 .It Cm v
196 Set the vertical line spacing to the following unsigned argument,
197 or change it by the following signed argument.
198 Currently ignored.
199 .It Cm t
200 Do not vertically center content in this vertical span,
201 leave it in the top row.
202 Currently ignored.
203 .It Cm u
204 Move cell content up by half a table row.
205 Currently ignored.
206 .It Cm w
207 Specify a minimum column width.
208 .It Cm x
209 After determining the width of all other columns, distribute the
210 rest of the line length among all columns having the
211 .Cm x
212 modifier.
213 .It Cm z
214 Do not use this cell for determining the width of this column.
215 .It Cm \&|
216 Draw a single vertical line to the right of this cell.
217 .It Cm ||
218 Draw a double vertical line to the right of this cell.
219 .El
220 .Pp
221 If a modifier consists of decimal digits,
222 it specifies a minimum spacing in units of
223 .Cm n
224 between this column and the next column to the right.
225 The default is 3.
226 If there is a vertical line, it is drawn inside the spacing.
227 .Ss Data
228 The data section follows the last
229 .Sx Layout
230 line.
231 Each data line consists of one or more data cells, delimited by
232 .Cm tab
233 characters.
234 .Pp
235 If a data cell contains only the two bytes
236 .Ql \e\(ha ,
237 the cell above spans to this row, as if the layout specification
238 of this cell were
239 .Cm \(ha .
240 .Pp
241 If a data cell contains only the single character
242 .Ql _
243 or
244 .Ql = ,
245 a single or double horizontal line is drawn across the cell,
246 joining its neighbours.
247 If a data cell contains only the two character sequence
248 .Ql \e_
249 or
250 .Ql \e= ,
251 a single or double horizontal line is drawn inside the cell,
252 not joining its neighbours.
253 If a data line contains nothing but the single character
254 .Ql _
255 or
256 .Ql = ,
257 a horizontal line across the whole table is inserted
258 without consuming a layout row.
259 .Pp
260 In place of any data cell, a text block can be used.
261 It starts with
262 .Ic \&T{
263 at the end of a physical input line.
264 Input line breaks inside the text block
265 neither end the text block nor its data cell.
266 It only ends if
267 .Ic \&T}
268 occurs at the beginning of a physical input line and is followed
269 by an end-of-cell indicator.
270 If the
271 .Ic \&T}
272 is followed by the end of the physical input line, the text block,
273 the data cell, and the data line ends at this point.
274 If the
275 .Ic \&T}
276 is followed by the
277 .Cm tab
278 character, only the text block and the data cell end,
279 but the data line continues with the data cell following the
280 .Cm tab
281 character.
282 If
283 .Ic \&T}
284 is followed by any other character, it does not end the text block,
285 which instead continues to the following physical input line.
286 .Sh EXAMPLES
287 String justification and font selection:
288 .Bd -literal -offset indent
289 \&.TS
290 rb c lb
291 r ci l.
292 r center l
293 ri ce le
294 right c left
295 \&.TE
296 .Ed
297 .Bd -filled -offset indent
298 .TS
299 rb c lb
300 r ci l.
301 r center l
302 ri ce le
303 right c left
304 .TE
305 .Ed
306 .Pp
307 Some ports in
308 .Ox 6.1
309 to show number alignment and line drawing:
310 .Bd -literal -offset indent
311 \&.TS
312 box tab(:);
313 r| l
314 r n.
315 software:version
316 _
317 AFL:2.39b
318 Mutt:1.8.0
319 Ruby:1.8.7.374
320 TeX Live:2015
321 \&.TE
322 .Ed
323 .Bd -filled -offset indent
324 .TS
325 box tab(:);
326 r| l
327 r n.
328 software:version
329 _
330 AFL:2.39b
331 Mutt:1.8.0
332 Ruby:1.8.7.374
333 TeX Live:2015
334 .TE
335 .Ed
336 .sp 2v
337 Spans and skipping width calculations:
338 .Bd -literal -offset indent
339 \&.TS
340 box tab(:);
341 lz s | rt
342 lt| cb| \(ha
343 \(ha | rz s.
344 left:r
345 l:center:
346 :right
347 \&.TE
348 .Ed
349 .Bd -filled -offset indent
350 .TS
351 box tab(:);
352 lz s | rt
353 lt| cb| ^
354 ^ | rz s.
355 left:r
356 l:center:
357 :right
358 .TE
359 .Ed
360 .sp 2v
361 Text blocks, specifying spacings and specifying and equalizing
362 column widths, putting lines into individual cells, and overriding
363 .Cm allbox :
364 .Bd -literal -offset indent
365 \&.TS
366 allbox tab(:);
367 le le||7 lw10.
368 The fourth line:_:line 1
369 of this column:=:line 2
370 determines:\_:line 3
371 the column width.:T{
372 This text is too wide to fit into a column of width 17.
373 T}:line 4
374 T{
375 No break here.
376 T}::line 5
377 \&.TE
378 .Ed
379 .Bd -filled -offset indent
380 .TS
381 allbox tab(:);
382 le le||7 lw10.
383 The fourth line:_:line 1
384 of this column:=:line 2
385 determines:\_:line 3
386 the column width.:T{
387 This text is too wide to fit into a column of width 17.
388 T}:line 4
389 T{
390 No break here.
391 T}::line 5
392 .TE
393 .Ed
394 .sp 2v
395 These examples were constructed to demonstrate many
396 .Nm
397 features in a compact way.
398 In real manual pages, keep tables as simple as possible.
399 They usually look better, are less fragile, and are more portable.
400 .Sh COMPATIBILITY
401 The
402 .Xr mandoc 1
403 implementation of
404 .Nm
405 doesn't support
406 .Xr mdoc 7
407 and
408 .Xr man 7
409 macros and
410 .Xr eqn 7
411 equations inside tables.
412 .Sh SEE ALSO
413 .Xr mandoc 1 ,
414 .Xr man 7 ,
415 .Xr mandoc_char 7 ,
416 .Xr mdoc 7 ,
417 .Xr roff 7
418 .Rs
419 .%A M. E. Lesk
420 .%T Tbl \(em A Program to Format Tables
421 .%D June 11, 1976
422 .Re
423 .Sh HISTORY
424 The tbl utility, a preprocessor for troff, was originally written by M.
425 E. Lesk at Bell Labs in 1975.
426 The GNU reimplementation of tbl, part of the groff package, was released
427 in 1990 by James Clark.
428 A standalone tbl implementation was written by Kristaps Dzonsons in
429 2010.
430 This formed the basis of the implementation that first appeared in
431 .Ox 4.9
432 as a part of the
433 .Xr mandoc 1
434 utility.
435 .Sh AUTHORS
436 This
437 .Nm
438 reference was written by
439 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
440 and
441 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
442 .Sh BUGS
443 In
444 .Fl T
445 .Cm utf8
446 output mode, heavy lines are drawn instead of double lines.
447 This cannot be improved because the Unicode standard only provides
448 an incomplete set of box drawing characters with double lines,
449 whereas it provides a full set of box drawing characters
450 with heavy lines.
451 It is unlikely this can be improved in the future because the box
452 drawing characters are already marked in Unicode as characters
453 intended only for backward compatibility with legacy systems,
454 and their use is not encouraged.
455 So it seems unlikely that the missing ones might get added in the future.