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