bin/mandoc/tbl.7

   1 .\"     $Id: tbl.7,v 1.34 2019/03/02 21:03:02 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\" Copyright (c) 2014,2015,2017,2018,2019 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: March 2 2019 $
  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 formats tables.
  28 It is used within
  29 .Xr mdoc 7
  30 and
  31 .Xr man 7
  32 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 Each table is started with a
  40 .Xr roff 7
  41 .Ic \&TS
  42 macro, consist of at most one line of
  43 .Sx Options ,
  44 one or more
  45 .Sx Layout
  46 lines, one or more
  47 .Sx Data
  48 lines, and ends with a
  49 .Ic \&TE
  50 macro.
  51 All input must be 7-bit ASCII.
  52 .Ss Options
  53 If the first input line of a table ends with a semicolon, it contains
  54 case-insensitive options separated by spaces, tabs, or commas.
  55 Otherwise, it is interpreted as the first
  56 .Sx Layout
  57 line.
  58 .Pp
  59 The following options are available.
  60 Some of them require arguments enclosed in parentheses:
  61 .Bl -tag -width Ds
  62 .It Cm allbox
  63 Draw a single-line box around each table cell.
  64 .It Cm box
  65 Draw a single-line box around the table.
  66 For GNU compatibility, this may also be invoked with
  67 .Cm frame .
  68 .It Cm center
  69 Center the table instead of left-adjusting it.
  70 For GNU compatibility, this may also be invoked with
  71 .Cm centre .
  72 .It Cm decimalpoint
  73 Use the single-character argument as the decimal point with the
  74 .Cm n
  75 layout key.
  76 This is a GNU extension.
  77 .It Cm delim
  78 Use the two characters of the argument as
  79 .Xr eqn 7
  80 delimiters.
  81 Currently unsupported.
  82 .It Cm doublebox
  83 Draw a double-line box around the table.
  84 For GNU compatibility, this may also be invoked with
  85 .Cm doubleframe .
  86 .It Cm expand
  87 Increase the width of the table to the current line length.
  88 Currently ignored.
  89 .It Cm linesize
  90 Draw lines with the point size given by the unsigned integer argument.
  91 Currently ignored.
  92 .It Cm nokeep
  93 Allow page breaks within the table.
  94 This is a GNU extension and currently ignored.
  95 .It Cm nospaces
  96 Ignore leading and trailing spaces in data cells.
  97 This is a GNU extension and currently ignored.
  98 .It Cm nowarn
  99 Suppress warnings about tables exceeding the current line length.
 100 This is a GNU extension and currently ignored.
 101 .It Cm tab
 102 Use the single-character argument as a delimiter between data cells.
 103 By default, the horizontal tabulator character is used.
 104 .El
 105 .Ss Layout
 106 The table layout follows an
 107 .Sx Options
 108 line or a
 109 .Xr roff 7
 110 .Ic \&TS
 111 or
 112 .Ic \&T&
 113 macro.
 114 Each layout line specifies how one line of
 115 .Sx Data
 116 is formatted.
 117 The last layout line ends with a full stop.
 118 It also applies to all remaining data lines.
 119 Multiple layout lines can be joined by commas on a single physical
 120 input line.
 121 .Pp
 122 Each layout line consists of one or more layout cell specifications,
 123 optionally separated by whitespace.
 124 The following case-insensitive key characters start a new cell
 125 specification:
 126 .Bl -tag -width 2n
 127 .It Cm c
 128 Center the string in this cell.
 129 .It Cm r
 130 Right-justify the string in this cell.
 131 .It Cm l
 132 Left-justify the string in this cell.
 133 .It Cm n
 134 Justify a number around its last decimal point.
 135 If no decimal point is found in the number,
 136 it is assumed to trail the number.
 137 .It Cm s
 138 Horizontally span columns from the last
 139 .Pf non- Cm s
 140 layout cell.
 141 It is an error if a column span follows a
 142 .Cm _
 143 or
 144 .Cm =
 145 cell, or comes first on a layout line.
 146 The combined cell as a whole consumes only one cell
 147 of the corresponding data line.
 148 .It Cm a
 149 Left-justify a string and pad with one space.
 150 .It Cm \(ha
 151 Vertically span rows from the last
 152 .Pf non- Cm \(ha
 153 layout cell.
 154 It is an error to invoke a vertical span on the first layout line.
 155 Unlike a horizontal span, a vertical span consumes a data cell
 156 and discards the content.
 157 .It Cm _
 158 Draw a single horizontal line in this cell.
 159 This consumes a data cell and discards the content.
 160 It may also be invoked with
 161 .Cm \- .
 162 .It Cm =
 163 Draw a double horizontal line in this cell.
 164 This consumes a data cell and discards the content.
 165 .El
 166 .Pp
 167 Each cell key may be followed by zero or more of the following
 168 case-insensitive modifiers:
 169 .Bl -tag -width 2n
 170 .It Cm b
 171 Use a bold font for the contents of this cell.
 172 .It Cm d
 173 Move content down to the last row of this vertical span.
 174 Currently ignored.
 175 .It Cm e
 176 Make this column wider to match the maximum width
 177 of any other column also having the
 178 .Cm e
 179 modifier.
 180 .It Cm f
 181 The next character selects the font to use for this cell.
 182 See the
 183 .Xr roff 7
 184 manual for supported one-character font names.
 185 .It Cm i
 186 Use an italic font for the contents of this cell.
 187 .It Cm m
 188 Specify a cell start macro.
 189 This is a GNU extension and currently unsupported.
 190 .It Cm p
 191 Set the point size to the following unsigned argument,
 192 or change it by the following signed argument.
 193 Currently ignored.
 194 .It Cm v
 195 Set the vertical line spacing to the following unsigned argument,
 196 or change it by the following signed argument.
 197 Currently ignored.
 198 .It Cm t
 199 Do not vertically center content in this vertical span,
 200 leave it in the top row.
 201 Currently ignored.
 202 .It Cm u
 203 Move cell content up by half a table row.
 204 Currently ignored.
 205 .It Cm w
 206 Specify a minimum column width.
 207 .It Cm x
 208 After determining the width of all other columns, distribute the
 209 rest of the line length among all columns having the
 210 .Cm x
 211 modifier.
 212 .It Cm z
 213 Do not use this cell for determining the width of this column.
 214 .It Cm \&|
 215 Draw a single vertical line to the right of this cell.
 216 .It Cm ||
 217 Draw a double vertical line to the right of this cell.
 218 .El
 219 .Pp
 220 If a modifier consists of decimal digits,
 221 it specifies a minimum spacing in units of
 222 .Cm n
 223 between this column and the next column to the right.
 224 The default is 3.
 225 If there is a vertical line, it is drawn inside the spacing.
 226 .Ss Data
 227 The data section follows the last
 228 .Sx Layout
 229 line.
 230 Each data line consists of one or more data cells, delimited by
 231 .Cm tab
 232 characters.
 233 .Pp
 234 If a data cell contains only the two bytes
 235 .Ql \e\(ha ,
 236 the cell above spans to this row, as if the layout specification
 237 of this cell were
 238 .Cm \(ha .
 239 .Pp
 240 If a data cell contains only the single character
 241 .Ql _
 242 or
 243 .Ql = ,
 244 a single or double horizontal line is drawn across the cell,
 245 joining its neighbours.
 246 If a data cell contains only the two character sequence
 247 .Ql \e_
 248 or
 249 .Ql \e= ,
 250 a single or double horizontal line is drawn inside the cell,
 251 not joining its neighbours.
 252 If a data line contains nothing but the single character
 253 .Ql _
 254 or
 255 .Ql = ,
 256 a horizontal line across the whole table is inserted
 257 without consuming a layout row.
 258 .Pp
 259 In place of any data cell, a text block can be used.
 260 It starts with
 261 .Ic \&T{
 262 at the end of a physical input line.
 263 Input line breaks inside the text block
 264 neither end the text block nor its data cell.
 265 It only ends if
 266 .Ic \&T}
 267 occurs at the beginning of a physical input line and is followed
 268 by an end-of-cell indicator.
 269 If the
 270 .Ic \&T}
 271 is followed by the end of the physical input line, the text block,
 272 the data cell, and the data line ends at this point.
 273 If the
 274 .Ic \&T}
 275 is followed by the
 276 .Cm tab
 277 character, only the text block and the data cell end,
 278 but the data line continues with the data cell following the
 279 .Cm tab
 280 character.
 281 If
 282 .Ic \&T}
 283 is followed by any other character, it does not end the text block,
 284 which instead continues to the following physical input line.
 285 .Sh EXAMPLES
 286 String justification and font selection:
 287 .Bd -literal -offset indent
 288 \&.TS
 289 rb c  lb
 290 r  ci l.
 291 r       center  l
 292 ri      ce      le
 293 right   c       left
 294 \&.TE
 295 .Ed
 296 .Bd -filled -offset indent
 297 .TS
 298 rb c  lb
 299 r  ci l.
 300 r       center  l
 301 ri      ce      le
 302 right   c       left
 303 .TE
 304 .Ed
 305 .Pp
 306 Some ports in
 307 .Ox 6.1
 308 to show number alignment and line drawing:
 309 .Bd -literal -offset indent
 310 \&.TS
 311 box tab(:);
 312 r| l
 313 r  n.
 314 software:version
 315 _
 316 AFL:2.39b
 317 Mutt:1.8.0
 318 Ruby:1.8.7.374
 319 TeX Live:2015
 320 \&.TE
 321 .Ed
 322 .Bd -filled -offset indent
 323 .TS
 324 box tab(:);
 325 r| l
 326 r  n.
 327 software:version
 328 _
 329 AFL:2.39b
 330 Mutt:1.8.0
 331 Ruby:1.8.7.374
 332 TeX Live:2015
 333 .TE
 334 .Ed
 335 .sp 2v
 336 Spans and skipping width calculations:
 337 .Bd -literal -offset indent
 338 \&.TS
 339 box tab(:);
 340 lz  s | rt
 341 lt| cb| \(ha
 342 \(ha | rz  s.
 343 left:r
 344 l:center:
 345 :right
 346 \&.TE
 347 .Ed
 348 .Bd -filled -offset indent
 349 .TS
 350 box tab(:);
 351 lz  s | rt
 352 lt| cb| ^
 353 ^ | rz  s.
 354 left:r
 355 l:center:
 356 :right
 357 .TE
 358 .Ed
 359 .sp 2v
 360 Text blocks, specifying spacings and specifying and equalizing
 361 column widths, putting lines into individual cells, and overriding
 362 .Cm allbox :
 363 .Bd -literal -offset indent
 364 \&.TS
 365 allbox tab(:);
 366 le le||7 lw10.
 367 The fourth line:_:line 1
 368 of this column:=:line 2
 369 determines:\_:line 3
 370 the column width.:T{
 371 This text is too wide to fit into a column of width 17.
 372 T}:line 4
 373 T{
 374 No break here.
 375 T}::line 5
 376 \&.TE
 377 .Ed
 378 .Bd -filled -offset indent
 379 .TS
 380 allbox tab(:);
 381 le le||7 lw10.
 382 The fourth line:_:line 1
 383 of this column:=:line 2
 384 determines:\_:line 3
 385 the column width.:T{
 386 This text is too wide to fit into a column of width 17.
 387 T}:line 4
 388 T{
 389 No break here.
 390 T}::line 5
 391 .TE
 392 .Ed
 393 .sp 2v
 394 These examples were constructed to demonstrate many
 395 .Nm
 396 features in a compact way.
 397 In real manual pages, keep tables as simple as possible.
 398 They usually look better, are less fragile, and are more portable.
 399 .Sh COMPATIBILITY
 400 The
 401 .Xr mandoc 1
 402 implementation of
 403 .Nm
 404 doesn't support
 405 .Xr mdoc 7
 406 and
 407 .Xr man 7
 408 macros and
 409 .Xr eqn 7
 410 equations inside tables.
 411 .Sh SEE ALSO
 412 .Xr mandoc 1 ,
 413 .Xr man 7 ,
 414 .Xr mandoc_char 7 ,
 415 .Xr mdoc 7 ,
 416 .Xr roff 7
 417 .Rs
 418 .%A M. E. Lesk
 419 .%T Tbl\(emA Program to Format Tables
 420 .%D June 11, 1976
 421 .Re
 422 .Sh HISTORY
 423 The tbl utility, a preprocessor for troff, was originally written by M.
 424 E. Lesk at Bell Labs in 1975.
 425 The GNU reimplementation of tbl, part of the groff package, was released
 426 in 1990 by James Clark.
 427 A standalone tbl implementation was written by Kristaps Dzonsons in
 428 2010.
 429 This formed the basis of the implementation that first appeared in
 430 .Ox 4.9
 431 as a part of the
 432 .Xr mandoc 1
 433 utility.
 434 .Sh AUTHORS
 435 This
 436 .Nm
 437 reference was written by
 438 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 439 and
 440 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
 441 .Sh BUGS
 442 In
 443 .Fl T
 444 .Cm utf8
 445 output mode, heavy lines are drawn instead of double lines.
 446 This cannot be improved because the Unicode standard only provides
 447 an incomplete set of box drawing characters with double lines,
 448 whereas it provides a full set of box drawing characters
 449 with heavy lines.
 450 It is unlikely this can be improved in the future because the box
 451 drawing characters are already marked in Unicode as characters
 452 intended only for backward compatibility with legacy systems,
 453 and their use is not encouraged.
 454 So it seems unlikely that the missing ones might get added in the future.