1 .\"
   2 .\" Permission to use, copy, modify, and distribute this software for any
   3 .\" purpose with or without fee is hereby granted, provided that the above
   4 .\" copyright notice and this permission notice appear in all copies.
   5 .\"
   6 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   7 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
   8 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
   9 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  10 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  11 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  12 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  13 .\"
  14 .\"
  15 .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  16 .\" Copyright 2012 Nexenta Systems, Inc. All rights reserved.
  17 .\"
  18 .Dd Sep 3, 2011
  19 .Dt TBL 5
  20 .Os
  21 .Sh NAME
  22 .Nm tbl
  23 .Nd tbl language reference for mandoc
  24 .Sh DESCRIPTION
  25 The
  26 .Nm tbl
  27 language is a table-formatting language.
  28 It is used within
  29 .Xr mdoc 5
  30 and
  31 .Xr man 5
  32 .Ux
  33 manual pages.
  34 This manual describes the subset of the
  35 .Nm
  36 language accepted by the
  37 .Xr mandoc 1
  38 utility.
  39 .Pp
  40 Tables within
  41 .Xr mdoc 5
  42 or
  43 .Xr man 5
  44 are enclosed by the
  45 .Sq TS
  46 and
  47 .Sq TE
  48 macro tags, whose precise syntax is documented in
  49 .Xr roff 5 .
  50 Tables consist of a series of options on a single line, followed by the
  51 table layout, followed by data.
  52 .Pp
  53 For example, the following creates a boxed table with digits centred in
  54 the cells.
  55 .Bd -literal -offset indent
  56 \&.TS
  57 tab(:) box;
  58 c5 c5 c5.
  59 1:2:3
  60 4:5:6
  61 \&.TE
  62 .Ed
  63 .Pp
  64 When formatted, the following output is produced:
  65 .Bd -filled -offset indent -compact
  66 .TS
  67 tab(:) box;
  68 c5 c5 c5.
  69 1:2:3
  70 4:5:6
  71 .TE
  72 .Ed
  73 .Pp
  74 The
  75 .Nm
  76 implementation in
  77 .Xr mandoc 1
  78 is
  79 .Ud
  80 .Sh TABLE STRUCTURE
  81 Tables are enclosed by the
  82 .Sq TS
  83 and
  84 .Sq TE
  85 .Xr roff 5
  86 macros.
  87 A table consists of an optional single line of table
  88 .Sx Options
  89 terminated by a semicolon, followed by one or more lines of
  90 .Sx Layout
  91 specifications terminated by a period, then
  92 .Sx Data .
  93 All input must be 7-bit ASCII.
  94 Example:
  95 .Bd -literal -offset indent
  96 \&.TS
  97 box tab(:);
  98 c | c
  99 | c | c.
 100 1:2
 101 3:4
 102 \&.TE
 103 .Ed
 104 .Pp
 105 Table data is
 106 .Em pre-processed ,
 107 that is, data rows are parsed then inserted into the underlying stream
 108 of input data.
 109 This allows data rows to be interspersed by arbitrary
 110 .Xr roff 5 ,
 111 .Xr mdoc 5 ,
 112 and
 113 .Xr man 5
 114 macros such as
 115 .Bd -literal -offset indent
 116 \&.TS
 117 tab(:);
 118 c c c.
 119 1:2:3
 120 \&.Ao
 121 3:2:1
 122 \&.Ac
 123 \&.TE
 124 .Ed
 125 .Pp
 126 in the case of
 127 .Xr mdoc 5
 128 or
 129 .Bd -literal -offset indent
 130 \&.TS
 131 tab(:);
 132 c c c.
 133 \&.ds ab 2
 134 1:\e*(ab:3
 135 \&.I
 136 3:2:1
 137 \&.TE
 138 .Ed
 139 .Pp
 140 in the case of
 141 .Xr man 5 .
 142 .Ss Options
 143 The first line of a table consists of space-separated option keys and
 144 modifiers terminated by a semicolon.
 145 If the first line does not have a terminating semicolon, it is assumed
 146 that no options are specified and instead a
 147 .Sx Layout
 148 is processed.
 149 Some options accept arguments enclosed by parenthesis.
 150 The following case-insensitive options are available:
 151 .Bl -tag -width Ds
 152 .It Cm center
 153 This option is not supported by
 154 .Xr mandoc 1 .
 155 This may also be invoked with
 156 .Cm centre .
 157 .It Cm delim
 158 Accepts a two-character argument.
 159 This option is not supported by
 160 .Xr mandoc 1 .
 161 .It Cm expand
 162 This option is not supported by
 163 .Xr mandoc 1 .
 164 .It Cm box
 165 Draw a single-line box around the table.
 166 This may also be invoked with
 167 .Cm frame .
 168 .It Cm doublebox
 169 Draw a double-line box around the table.
 170 This may also be invoked with
 171 .Cm doubleframe .
 172 .It Cm allbox
 173 This option is not supported by
 174 .Xr mandoc 1 .
 175 .It Cm tab
 176 Accepts a single-character argument.
 177 This character is used as a delimiter between data cells, which otherwise
 178 defaults to the tab character.
 179 .It Cm linesize
 180 Accepts a natural number (all digits).
 181 This option is not supported by
 182 .Xr mandoc 1 .
 183 .It Cm nokeep
 184 This option is not supported by
 185 .Xr mandoc 1 .
 186 .It Cm decimalpoint
 187 Accepts a single-character argument.
 188 This character will be used as the decimal point with the
 189 .Cm n
 190 layout key.
 191 .It Cm nospaces
 192 This option is not supported by
 193 .Xr mandoc 1 .
 194 .El
 195 .Ss Layout
 196 The table layout follows
 197 .Sx Options
 198 or a
 199 .Sq \&T&
 200 macro invocation.
 201 Layout specifies how data rows are displayed on output.
 202 Each layout line corresponds to a line of data; the last layout line
 203 applies to all remaining data lines.
 204 Layout lines may also be separated by a comma.
 205 Each layout cell consists of one of the following case-insensitive keys:
 206 .Bl -tag -width Ds
 207 .It Cm c
 208 Centre a literal string within its column.
 209 .It Cm r
 210 Right-justify a literal string within its column.
 211 .It Cm l
 212 Left-justify a literal string within its column.
 213 .It Cm n
 214 Justify a number around its last decimal point.
 215 If the decimal point is not found on the number, it's assumed to trail
 216 the number.
 217 .It Cm s
 218 Horizontally span columns from the last
 219 .No non- Ns Cm s
 220 data cell.
 221 It is an error if spanning columns follow a
 222 .Cm \-
 223 or
 224 .Cm \(ba
 225 cell, or come first.
 226 This option is not supported by
 227 .Xr mandoc 1 .
 228 .It Cm a
 229 Left-justify a literal string and pad with one space.
 230 .It Cm ^
 231 Vertically span rows from the last
 232 .No non- Ns Cm ^
 233 data cell.
 234 It is an error to invoke a vertical span on the first layout row.
 235 Unlike a horizontal spanner, you must specify an empty cell (if it not
 236 empty, the data is discarded) in the corresponding data cell.
 237 .It Cm \-
 238 Replace the data cell (its contents will be lost) with a single
 239 horizontal line.
 240 This may also be invoked with
 241 .Cm _ .
 242 .It Cm =
 243 Replace the data cell (its contents will be lost) with a double
 244 horizontal line.
 245 .It Cm \(ba
 246 Emit a vertical bar instead of data.
 247 .It Cm \(ba\(ba
 248 Emit a double-vertical bar instead of data.
 249 .El
 250 .Pp
 251 Keys may be followed by a set of modifiers.
 252 A modifier is either a modifier key or a natural number for specifying
 253 the minimum width of a column.
 254 The following case-insensitive modifier keys are available:
 255 .Cm z ,
 256 .Cm u ,
 257 .Cm e ,
 258 .Cm t ,
 259 .Cm d ,
 260 .Cm b ,
 261 .Cm i ,
 262 .Cm r ,
 263 and
 264 .Cm f
 265 .Po
 266 followed by
 267 .Cm b ,
 268 .Cm i ,
 269 .Cm r ,
 270 .Cm 3 ,
 271 .Cm 2 ,
 272 or
 273 .Cm 1
 274 .Pc .
 275 All of these are ignored by
 276 .Xr mandoc 1 .
 277 .Pp
 278 For example, the following layout specifies a centre-justified column of
 279 minimum width 10, followed by vertical bar, followed by a left-justified
 280 column of minimum width 10, another vertical bar, then a column
 281 justified about the decimal point in numbers:
 282 .Pp
 283 .Dl c10 | l10 | n
 284 .Ss Data
 285 The data section follows the last layout row.
 286 By default, cells in a data section are delimited by a tab.
 287 This behaviour may be changed with the
 288 .Cm tab
 289 option.
 290 If
 291 .Cm _
 292 or
 293 .Cm =
 294 is specified, a single or double line, respectively, is drawn across the
 295 data field.
 296 If
 297 .Cm \e-
 298 or
 299 .Cm \e=
 300 is specified, a line is drawn within the data field (i.e. terminating
 301 within the cell and not draw to the border).
 302 If the last cell of a line is
 303 .Cm T{ ,
 304 all subsequent lines are included as part of the cell until
 305 .Cm T}
 306 is specified as its own data cell.
 307 It may then be followed by a tab
 308 .Pq or as designated by Cm tab
 309 or an end-of-line to terminate the row.
 310 .Sh COMPATIBILITY
 311 This section documents compatibility between mandoc and other
 312 .Nm
 313 implementations, at this time limited to GNU tbl.
 314 .Pp
 315 .Bl -dash -compact
 316 .It
 317 In GNU tbl, comments and macros are disallowed prior to the data block
 318 of a table.
 319 The
 320 .Xr mandoc 1
 321 implementation allows them.
 322 .El
 323 .Sh SEE ALSO
 324 .Xr mandoc 1 ,
 325 .Xr man 5 ,
 326 .Xr mandoc_char 5 ,
 327 .Xr mdoc 5 ,
 328 .Xr roff 5
 329 .Rs
 330 .%A M. E. Lesk
 331 .%T Tbl\(emA Program to Format Tables
 332 .%D June 11, 1976
 333 .Re
 334 .Sh HISTORY
 335 The tbl utility, a preprocessor for troff, was originally written by M.
 336 E. Lesk at Bell Labs in 1975.
 337 The GNU reimplementation of tbl, part of the groff package, was released
 338 in 1990 by James Clark.
 339 A standalone tbl implementation was written by Kristaps Dzonsons in
 340 2010.
 341 This formed the basis of the implementation that is part of the
 342 .Xr mandoc 1
 343 utility.
 344 .Sh AUTHORS
 345 This
 346 .Nm
 347 reference was written by
 348 .An Kristaps Dzonsons ,
 349 .Mt kristaps@bsd.lv .