tbl.7

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