Annotation of mandoc/tbl.7, Revision 1.26
1.26 ! schwarze 1: .\" $Id: tbl.7,v 1.25 2015/01/28 04:19:35 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.26 ! schwarze 18: .Dd $Mdocdate: January 28 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: For GNU compatibility, this may also be invoked with
1.1 kristaps 156: .Cm centre .
1.23 schwarze 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.
1.1 kristaps 162: .It Cm delim
1.23 schwarze 163: Use the two characters of the argument as
164: .Xr eqn 7
165: delimiters.
166: Currently unsupported.
1.1 kristaps 167: .It Cm doublebox
168: Draw a double-line box around the table.
1.23 schwarze 169: For GNU compatibility, this may also be invoked with
1.1 kristaps 170: .Cm doubleframe .
1.23 schwarze 171: .It Cm expand
172: Increase the width of the table to the current line length.
173: Currently ignored.
1.1 kristaps 174: .It Cm linesize
1.23 schwarze 175: Draw lines with the point size given by the unsigned integer argument.
176: Currently ignored.
1.1 kristaps 177: .It Cm nokeep
1.23 schwarze 178: Allow page breaks within the table.
179: This is a GNU extension and currently ignored.
1.1 kristaps 180: .It Cm nospaces
1.23 schwarze 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.
1.1 kristaps 189: .El
1.2 kristaps 190: .Ss Layout
191: The table layout follows
192: .Sx Options
193: or a
194: .Sq \&T&
195: macro invocation.
1.1 kristaps 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:
1.19 schwarze 201: .Bl -tag -width 2n
1.1 kristaps 202: .It Cm c
1.22 schwarze 203: Center a literal string within its column.
1.1 kristaps 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
1.6 kristaps 209: Justify a number around its last decimal point.
1.1 kristaps 210: If the decimal point is not found on the number, it's assumed to trail
211: the number.
212: .It Cm s
1.12 schwarze 213: Horizontally span columns from the last
214: .No non- Ns Cm s
1.9 kristaps 215: data cell.
1.8 kristaps 216: It is an error if spanning columns follow a
217: .Cm \-
218: or
219: .Cm \(ba
220: cell, or come first.
1.9 kristaps 221: This option is not supported by
222: .Xr mandoc 1 .
1.1 kristaps 223: .It Cm a
1.7 kristaps 224: Left-justify a literal string and pad with one space.
1.1 kristaps 225: .It Cm ^
1.12 schwarze 226: Vertically span rows from the last
227: .No non- Ns Cm ^
1.9 kristaps 228: data cell.
229: It is an error to invoke a vertical span on the first layout row.
1.10 kristaps 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.
1.1 kristaps 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
1.5 kristaps 248: the minimum width of a column.
1.1 kristaps 249: The following case-insensitive modifier keys are available:
1.19 schwarze 250: .Bl -tag -width 2n
251: .It Cm b
252: Use a bold font for the contents of this column.
1.24 schwarze 253: .It Cm d
254: Move cell content down to the last cell of a vertical span.
255: Currently ignored.
1.20 schwarze 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.
1.19 schwarze 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.
1.24 schwarze 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.
1.20 schwarze 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.
1.19 schwarze 296: .El
1.5 kristaps 297: .Pp
1.22 schwarze 298: For example, the following layout specifies a center-justified column of
1.5 kristaps 299: minimum width 10, followed by vertical bar, followed by a left-justified
1.19 schwarze 300: column of minimum width 10, another vertical bar, then a column using
301: bold font justified about the decimal point in numbers:
1.5 kristaps 302: .Pp
1.19 schwarze 303: .Dl c10 | l10 | nfB
1.2 kristaps 304: .Ss Data
1.1 kristaps 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=
1.3 kristaps 320: is specified, a line is drawn within the data field (i.e. terminating
1.1 kristaps 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}
1.4 kristaps 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.
1.1 kristaps 330: .Sh COMPATIBILITY
331: The
332: .Xr mandoc 1
1.26 ! schwarze 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.
1.1 kristaps 342: .Sh SEE ALSO
343: .Xr mandoc 1 ,
1.3 kristaps 344: .Xr man 7 ,
1.1 kristaps 345: .Xr mandoc_char 7 ,
1.3 kristaps 346: .Xr mdoc 7 ,
347: .Xr roff 7
1.1 kristaps 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
1.14 kristaps 364: This
1.1 kristaps 365: .Nm
366: reference was written by
1.17 schwarze 367: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
CVSweb