1.\" $Vendor-Id: tbl.7,v 1.4 2011/01/07 14:59:52 kristaps Exp $ 2.\" 3.\" Copyright (c) 2010 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 January 7, 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 centered 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. 183This option is not supported by 184.Xr mandoc 1 . 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 Ds 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 decimal point. 209If the decimal point is not found on the number, it's assumed to trail 210the number. 211.It Cm s 212This option is not supported by 213.Xr mandoc 1 . 214.It Cm a 215This option is not supported by 216.Xr mandoc 1 . 217.It Cm ^ 218This option is not supported by 219.Xr mandoc 1 . 220.It Cm \- 221Replace the data cell (its contents will be lost) with a single 222horizontal line. 223This may also be invoked with 224.Cm _ . 225.It Cm = 226Replace the data cell (its contents will be lost) with a double 227horizontal line. 228.It Cm \(ba 229Emit a vertical bar instead of data. 230.It Cm \(ba\(ba 231Emit a double-vertical bar instead of data. 232.El 233.Pp 234For example, the following layout specifies a centre-justified column of 235minimum width 10, followed by vertical bar, followed by a left-justified 236column of minimum width 10, another vertical bar, then a column 237justified about the decimal point in numbers: 238.Pp 239.Dl c10 | l10 | n 240.Pp 241Keys may be followed by a set of modifiers. 242A modifier is either a modifier key or a natural number for specifying 243spacing. 244The following case-insensitive modifier keys are available: 245.Cm z , 246.Cm u , 247.Cm e , 248.Cm t , 249.Cm d , 250.Cm f , 251.Cm b , 252.Cm i , 253.Cm b , 254and 255.Cm i . 256All of these are ignored by 257.Xr mandoc 1 . 258.Ss Data 259The data section follows the last layout row. 260By default, cells in a data section are delimited by a tab. 261This behaviour may be changed with the 262.Cm tab 263option. 264If 265.Cm _ 266or 267.Cm = 268is specified, a single or double line, respectively, is drawn across the 269data field. 270If 271.Cm \e- 272or 273.Cm \e= 274is specified, a line is drawn within the data field (i.e. terminating 275within the cell and not draw to the border). 276If the last cell of a line is 277.Cm T{ , 278all subsequent lines are included as part of the cell until 279.Cm T} 280is specified as its own data cell. 281It may then be followed by a tab 282.Pq or as designated by Cm tab 283or an end-of-line to terminate the row. 284.Sh COMPATIBILITY 285This section documents compatibility between mandoc and other 286.Nm 287implementations, at this time limited to GNU tbl. 288.Pp 289.Bl -dash -compact 290.It 291In GNU tbl, comments and macros are disallowed prior to the data block 292of a table. 293The 294.Xr mandoc 1 295implementation allows them. 296.El 297.Sh SEE ALSO 298.Xr mandoc 1 , 299.Xr man 7 , 300.Xr mandoc_char 7 , 301.Xr mdoc 7 , 302.Xr roff 7 303.Rs 304.%A M. E. Lesk 305.%T Tbl\(emA Program to Format Tables 306.%D June 11, 1976 307.Re 308.Sh HISTORY 309The tbl utility, a preprocessor for troff, was originally written by M. 310E. Lesk at Bell Labs in 1975. 311The GNU reimplementation of tbl, part of the groff package, was released 312in 1990 by James Clark. 313A standalone tbl implementation was written by Kristaps Dzonsons in 3142010. 315This formed the basis of the implementation that is part of the 316.Xr mandoc 1 317utility. 318.Sh AUTHORS 319This partial 320.Nm 321reference was written by 322.An Kristaps Dzonsons Aq kristaps@bsd.lv . 323