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