1.\" $Id: tbl.7,v 1.16 2011/09/03 00:29:21 kristaps 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 3 2011 $ 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.Pp 73The 74.Nm 75implementation in 76.Xr mandoc 1 77is 78.Ud 79.Sh TABLE STRUCTURE 80Tables are enclosed by the 81.Sq TS 82and 83.Sq TE 84.Xr roff 7 85macros. 86A table consists of an optional single line of table 87.Sx Options 88terminated by a semicolon, followed by one or more lines of 89.Sx Layout 90specifications terminated by a period, then 91.Sx Data . 92All input must be 7-bit ASCII. 93Example: 94.Bd -literal -offset indent 95\&.TS 96box tab(:); 97c | c 98| c | c. 991:2 1003:4 101\&.TE 102.Ed 103.Pp 104Table data is 105.Em pre-processed , 106that is, data rows are parsed then inserted into the underlying stream 107of input data. 108This allows data rows to be interspersed by arbitrary 109.Xr roff 7 , 110.Xr mdoc 7 , 111and 112.Xr man 7 113macros such as 114.Bd -literal -offset indent 115\&.TS 116tab(:); 117c c c. 1181:2:3 119\&.Ao 1203:2:1 121\&.Ac 122\&.TE 123.Ed 124.Pp 125in the case of 126.Xr mdoc 7 127or 128.Bd -literal -offset indent 129\&.TS 130tab(:); 131c c c. 132\&.ds ab 2 1331:\e*(ab:3 134\&.I 1353:2:1 136\&.TE 137.Ed 138.Pp 139in the case of 140.Xr man 7 . 141.Ss Options 142The first line of a table consists of space-separated option keys and 143modifiers terminated by a semicolon. 144If the first line does not have a terminating semicolon, it is assumed 145that no options are specified and instead a 146.Sx Layout 147is processed. 148Some options accept arguments enclosed by parenthesis. 149The following case-insensitive options are available: 150.Bl -tag -width Ds 151.It Cm center 152This option is not supported by 153.Xr mandoc 1 . 154This may also be invoked with 155.Cm centre . 156.It Cm delim 157Accepts a two-character argument. 158This option is not supported by 159.Xr mandoc 1 . 160.It Cm expand 161This option is not supported by 162.Xr mandoc 1 . 163.It Cm box 164Draw a single-line box around the table. 165This may also be invoked with 166.Cm frame . 167.It Cm doublebox 168Draw a double-line box around the table. 169This may also be invoked with 170.Cm doubleframe . 171.It Cm allbox 172This option is not supported by 173.Xr mandoc 1 . 174.It Cm tab 175Accepts a single-character argument. 176This character is used as a delimiter between data cells, which otherwise 177defaults to the tab character. 178.It Cm linesize 179Accepts a natural number (all digits). 180This option is not supported by 181.Xr mandoc 1 . 182.It Cm nokeep 183This option is not supported by 184.Xr mandoc 1 . 185.It Cm decimalpoint 186Accepts a single-character argument. 187This character will be used as the decimal point with the 188.Cm n 189layout key. 190.It Cm nospaces 191This option is not supported by 192.Xr mandoc 1 . 193.El 194.Ss Layout 195The table layout follows 196.Sx Options 197or a 198.Sq \&T& 199macro invocation. 200Layout specifies how data rows are displayed on output. 201Each layout line corresponds to a line of data; the last layout line 202applies to all remaining data lines. 203Layout lines may also be separated by a comma. 204Each layout cell consists of one of the following case-insensitive keys: 205.Bl -tag -width Ds 206.It Cm c 207Centre a literal string within its column. 208.It Cm r 209Right-justify a literal string within its column. 210.It Cm l 211Left-justify a literal string within its column. 212.It Cm n 213Justify a number around its last decimal point. 214If the decimal point is not found on the number, it's assumed to trail 215the number. 216.It Cm s 217Horizontally span columns from the last 218.No non- Ns Cm s 219data cell. 220It is an error if spanning columns follow a 221.Cm \- 222or 223.Cm \(ba 224cell, or come first. 225This option is not supported by 226.Xr mandoc 1 . 227.It Cm a 228Left-justify a literal string and pad with one space. 229.It Cm ^ 230Vertically span rows from the last 231.No non- Ns Cm ^ 232data cell. 233It is an error to invoke a vertical span on the first layout row. 234Unlike a horizontal spanner, you must specify an empty cell (if it not 235empty, the data is discarded) in the corresponding data cell. 236.It Cm \- 237Replace the data cell (its contents will be lost) with a single 238horizontal line. 239This may also be invoked with 240.Cm _ . 241.It Cm = 242Replace the data cell (its contents will be lost) with a double 243horizontal line. 244.It Cm \(ba 245Emit a vertical bar instead of data. 246.It Cm \(ba\(ba 247Emit a double-vertical bar instead of data. 248.El 249.Pp 250Keys may be followed by a set of modifiers. 251A modifier is either a modifier key or a natural number for specifying 252the minimum width of a column. 253The following case-insensitive modifier keys are available: 254.Cm z , 255.Cm u , 256.Cm e , 257.Cm t , 258.Cm d , 259.Cm b , 260.Cm i , 261.Cm r , 262and 263.Cm f 264.Po 265followed by 266.Cm b , 267.Cm i , 268.Cm r , 269.Cm 3 , 270.Cm 2 , 271or 272.Cm 1 273.Pc . 274All of these are ignored by 275.Xr mandoc 1 . 276.Pp 277For example, the following layout specifies a centre-justified column of 278minimum width 10, followed by vertical bar, followed by a left-justified 279column of minimum width 10, another vertical bar, then a column 280justified about the decimal point in numbers: 281.Pp 282.Dl c10 | l10 | n 283.Ss Data 284The data section follows the last layout row. 285By default, cells in a data section are delimited by a tab. 286This behaviour may be changed with the 287.Cm tab 288option. 289If 290.Cm _ 291or 292.Cm = 293is specified, a single or double line, respectively, is drawn across the 294data field. 295If 296.Cm \e- 297or 298.Cm \e= 299is specified, a line is drawn within the data field (i.e. terminating 300within the cell and not draw to the border). 301If the last cell of a line is 302.Cm T{ , 303all subsequent lines are included as part of the cell until 304.Cm T} 305is specified as its own data cell. 306It may then be followed by a tab 307.Pq or as designated by Cm tab 308or an end-of-line to terminate the row. 309.Sh COMPATIBILITY 310This section documents compatibility between mandoc and other 311.Nm 312implementations, at this time limited to GNU tbl. 313.Pp 314.Bl -dash -compact 315.It 316In GNU tbl, comments and macros are disallowed prior to the data block 317of a table. 318The 319.Xr mandoc 1 320implementation allows them. 321.El 322.Sh SEE ALSO 323.Xr mandoc 1 , 324.Xr man 7 , 325.Xr mandoc_char 7 , 326.Xr mdoc 7 , 327.Xr roff 7 328.Rs 329.%A M. E. Lesk 330.%T Tbl\(emA Program to Format Tables 331.%D June 11, 1976 332.Re 333.Sh HISTORY 334The tbl utility, a preprocessor for troff, was originally written by M. 335E. Lesk at Bell Labs in 1975. 336The GNU reimplementation of tbl, part of the groff package, was released 337in 1990 by James Clark. 338A standalone tbl implementation was written by Kristaps Dzonsons in 3392010. 340This formed the basis of the implementation that is part of the 341.Xr mandoc 1 342utility. 343.Sh AUTHORS 344This 345.Nm 346reference was written by 347.An Kristaps Dzonsons , 348.Mt kristaps@bsd.lv . 349