Annotation of mandoc/tbl.7, Revision 1.9
1.9 ! kristaps 1: .\" $Id: tbl.7,v 1.8 2011/01/10 14:40:30 kristaps Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
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.9 ! kristaps 17: .Dd $Mdocdate: January 10 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
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: This option is not supported by
184: .Xr mandoc 1 .
185: .It Cm nospaces
186: This option is not supported by
187: .Xr mandoc 1 .
188: .El
1.2 kristaps 189: .Ss Layout
190: The table layout follows
191: .Sx Options
192: or a
193: .Sq \&T&
194: macro invocation.
1.1 kristaps 195: Layout specifies how data rows are displayed on output.
196: Each layout line corresponds to a line of data; the last layout line
197: applies to all remaining data lines.
198: Layout lines may also be separated by a comma.
199: Each layout cell consists of one of the following case-insensitive keys:
200: .Bl -tag -width Ds
201: .It Cm c
202: Centre a literal string within its column.
203: .It Cm r
204: Right-justify a literal string within its column.
205: .It Cm l
206: Left-justify a literal string within its column.
207: .It Cm n
1.6 kristaps 208: Justify a number around its last decimal point.
1.1 kristaps 209: If the decimal point is not found on the number, it's assumed to trail
210: the number.
211: .It Cm s
1.9 ! kristaps 212: Horizontally span columns from the last non-
! 213: .Ns Cm s
! 214: data cell.
1.8 kristaps 215: It is an error if spanning columns follow a
216: .Cm \-
217: or
218: .Cm \(ba
219: cell, or come first.
1.9 ! kristaps 220: This option is not supported by
! 221: .Xr mandoc 1 .
1.1 kristaps 222: .It Cm a
1.7 kristaps 223: Left-justify a literal string and pad with one space.
1.1 kristaps 224: .It Cm ^
1.9 ! kristaps 225: Vertically span rows from the last non-
! 226: .Ns Cm ^
! 227: data cell.
! 228: It is an error to invoke a vertical span on the first layout row.
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 f ,
253: .Cm b ,
254: .Cm i ,
255: .Cm b ,
256: and
257: .Cm i .
258: All of these are ignored by
259: .Xr mandoc 1 .
1.5 kristaps 260: .Pp
261: For example, the following layout specifies a centre-justified column of
262: minimum width 10, followed by vertical bar, followed by a left-justified
263: column of minimum width 10, another vertical bar, then a column
264: justified about the decimal point in numbers:
265: .Pp
266: .Dl c10 | l10 | n
1.2 kristaps 267: .Ss Data
1.1 kristaps 268: The data section follows the last layout row.
269: By default, cells in a data section are delimited by a tab.
270: This behaviour may be changed with the
271: .Cm tab
272: option.
273: If
274: .Cm _
275: or
276: .Cm =
277: is specified, a single or double line, respectively, is drawn across the
278: data field.
279: If
280: .Cm \e-
281: or
282: .Cm \e=
1.3 kristaps 283: is specified, a line is drawn within the data field (i.e. terminating
1.1 kristaps 284: within the cell and not draw to the border).
285: If the last cell of a line is
286: .Cm T{ ,
287: all subsequent lines are included as part of the cell until
288: .Cm T}
1.4 kristaps 289: is specified as its own data cell.
290: It may then be followed by a tab
291: .Pq or as designated by Cm tab
292: or an end-of-line to terminate the row.
1.1 kristaps 293: .Sh COMPATIBILITY
294: This section documents compatibility between mandoc and other
295: .Nm
296: implementations, at this time limited to GNU tbl.
297: .Pp
298: .Bl -dash -compact
299: .It
300: In GNU tbl, comments and macros are disallowed prior to the data block
301: of a table.
302: The
303: .Xr mandoc 1
304: implementation allows them.
305: .El
306: .Sh SEE ALSO
307: .Xr mandoc 1 ,
1.3 kristaps 308: .Xr man 7 ,
1.1 kristaps 309: .Xr mandoc_char 7 ,
1.3 kristaps 310: .Xr mdoc 7 ,
311: .Xr roff 7
1.1 kristaps 312: .Rs
313: .%A M. E. Lesk
314: .%T Tbl\(emA Program to Format Tables
315: .%D June 11, 1976
316: .Re
317: .Sh HISTORY
318: The tbl utility, a preprocessor for troff, was originally written by M.
319: E. Lesk at Bell Labs in 1975.
320: The GNU reimplementation of tbl, part of the groff package, was released
321: in 1990 by James Clark.
322: A standalone tbl implementation was written by Kristaps Dzonsons in
323: 2010.
324: This formed the basis of the implementation that is part of the
325: .Xr mandoc 1
326: utility.
327: .Sh AUTHORS
328: This partial
329: .Nm
330: reference was written by
331: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb