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