contrib/mdocml/tbl.7

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