tbl.7

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