Annotation of mandoc/tbl.7, Revision 1.18
1.18 ! schwarze 1: .\" $Id: tbl.7,v 1.17 2013/07/13 19:41:16 schwarze Exp $
1.1 kristaps 2: .\"
1.12 schwarze 3: .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.1 kristaps 4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\"
1.18 ! schwarze 17: .Dd $Mdocdate: July 13 2013 $
1.1 kristaps 18: .Dt TBL 7
19: .Os
20: .Sh NAME
21: .Nm tbl
22: .Nd tbl language reference for mandoc
23: .Sh DESCRIPTION
24: The
25: .Nm tbl
26: language is a table-formatting language.
27: It is used within
28: .Xr mdoc 7
29: and
30: .Xr man 7
31: .Ux
32: manual 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: Tables within
40: .Xr mdoc 7
41: or
42: .Xr man 7
43: are enclosed by the
44: .Sq TS
45: and
46: .Sq TE
47: macro tags, whose precise syntax is documented in
48: .Xr roff 7 .
49: Tables consist of a series of options on a single line, followed by the
50: table layout, followed by data.
51: .Pp
1.15 kristaps 52: For example, the following creates a boxed table with digits centred in
1.1 kristaps 53: the cells.
54: .Bd -literal -offset indent
55: \&.TS
56: tab(:) box;
57: c5 c5 c5.
58: 1:2:3
59: 4:5:6
60: \&.TE
61: .Ed
62: .Pp
63: When formatted, the following output is produced:
64: .Bd -filled -offset indent -compact
65: .TS
66: tab(:) box;
67: c5 c5 c5.
68: 1:2:3
69: 4:5:6
70: .TE
71: .Ed
72: .Sh TABLE STRUCTURE
73: Tables are enclosed by the
74: .Sq TS
75: and
76: .Sq TE
77: .Xr roff 7
78: macros.
1.2 kristaps 79: A table consists of an optional single line of table
80: .Sx Options
81: terminated by a semicolon, followed by one or more lines of
82: .Sx Layout
83: specifications terminated by a period, then
84: .Sx Data .
1.1 kristaps 85: All input must be 7-bit ASCII.
86: Example:
87: .Bd -literal -offset indent
88: \&.TS
89: box tab(:);
90: c | c
91: | c | c.
92: 1:2
93: 3:4
94: \&.TE
95: .Ed
96: .Pp
97: Table data is
98: .Em pre-processed ,
99: that is, data rows are parsed then inserted into the underlying stream
100: of input data.
1.3 kristaps 101: This allows data rows to be interspersed by arbitrary
1.1 kristaps 102: .Xr roff 7 ,
103: .Xr mdoc 7 ,
104: and
105: .Xr man 7
106: macros such as
107: .Bd -literal -offset indent
108: \&.TS
109: tab(:);
110: c c c.
111: 1:2:3
112: \&.Ao
113: 3:2:1
114: \&.Ac
115: \&.TE
116: .Ed
117: .Pp
118: in the case of
119: .Xr mdoc 7
120: or
121: .Bd -literal -offset indent
122: \&.TS
123: tab(:);
124: c c c.
125: \&.ds ab 2
126: 1:\e*(ab:3
127: \&.I
128: 3:2:1
129: \&.TE
130: .Ed
131: .Pp
132: in the case of
133: .Xr man 7 .
1.2 kristaps 134: .Ss Options
135: The first line of a table consists of space-separated option keys and
136: modifiers terminated by a semicolon.
1.1 kristaps 137: If the first line does not have a terminating semicolon, it is assumed
1.2 kristaps 138: that no options are specified and instead a
139: .Sx Layout
140: is processed.
1.3 kristaps 141: Some options accept arguments enclosed by parenthesis.
1.1 kristaps 142: The following case-insensitive options are available:
143: .Bl -tag -width Ds
144: .It Cm center
145: This option is not supported by
146: .Xr mandoc 1 .
147: This may also be invoked with
148: .Cm centre .
149: .It Cm delim
150: Accepts a two-character argument.
151: This option is not supported by
152: .Xr mandoc 1 .
153: .It Cm expand
154: This option is not supported by
155: .Xr mandoc 1 .
156: .It Cm box
157: Draw a single-line box around the table.
158: This may also be invoked with
159: .Cm frame .
160: .It Cm doublebox
161: Draw a double-line box around the table.
162: This may also be invoked with
163: .Cm doubleframe .
164: .It Cm allbox
165: This option is not supported by
166: .Xr mandoc 1 .
167: .It Cm tab
168: Accepts a single-character argument.
1.3 kristaps 169: This character is used as a delimiter between data cells, which otherwise
1.1 kristaps 170: defaults to the tab character.
171: .It Cm linesize
172: Accepts a natural number (all digits).
173: This option is not supported by
174: .Xr mandoc 1 .
175: .It Cm nokeep
176: This option is not supported by
177: .Xr mandoc 1 .
178: .It Cm decimalpoint
179: Accepts a single-character argument.
180: This character will be used as the decimal point with the
181: .Cm n
182: layout key.
183: .It Cm nospaces
184: This option is not supported by
185: .Xr mandoc 1 .
186: .El
1.2 kristaps 187: .Ss Layout
188: The table layout follows
189: .Sx Options
190: or a
191: .Sq \&T&
192: macro invocation.
1.1 kristaps 193: Layout specifies how data rows are displayed on output.
194: Each layout line corresponds to a line of data; the last layout line
195: applies to all remaining data lines.
196: Layout lines may also be separated by a comma.
197: Each layout cell consists of one of the following case-insensitive keys:
198: .Bl -tag -width Ds
199: .It Cm c
200: Centre a literal string within its column.
201: .It Cm r
202: Right-justify a literal string within its column.
203: .It Cm l
204: Left-justify a literal string within its column.
205: .It Cm n
1.6 kristaps 206: Justify a number around its last decimal point.
1.1 kristaps 207: If the decimal point is not found on the number, it's assumed to trail
208: the number.
209: .It Cm s
1.12 schwarze 210: Horizontally span columns from the last
211: .No non- Ns Cm s
1.9 kristaps 212: data cell.
1.8 kristaps 213: It is an error if spanning columns follow a
214: .Cm \-
215: or
216: .Cm \(ba
217: cell, or come first.
1.9 kristaps 218: This option is not supported by
219: .Xr mandoc 1 .
1.1 kristaps 220: .It Cm a
1.7 kristaps 221: Left-justify a literal string and pad with one space.
1.1 kristaps 222: .It Cm ^
1.12 schwarze 223: Vertically span rows from the last
224: .No non- Ns Cm ^
1.9 kristaps 225: data cell.
226: It is an error to invoke a vertical span on the first layout row.
1.10 kristaps 227: Unlike a horizontal spanner, you must specify an empty cell (if it not
228: empty, the data is discarded) in the corresponding data cell.
1.1 kristaps 229: .It Cm \-
230: Replace the data cell (its contents will be lost) with a single
231: horizontal line.
232: This may also be invoked with
233: .Cm _ .
234: .It Cm =
235: Replace the data cell (its contents will be lost) with a double
236: horizontal line.
237: .It Cm \(ba
238: Emit a vertical bar instead of data.
239: .It Cm \(ba\(ba
240: Emit a double-vertical bar instead of data.
241: .El
242: .Pp
243: Keys may be followed by a set of modifiers.
244: A modifier is either a modifier key or a natural number for specifying
1.5 kristaps 245: the minimum width of a column.
1.1 kristaps 246: The following case-insensitive modifier keys are available:
247: .Cm z ,
248: .Cm u ,
249: .Cm e ,
250: .Cm t ,
251: .Cm d ,
252: .Cm b ,
253: .Cm i ,
1.16 kristaps 254: .Cm r ,
255: and
256: .Cm f
257: .Po
258: followed by
1.1 kristaps 259: .Cm b ,
1.16 kristaps 260: .Cm i ,
261: .Cm r ,
262: .Cm 3 ,
263: .Cm 2 ,
264: or
265: .Cm 1
266: .Pc .
1.1 kristaps 267: All of these are ignored by
268: .Xr mandoc 1 .
1.5 kristaps 269: .Pp
270: For example, the following layout specifies a centre-justified column of
271: minimum width 10, followed by vertical bar, followed by a left-justified
272: column of minimum width 10, another vertical bar, then a column
273: justified about the decimal point in numbers:
274: .Pp
275: .Dl c10 | l10 | n
1.2 kristaps 276: .Ss Data
1.1 kristaps 277: The data section follows the last layout row.
278: By default, cells in a data section are delimited by a tab.
279: This behaviour may be changed with the
280: .Cm tab
281: option.
282: If
283: .Cm _
284: or
285: .Cm =
286: is specified, a single or double line, respectively, is drawn across the
287: data field.
288: If
289: .Cm \e-
290: or
291: .Cm \e=
1.3 kristaps 292: is specified, a line is drawn within the data field (i.e. terminating
1.1 kristaps 293: within the cell and not draw to the border).
294: If the last cell of a line is
295: .Cm T{ ,
296: all subsequent lines are included as part of the cell until
297: .Cm T}
1.4 kristaps 298: is specified as its own data cell.
299: It may then be followed by a tab
300: .Pq or as designated by Cm tab
301: or an end-of-line to terminate the row.
1.1 kristaps 302: .Sh COMPATIBILITY
303: This section documents compatibility between mandoc and other
304: .Nm
305: implementations, at this time limited to GNU tbl.
306: .Pp
307: .Bl -dash -compact
308: .It
309: In GNU tbl, comments and macros are disallowed prior to the data block
310: of a table.
311: The
312: .Xr mandoc 1
313: implementation allows them.
314: .El
315: .Sh SEE ALSO
316: .Xr mandoc 1 ,
1.3 kristaps 317: .Xr man 7 ,
1.1 kristaps 318: .Xr mandoc_char 7 ,
1.3 kristaps 319: .Xr mdoc 7 ,
320: .Xr roff 7
1.1 kristaps 321: .Rs
322: .%A M. E. Lesk
323: .%T Tbl\(emA Program to Format Tables
324: .%D June 11, 1976
325: .Re
326: .Sh HISTORY
327: The tbl utility, a preprocessor for troff, was originally written by M.
328: E. Lesk at Bell Labs in 1975.
329: The GNU reimplementation of tbl, part of the groff package, was released
330: in 1990 by James Clark.
331: A standalone tbl implementation was written by Kristaps Dzonsons in
332: 2010.
333: This formed the basis of the implementation that is part of the
334: .Xr mandoc 1
335: utility.
336: .Sh AUTHORS
1.14 kristaps 337: This
1.1 kristaps 338: .Nm
339: reference was written by
1.17 schwarze 340: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
CVSweb