1.\" $Id: tbl.7,v 1.26 2015/01/29 00:33:57 schwarze Exp $ 2.\" 3.\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2014, 2015 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: January 29 2015 $ 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 mandoc_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 centered 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 mandoc_roff 5 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 mandoc_roff 5 , 104.Xr mdoc 5 , 105and 106.Xr man 5 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 5 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 5 . 135.Ss Options 136The first line of a table may contain options separated by spaces, tabs, 137or commas and terminated by a semicolon. 138If the first line does not have a terminating semicolon, it is assumed 139that no options are specified and instead a 140.Sx Layout 141is processed. 142Some options require arguments enclosed by parentheses. 143The following case-insensitive options are available: 144.Bl -tag -width Ds 145.It Cm allbox 146Draw a single-line box around each table cell. 147Currently treated as a synonym for 148.Cm box . 149.It Cm box 150Draw a single-line box around the table. 151For GNU compatibility, this may also be invoked with 152.Cm frame . 153.It Cm center 154Center the table instead of left-adjusting it. 155For GNU compatibility, this may also be invoked with 156.Cm centre . 157.It Cm decimalpoint 158Use the single-character argument as the decimal point with the 159.Cm n 160layout key. 161This is a GNU extension. 162.It Cm delim 163Use the two characters of the argument as 164.Xr eqn 5 165delimiters. 166Currently unsupported. 167.It Cm doublebox 168Draw a double-line box around the table. 169For GNU compatibility, this may also be invoked with 170.Cm doubleframe . 171.It Cm expand 172Increase the width of the table to the current line length. 173Currently ignored. 174.It Cm linesize 175Draw lines with the point size given by the unsigned integer argument. 176Currently ignored. 177.It Cm nokeep 178Allow page breaks within the table. 179This is a GNU extension and currently ignored. 180.It Cm nospaces 181Ignore leading and trailing spaces in data cells. 182This is a GNU extension and currently ignored. 183.It Cm nowarn 184Suppress warnings about tables exceeding the current line length. 185This is a GNU extension and currently ignored. 186.It Cm tab 187Use the single-character argument as a delimiter between data cells. 188By default, the tab character is used. 189.El 190.Ss Layout 191The table layout follows 192.Sx Options 193or a 194.Sq \&T& 195macro invocation. 196Layout specifies how data rows are displayed on output. 197Each layout line corresponds to a line of data; the last layout line 198applies to all remaining data lines. 199Layout lines may also be separated by a comma. 200Each layout cell consists of one of the following case-insensitive keys: 201.Bl -tag -width 2n 202.It Cm c 203Center a literal string within its column. 204.It Cm r 205Right-justify a literal string within its column. 206.It Cm l 207Left-justify a literal string within its column. 208.It Cm n 209Justify a number around its last decimal point. 210If the decimal point is not found on the number, it's assumed to trail 211the number. 212.It Cm s 213Horizontally span columns from the last 214.No non- Ns Cm s 215data cell. 216It is an error if spanning columns follow a 217.Cm \- 218or 219.Cm \(ba 220cell, or come first. 221This option is not supported by 222.Xr mandoc 1 . 223.It Cm a 224Left-justify a literal string and pad with one space. 225.It Cm ^ 226Vertically span rows from the last 227.No non- Ns Cm ^ 228data cell. 229It is an error to invoke a vertical span on the first layout row. 230Unlike a horizontal spanner, you must specify an empty cell (if it not 231empty, the data is discarded) in the corresponding data cell. 232.It Cm \- 233Replace the data cell (its contents will be lost) with a single 234horizontal line. 235This may also be invoked with 236.Cm _ . 237.It Cm = 238Replace the data cell (its contents will be lost) with a double 239horizontal line. 240.It Cm \(ba 241Emit a vertical bar instead of data. 242.It Cm \(ba\(ba 243Emit a double-vertical bar instead of data. 244.El 245.Pp 246Keys may be followed by a set of modifiers. 247A modifier is either a modifier key or a natural number for specifying 248the minimum width of a column. 249The following case-insensitive modifier keys are available: 250.Bl -tag -width 2n 251.It Cm b 252Use a bold font for the contents of this column. 253.It Cm d 254Move cell content down to the last cell of a vertical span. 255Currently ignored. 256.It Cm e 257Make this column wider to match the maximum width 258of any other column also having the 259.Cm e 260modifier. 261.It Cm f 262The next character selects the font to use for this column. 263See the 264.Xr mandoc_roff 5 265manual for supported one-character font names. 266.It Cm i 267Use an italic font for the contents of this column. 268.It Cm m 269Specify a cell start macro. 270This is a GNU extension and currently unsupported. 271.It Cm p 272Set the point size to the following unsigned argument, 273or change it by the following signed argument. 274Currently ignored. 275.It Cm v 276Set the vertical line spacing to the following unsigned argument, 277or change it by the following signed argument. 278Currently ignored. 279.It Cm t 280Do not vertically center cell content in the vertical span, 281leave it at the top. 282Currently ignored. 283.It Cm u 284Move cell content up by half a table line. 285Currently ignored. 286.It Cm w 287Specify minimum column width. 288Currently ignored. 289.It Cm x 290After determining the width of all other columns, distribute the 291rest of the line length among all columns having the 292.Cm x 293modifier. 294.It Cm z 295Do not use this cell for determining the width of this column. 296.El 297.Pp 298For example, the following layout specifies a center-justified column of 299minimum width 10, followed by vertical bar, followed by a left-justified 300column of minimum width 10, another vertical bar, then a column using 301bold font justified about the decimal point in numbers: 302.Pp 303.Dl c10 | l10 | nfB 304.Ss Data 305The data section follows the last layout row. 306By default, cells in a data section are delimited by a tab. 307This behaviour may be changed with the 308.Cm tab 309option. 310If 311.Cm _ 312or 313.Cm = 314is specified, a single or double line, respectively, is drawn across the 315data field. 316If 317.Cm \e- 318or 319.Cm \e= 320is specified, a line is drawn within the data field (i.e. terminating 321within the cell and not draw to the border). 322If the last cell of a line is 323.Cm T{ , 324all subsequent lines are included as part of the cell until 325.Cm T} 326is specified as its own data cell. 327It may then be followed by a tab 328.Pq or as designated by Cm tab 329or an end-of-line to terminate the row. 330.Sh COMPATIBILITY 331The 332.Xr mandoc 1 333implementation of 334.Nm 335doesn't support 336.Xr mdoc 5 337and 338.Xr man 5 339macros and 340.Xr eqn 5 341equations inside tables. 342.Sh SEE ALSO 343.Xr mandoc 1 , 344.Xr man 5 , 345.Xr mandoc_char 5 , 346.Xr mandoc_roff 5 , 347.Xr mdoc 5 348.Rs 349.%A M. E. Lesk 350.%T Tbl\(emA Program to Format Tables 351.%D June 11, 1976 352.Re 353.Sh HISTORY 354The tbl utility, a preprocessor for troff, was originally written by M. 355E. Lesk at Bell Labs in 1975. 356The GNU reimplementation of tbl, part of the groff package, was released 357in 1990 by James Clark. 358A standalone tbl implementation was written by Kristaps Dzonsons in 3592010. 360This formed the basis of the implementation that is part of the 361.Xr mandoc 1 362utility. 363.Sh AUTHORS 364This 365.Nm 366reference was written by 367.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 368