Annotation of mandoc/tbl.7, Revision 1.28
1.28 ! schwarze 1: .\" $Id: tbl.7,v 1.27 2017/06/08 18:11:22 schwarze Exp $
1.1 kristaps 2: .\"
1.12 schwarze 3: .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.27 schwarze 4: .\" Copyright (c) 2014, 2015, 2017 Ingo Schwarze <schwarze@openbsd.org>
1.1 kristaps 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: .\"
1.28 ! schwarze 18: .Dd $Mdocdate: June 8 2017 $
1.1 kristaps 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
1.28 ! schwarze 27: language formats tables.
1.1 kristaps 28: It is used within
29: .Xr mdoc 7
30: and
31: .Xr man 7
1.28 ! schwarze 32: pages.
1.1 kristaps 33: This manual describes the subset of the
34: .Nm
35: language accepted by the
36: .Xr mandoc 1
37: utility.
38: .Pp
1.28 ! schwarze 39: Each table is started with a
1.1 kristaps 40: .Xr roff 7
1.28 ! schwarze 41: .Ic \&TS
! 42: macro, consist of at most one line of
! 43: .Sx Options ,
! 44: one or more
1.2 kristaps 45: .Sx Layout
1.28 ! schwarze 46: lines, one or more
! 47: .Sx Data
! 48: lines, and ends with a
! 49: .Ic \&TE
! 50: macro.
1.1 kristaps 51: All input must be 7-bit ASCII.
1.2 kristaps 52: .Ss Options
1.28 ! schwarze 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
1.2 kristaps 56: .Sx Layout
1.28 ! schwarze 57: line.
! 58: .Pp
! 59: The following options are available.
! 60: Some of them require arguments enclosed in parentheses:
1.1 kristaps 61: .Bl -tag -width Ds
1.23 schwarze 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 .
1.1 kristaps 68: .It Cm center
1.23 schwarze 69: Center the table instead of left-adjusting it.
70: For GNU compatibility, this may also be invoked with
1.1 kristaps 71: .Cm centre .
1.23 schwarze 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.
1.1 kristaps 77: .It Cm delim
1.23 schwarze 78: Use the two characters of the argument as
79: .Xr eqn 7
80: delimiters.
81: Currently unsupported.
1.1 kristaps 82: .It Cm doublebox
83: Draw a double-line box around the table.
1.23 schwarze 84: For GNU compatibility, this may also be invoked with
1.1 kristaps 85: .Cm doubleframe .
1.23 schwarze 86: .It Cm expand
87: Increase the width of the table to the current line length.
88: Currently ignored.
1.1 kristaps 89: .It Cm linesize
1.23 schwarze 90: Draw lines with the point size given by the unsigned integer argument.
91: Currently ignored.
1.1 kristaps 92: .It Cm nokeep
1.23 schwarze 93: Allow page breaks within the table.
94: This is a GNU extension and currently ignored.
1.1 kristaps 95: .It Cm nospaces
1.23 schwarze 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.
1.28 ! schwarze 103: By default, the horizontal tabulator character is used.
1.1 kristaps 104: .El
1.2 kristaps 105: .Ss Layout
1.28 ! schwarze 106: The table layout follows an
1.2 kristaps 107: .Sx Options
1.28 ! schwarze 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:
1.19 schwarze 126: .Bl -tag -width 2n
1.1 kristaps 127: .It Cm c
1.28 ! schwarze 128: Center the string in this cell.
1.1 kristaps 129: .It Cm r
1.28 ! schwarze 130: Right-justify the string in this cell.
1.1 kristaps 131: .It Cm l
1.28 ! schwarze 132: Left-justify the string in this cell.
1.1 kristaps 133: .It Cm n
1.6 kristaps 134: Justify a number around its last decimal point.
1.28 ! schwarze 135: If no decimal point is found in the number,
! 136: it is assumed to trail the number.
1.1 kristaps 137: .It Cm s
1.12 schwarze 138: Horizontally span columns from the last
1.28 ! schwarze 139: .Pf non- Cm s
! 140: layout cell.
! 141: It is an error if a column span follows a
! 142: .Cm _
1.8 kristaps 143: or
1.28 ! schwarze 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.
1.1 kristaps 148: .It Cm a
1.28 ! schwarze 149: Left-justify a string and pad with one space.
1.1 kristaps 150: .It Cm ^
1.12 schwarze 151: Vertically span rows from the last
1.28 ! schwarze 152: .Pf non- Cm ^
! 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 \- .
1.1 kristaps 162: .It Cm =
1.28 ! schwarze 163: Draw a double horizontal line in this cell.
! 164: This consumes a data cell and discards the content.
1.1 kristaps 165: .El
166: .Pp
1.28 ! schwarze 167: Each cell key may be followed by zero or more of the following
! 168: case-insensitive modifiers:
1.19 schwarze 169: .Bl -tag -width 2n
170: .It Cm b
1.28 ! schwarze 171: Use a bold font for the contents of this cell.
1.24 schwarze 172: .It Cm d
1.28 ! schwarze 173: Move content down to the last row of this vertical span.
1.24 schwarze 174: Currently ignored.
1.20 schwarze 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.
1.19 schwarze 180: .It Cm f
1.28 ! schwarze 181: The next character selects the font to use for this cell.
1.19 schwarze 182: See the
183: .Xr roff 7
184: manual for supported one-character font names.
185: .It Cm i
1.28 ! schwarze 186: Use an italic font for the contents of this cell.
1.24 schwarze 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
1.28 ! schwarze 199: Do not vertically center content in this vertical span,
! 200: leave it in the top row.
1.24 schwarze 201: Currently ignored.
202: .It Cm u
1.28 ! schwarze 203: Move cell content up by half a table row.
1.24 schwarze 204: Currently ignored.
205: .It Cm w
1.28 ! schwarze 206: Specify a minimum column width.
1.20 schwarze 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.
1.28 ! schwarze 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.
1.19 schwarze 218: .El
1.5 kristaps 219: .Pp
1.28 ! schwarze 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.
1.2 kristaps 226: .Ss Data
1.28 ! schwarze 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
1.1 kristaps 231: .Cm tab
1.28 ! schwarze 232: characters.
! 233: .Pp
! 234: If a data cells contains only the single character
! 235: .Ql _
! 236: or
! 237: .Ql = ,
! 238: a single or double horizontal line is drawn across the cell,
! 239: joining its neighbours.
! 240: If a data cells contains only the two character sequence
! 241: .Ql \e_
! 242: or
! 243: .Ql \e= ,
! 244: a single or double horizontal line is drawn inside the cell,
! 245: not joining its neighbours.
! 246: If a data line contains nothing but the single character
! 247: .Ql _
1.1 kristaps 248: or
1.28 ! schwarze 249: .Ql = ,
! 250: a horizontal line across the whole table is inserted
! 251: without consuming a layout row.
! 252: .Pp
! 253: In place of any data cell, a text block can be used.
! 254: It starts with
! 255: .Ic \&T{
! 256: at the end of a physical input line.
! 257: Input line breaks inside the text block
! 258: neither end the text block nor its data cell.
! 259: It only ends if
! 260: .Ic \&T}
! 261: occurs at the beginning of a physical input line and is followed
! 262: by an end-of-cell indicator.
! 263: If the
! 264: .Ic \&T}
! 265: is followed by the end of the physical input line, the text block,
! 266: the data cell, and the data line ends at this point.
! 267: If the
! 268: .Ic \&T}
! 269: is followed by the
! 270: .Cm tab
! 271: character, only the text block and the data cell end,
! 272: but the data line continues with the data cell following the
! 273: .Cm tab
! 274: character.
1.1 kristaps 275: If
1.28 ! schwarze 276: .Ic \&T}
! 277: is followed by any other character, it does not end the text block,
! 278: which instead continues to the following physical input line.
! 279: .Sh EXAMPLES
! 280: String justification and font selection:
! 281: .Bd -literal -offset indent
! 282: \&.TS
! 283: rb c lb
! 284: r ci l.
! 285: r center l
! 286: ri ce le
! 287: right c left
! 288: \&.TE
! 289: .Ed
! 290: .Bd -filled -offset indent
! 291: .TS
! 292: rb c lb
! 293: r ci l.
! 294: r center l
! 295: ri ce le
! 296: right c left
! 297: .TE
! 298: .Ed
! 299: .Pp
! 300: Some ports in
! 301: .Ox 6.1
! 302: to show number alignment and line drawing:
! 303: .Bd -literal -offset indent
! 304: \&.TS
! 305: box tab(:);
! 306: r| l
! 307: r n.
! 308: software:version
! 309: _
! 310: AFL:2.39b
! 311: Mutt:1.8.0
! 312: Ruby:1.8.7.374
! 313: TeX Live:2015
! 314: \&.TE
! 315: .Ed
! 316: .Bd -filled -offset indent
! 317: .TS
! 318: box tab(:);
! 319: r| l
! 320: r n.
! 321: software:version
! 322: _
! 323: AFL:2.39b
! 324: Mutt:1.8.0
! 325: Ruby:1.8.7.374
! 326: TeX Live:2015
! 327: .TE
! 328: .Ed
! 329: .sp 2v
! 330: Spans and skipping width calculations:
! 331: .Bd -literal -offset indent
! 332: \&.TS
! 333: box tab(:);
! 334: lz s | rt
! 335: lt| cb| ^
! 336: ^ | rz s.
! 337: left:r
! 338: l:center:
! 339: :right
! 340: \&.TE
! 341: .Ed
! 342: .Bd -filled -offset indent
! 343: .TS
! 344: box tab(:);
! 345: lz s | rt
! 346: lt| cb| ^
! 347: ^ | rz s.
! 348: left:r
! 349: l:center:
! 350: :right
! 351: .TE
! 352: .Ed
! 353: .sp 2v
! 354: Text blocks, specifying spacings and specifying and equalizing
! 355: column widths, putting lines into individual cells, and overriding
! 356: .Cm allbox :
! 357: .Bd -literal -offset indent
! 358: \&.TS
! 359: allbox tab(:);
! 360: le le||7 lw10.
! 361: The fourth line:_:line 1
! 362: of this column:=:line 2
! 363: determines:\_:line 3
! 364: the column width.:T{
! 365: This text is too wide to fit into a column of width 17.
! 366: T}:line 4
! 367: T{
! 368: No break here.
! 369: T}::line 5
! 370: \&.TE
! 371: .Ed
! 372: .Bd -filled -offset indent
! 373: .TS
! 374: allbox tab(:);
! 375: le le||7 lw10.
! 376: The fourth line:_:line 1
! 377: of this column:=:line 2
! 378: determines:\_:line 3
! 379: the column width.:T{
! 380: This text is too wide to fit into a column of width 17.
! 381: T}:line 4
! 382: T{
! 383: No break here.
! 384: T}::line 5
! 385: .TE
! 386: .Ed
! 387: .sp 2v
! 388: These examples were constructed to demonstrate many
! 389: .Nm
! 390: features in a compact way.
! 391: In real manual pages, keep tables as simple as possible:
! 392: Like that, they usually look better, are less fragile, and more portable.
1.1 kristaps 393: .Sh COMPATIBILITY
394: The
395: .Xr mandoc 1
1.26 schwarze 396: implementation of
397: .Nm
398: doesn't support
399: .Xr mdoc 7
400: and
401: .Xr man 7
402: macros and
403: .Xr eqn 7
404: equations inside tables.
1.1 kristaps 405: .Sh SEE ALSO
406: .Xr mandoc 1 ,
1.3 kristaps 407: .Xr man 7 ,
1.1 kristaps 408: .Xr mandoc_char 7 ,
1.3 kristaps 409: .Xr mdoc 7 ,
410: .Xr roff 7
1.1 kristaps 411: .Rs
412: .%A M. E. Lesk
413: .%T Tbl\(emA Program to Format Tables
414: .%D June 11, 1976
415: .Re
416: .Sh HISTORY
417: The tbl utility, a preprocessor for troff, was originally written by M.
418: E. Lesk at Bell Labs in 1975.
419: The GNU reimplementation of tbl, part of the groff package, was released
420: in 1990 by James Clark.
421: A standalone tbl implementation was written by Kristaps Dzonsons in
422: 2010.
423: This formed the basis of the implementation that is part of the
424: .Xr mandoc 1
425: utility.
426: .Sh AUTHORS
1.14 kristaps 427: This
1.1 kristaps 428: .Nm
429: reference was written by
1.28 ! schwarze 430: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
! 431: and
! 432: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
CVSweb