tbl.7

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