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