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 25The 26.Nm tbl 27language is a table-formatting language. 28It is used within 29.Xr mdoc 5 30and 31.Xr man 5 32.Ux 33manual pages. 34This manual describes the subset of the 35.Nm 36language accepted by the 37.Xr mandoc 1 38utility. 39.Pp 40Tables within 41.Xr mdoc 5 42or 43.Xr man 5 44are enclosed by the 45.Sq TS 46and 47.Sq TE 48macro tags, whose precise syntax is documented in 49.Xr roff 5 . 50Tables consist of a series of options on a single line, followed by the 51table layout, followed by data. 52.Pp 53For example, the following creates a boxed table with digits centred in 54the cells. 55.Bd -literal -offset indent 56\&.TS 57tab(:) box; 58c5 c5 c5. 591:2:3 604:5:6 61\&.TE 62.Ed 63.Pp 64When formatted, the following output is produced: 65.Bd -filled -offset indent -compact 66.TS 67tab(:) box; 68c5 c5 c5. 691:2:3 704:5:6 71.TE 72.Ed 73.Pp 74The 75.Nm 76implementation in 77.Xr mandoc 1 78is 79.Ud 80.Sh TABLE STRUCTURE 81Tables are enclosed by the 82.Sq TS 83and 84.Sq TE 85.Xr roff 5 86macros. 87A table consists of an optional single line of table 88.Sx Options 89terminated by a semicolon, followed by one or more lines of 90.Sx Layout 91specifications terminated by a period, then 92.Sx Data . 93All input must be 7-bit ASCII. 94Example: 95.Bd -literal -offset indent 96\&.TS 97box tab(:); 98c | c 99| c | c. 1001:2 1013:4 102\&.TE 103.Ed 104.Pp 105Table data is 106.Em pre-processed , 107that is, data rows are parsed then inserted into the underlying stream 108of input data. 109This allows data rows to be interspersed by arbitrary 110.Xr roff 5 , 111.Xr mdoc 5 , 112and 113.Xr man 5 114macros such as 115.Bd -literal -offset indent 116\&.TS 117tab(:); 118c c c. 1191:2:3 120\&.Ao 1213:2:1 122\&.Ac 123\&.TE 124.Ed 125.Pp 126in the case of 127.Xr mdoc 5 128or 129.Bd -literal -offset indent 130\&.TS 131tab(:); 132c c c. 133\&.ds ab 2 1341:\e*(ab:3 135\&.I 1363:2:1 137\&.TE 138.Ed 139.Pp 140in the case of 141.Xr man 5 . 142.Ss Options 143The first line of a table consists of space-separated option keys and 144modifiers terminated by a semicolon. 145If the first line does not have a terminating semicolon, it is assumed 146that no options are specified and instead a 147.Sx Layout 148is processed. 149Some options accept arguments enclosed by parenthesis. 150The following case-insensitive options are available: 151.Bl -tag -width Ds 152.It Cm center 153This option is not supported by 154.Xr mandoc 1 . 155This may also be invoked with 156.Cm centre . 157.It Cm delim 158Accepts a two-character argument. 159This option is not supported by 160.Xr mandoc 1 . 161.It Cm expand 162This option is not supported by 163.Xr mandoc 1 . 164.It Cm box 165Draw a single-line box around the table. 166This may also be invoked with 167.Cm frame . 168.It Cm doublebox 169Draw a double-line box around the table. 170This may also be invoked with 171.Cm doubleframe . 172.It Cm allbox 173This option is not supported by 174.Xr mandoc 1 . 175.It Cm tab 176Accepts a single-character argument. 177This character is used as a delimiter between data cells, which otherwise 178defaults to the tab character. 179.It Cm linesize 180Accepts a natural number (all digits). 181This option is not supported by 182.Xr mandoc 1 . 183.It Cm nokeep 184This option is not supported by 185.Xr mandoc 1 . 186.It Cm decimalpoint 187Accepts a single-character argument. 188This character will be used as the decimal point with the 189.Cm n 190layout key. 191.It Cm nospaces 192This option is not supported by 193.Xr mandoc 1 . 194.El 195.Ss Layout 196The table layout follows 197.Sx Options 198or a 199.Sq \&T& 200macro invocation. 201Layout specifies how data rows are displayed on output. 202Each layout line corresponds to a line of data; the last layout line 203applies to all remaining data lines. 204Layout lines may also be separated by a comma. 205Each layout cell consists of one of the following case-insensitive keys: 206.Bl -tag -width Ds 207.It Cm c 208Centre a literal string within its column. 209.It Cm r 210Right-justify a literal string within its column. 211.It Cm l 212Left-justify a literal string within its column. 213.It Cm n 214Justify a number around its last decimal point. 215If the decimal point is not found on the number, it's assumed to trail 216the number. 217.It Cm s 218Horizontally span columns from the last 219.No non- Ns Cm s 220data cell. 221It is an error if spanning columns follow a 222.Cm \- 223or 224.Cm \(ba 225cell, or come first. 226This option is not supported by 227.Xr mandoc 1 . 228.It Cm a 229Left-justify a literal string and pad with one space. 230.It Cm ^ 231Vertically span rows from the last 232.No non- Ns Cm ^ 233data cell. 234It is an error to invoke a vertical span on the first layout row. 235Unlike a horizontal spanner, you must specify an empty cell (if it not 236empty, the data is discarded) in the corresponding data cell. 237.It Cm \- 238Replace the data cell (its contents will be lost) with a single 239horizontal line. 240This may also be invoked with 241.Cm _ . 242.It Cm = 243Replace the data cell (its contents will be lost) with a double 244horizontal line. 245.It Cm \(ba 246Emit a vertical bar instead of data. 247.It Cm \(ba\(ba 248Emit a double-vertical bar instead of data. 249.El 250.Pp 251Keys may be followed by a set of modifiers. 252A modifier is either a modifier key or a natural number for specifying 253the minimum width of a column. 254The 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 , 263and 264.Cm f 265.Po 266followed by 267.Cm b , 268.Cm i , 269.Cm r , 270.Cm 3 , 271.Cm 2 , 272or 273.Cm 1 274.Pc . 275All of these are ignored by 276.Xr mandoc 1 . 277.Pp 278For example, the following layout specifies a centre-justified column of 279minimum width 10, followed by vertical bar, followed by a left-justified 280column of minimum width 10, another vertical bar, then a column 281justified about the decimal point in numbers: 282.Pp 283.Dl c10 | l10 | n 284.Ss Data 285The data section follows the last layout row. 286By default, cells in a data section are delimited by a tab. 287This behaviour may be changed with the 288.Cm tab 289option. 290If 291.Cm _ 292or 293.Cm = 294is specified, a single or double line, respectively, is drawn across the 295data field. 296If 297.Cm \e- 298or 299.Cm \e= 300is specified, a line is drawn within the data field (i.e. terminating 301within the cell and not draw to the border). 302If the last cell of a line is 303.Cm T{ , 304all subsequent lines are included as part of the cell until 305.Cm T} 306is specified as its own data cell. 307It may then be followed by a tab 308.Pq or as designated by Cm tab 309or an end-of-line to terminate the row. 310.Sh COMPATIBILITY 311This section documents compatibility between mandoc and other 312.Nm 313implementations, at this time limited to GNU tbl. 314.Pp 315.Bl -dash -compact 316.It 317In GNU tbl, comments and macros are disallowed prior to the data block 318of a table. 319The 320.Xr mandoc 1 321implementation 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 335The tbl utility, a preprocessor for troff, was originally written by M. 336E. Lesk at Bell Labs in 1975. 337The GNU reimplementation of tbl, part of the groff package, was released 338in 1990 by James Clark. 339A standalone tbl implementation was written by Kristaps Dzonsons in 3402010. 341This formed the basis of the implementation that is part of the 342.Xr mandoc 1 343utility. 344.Sh AUTHORS 345This 346.Nm 347reference was written by 348.An Kristaps Dzonsons , 349.Mt kristaps@bsd.lv . 350