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