contrib/mdocml/tbl.7

   1 .\"     $Id: tbl.7,v 1.21 2014/11/26 17:51:55 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: November 26 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 For GNU compatibility, option keys can also be separated by commas.
 139 If the first line does not have a terminating semicolon, it is assumed
 140 that no options are specified and instead a
 141 .Sx Layout
 142 is processed.
 143 Some options accept arguments enclosed by parenthesis.
 144 The following case-insensitive options are available:
 145 .Bl -tag -width Ds
 146 .It Cm center
 147 This option is not supported by
 148 .Xr mandoc 1 .
 149 This may also be invoked with
 150 .Cm centre .
 151 .It Cm delim
 152 Accepts a two-character argument.
 153 This option is not supported by
 154 .Xr mandoc 1 .
 155 .It Cm expand
 156 This option is not supported by
 157 .Xr mandoc 1 .
 158 .It Cm box
 159 Draw a single-line box around the table.
 160 This may also be invoked with
 161 .Cm frame .
 162 .It Cm doublebox
 163 Draw a double-line box around the table.
 164 This may also be invoked with
 165 .Cm doubleframe .
 166 .It Cm allbox
 167 This option is not supported by
 168 .Xr mandoc 1 .
 169 .It Cm tab
 170 Accepts a single-character argument.
 171 This character is used as a delimiter between data cells, which otherwise
 172 defaults to the tab character.
 173 .It Cm linesize
 174 Accepts a natural number (all digits).
 175 This option is not supported by
 176 .Xr mandoc 1 .
 177 .It Cm nokeep
 178 This option is not supported by
 179 .Xr mandoc 1 .
 180 .It Cm decimalpoint
 181 Accepts a single-character argument.
 182 This character will be used as the decimal point with the
 183 .Cm n
 184 layout key.
 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 2n
 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 Horizontally span columns from the last
 213 .No non- Ns Cm s
 214 data cell.
 215 It is an error if spanning columns follow a
 216 .Cm \-
 217 or
 218 .Cm \(ba
 219 cell, or come first.
 220 This option is not supported by
 221 .Xr mandoc 1 .
 222 .It Cm a
 223 Left-justify a literal string and pad with one space.
 224 .It Cm ^
 225 Vertically span rows from the last
 226 .No non- Ns Cm ^
 227 data cell.
 228 It is an error to invoke a vertical span on the first layout row.
 229 Unlike a horizontal spanner, you must specify an empty cell (if it not
 230 empty, the data is discarded) in the corresponding data cell.
 231 .It Cm \-
 232 Replace the data cell (its contents will be lost) with a single
 233 horizontal line.
 234 This may also be invoked with
 235 .Cm _ .
 236 .It Cm =
 237 Replace the data cell (its contents will be lost) with a double
 238 horizontal line.
 239 .It Cm \(ba
 240 Emit a vertical bar instead of data.
 241 .It Cm \(ba\(ba
 242 Emit a double-vertical bar instead of data.
 243 .El
 244 .Pp
 245 Keys may be followed by a set of modifiers.
 246 A modifier is either a modifier key or a natural number for specifying
 247 the minimum width of a column.
 248 The following case-insensitive modifier keys are available:
 249 .Bl -tag -width 2n
 250 .It Cm b
 251 Use a bold font for the contents of this column.
 252 .It Cm e
 253 Make this column wider to match the maximum width
 254 of any other column also having the
 255 .Cm e
 256 modifier.
 257 .It Cm f
 258 The next character selects the font to use for this column.
 259 See the
 260 .Xr roff 7
 261 manual for supported one-character font names.
 262 .It Cm i
 263 Use an italic font for the contents of this column.
 264 .It Cm x
 265 After determining the width of all other columns, distribute the
 266 rest of the line length among all columns having the
 267 .Cm x
 268 modifier.
 269 .It Cm z
 270 Do not use this cell for determining the width of this column.
 271 .El
 272 .Pp
 273 The modifiers
 274 .Cm d ,
 275 .Cm t ,
 276 .Cm u ,
 277 and
 278 .Cm w
 279 are ignored by
 280 .Xr mandoc 1 .
 281 .Pp
 282 For example, the following layout specifies a centre-justified column of
 283 minimum width 10, followed by vertical bar, followed by a left-justified
 284 column of minimum width 10, another vertical bar, then a column using
 285 bold font justified about the decimal point in numbers:
 286 .Pp
 287 .Dl c10 | l10 | nfB
 288 .Ss Data
 289 The data section follows the last layout row.
 290 By default, cells in a data section are delimited by a tab.
 291 This behaviour may be changed with the
 292 .Cm tab
 293 option.
 294 If
 295 .Cm _
 296 or
 297 .Cm =
 298 is specified, a single or double line, respectively, is drawn across the
 299 data field.
 300 If
 301 .Cm \e-
 302 or
 303 .Cm \e=
 304 is specified, a line is drawn within the data field (i.e. terminating
 305 within the cell and not draw to the border).
 306 If the last cell of a line is
 307 .Cm T{ ,
 308 all subsequent lines are included as part of the cell until
 309 .Cm T}
 310 is specified as its own data cell.
 311 It may then be followed by a tab
 312 .Pq or as designated by Cm tab
 313 or an end-of-line to terminate the row.
 314 .Sh COMPATIBILITY
 315 This section documents compatibility between mandoc and other
 316 .Nm
 317 implementations, at this time limited to GNU tbl.
 318 .Pp
 319 .Bl -dash -compact
 320 .It
 321 In GNU tbl, comments and macros are disallowed prior to the data block
 322 of a table.
 323 The
 324 .Xr mandoc 1
 325 implementation allows them.
 326 .El
 327 .Sh SEE ALSO
 328 .Xr mandoc 1 ,
 329 .Xr man 7 ,
 330 .Xr mandoc_char 7 ,
 331 .Xr mdoc 7 ,
 332 .Xr roff 7
 333 .Rs
 334 .%A M. E. Lesk
 335 .%T Tbl\(emA Program to Format Tables
 336 .%D June 11, 1976
 337 .Re
 338 .Sh HISTORY
 339 The tbl utility, a preprocessor for troff, was originally written by M.
 340 E. Lesk at Bell Labs in 1975.
 341 The GNU reimplementation of tbl, part of the groff package, was released
 342 in 1990 by James Clark.
 343 A standalone tbl implementation was written by Kristaps Dzonsons in
 344 2010.
 345 This formed the basis of the implementation that is part of the
 346 .Xr mandoc 1
 347 utility.
 348 .Sh AUTHORS
 349 This
 350 .Nm
 351 reference was written by
 352 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .