Annotation of mandoc/tbl.7, Revision 1.16
1.16 ! kristaps 1: .\" $Id: tbl.7,v 1.15 2011/09/02 19:37:35 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.16 ! kristaps 17: .Dd $Mdocdate: September 2 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
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
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 b ,
260: .Cm i ,
1.16 ! kristaps 261: .Cm r ,
! 262: and
! 263: .Cm f
! 264: .Po
! 265: followed by
1.1 kristaps 266: .Cm b ,
1.16 ! kristaps 267: .Cm i ,
! 268: .Cm r ,
! 269: .Cm 3 ,
! 270: .Cm 2 ,
! 271: or
! 272: .Cm 1
! 273: .Pc .
1.1 kristaps 274: All of these are ignored by
275: .Xr mandoc 1 .
1.5 kristaps 276: .Pp
277: For example, the following layout specifies a centre-justified column of
278: minimum width 10, followed by vertical bar, followed by a left-justified
279: column of minimum width 10, another vertical bar, then a column
280: justified about the decimal point in numbers:
281: .Pp
282: .Dl c10 | l10 | n
1.2 kristaps 283: .Ss Data
1.1 kristaps 284: The data section follows the last layout row.
285: By default, cells in a data section are delimited by a tab.
286: This behaviour may be changed with the
287: .Cm tab
288: option.
289: If
290: .Cm _
291: or
292: .Cm =
293: is specified, a single or double line, respectively, is drawn across the
294: data field.
295: If
296: .Cm \e-
297: or
298: .Cm \e=
1.3 kristaps 299: is specified, a line is drawn within the data field (i.e. terminating
1.1 kristaps 300: within the cell and not draw to the border).
301: If the last cell of a line is
302: .Cm T{ ,
303: all subsequent lines are included as part of the cell until
304: .Cm T}
1.4 kristaps 305: is specified as its own data cell.
306: It may then be followed by a tab
307: .Pq or as designated by Cm tab
308: or an end-of-line to terminate the row.
1.1 kristaps 309: .Sh COMPATIBILITY
310: This section documents compatibility between mandoc and other
311: .Nm
312: implementations, at this time limited to GNU tbl.
313: .Pp
314: .Bl -dash -compact
315: .It
316: In GNU tbl, comments and macros are disallowed prior to the data block
317: of a table.
318: The
319: .Xr mandoc 1
320: implementation allows them.
321: .El
322: .Sh SEE ALSO
323: .Xr mandoc 1 ,
1.3 kristaps 324: .Xr man 7 ,
1.1 kristaps 325: .Xr mandoc_char 7 ,
1.3 kristaps 326: .Xr mdoc 7 ,
327: .Xr roff 7
1.1 kristaps 328: .Rs
329: .%A M. E. Lesk
330: .%T Tbl\(emA Program to Format Tables
331: .%D June 11, 1976
332: .Re
333: .Sh HISTORY
334: The tbl utility, a preprocessor for troff, was originally written by M.
335: E. Lesk at Bell Labs in 1975.
336: The GNU reimplementation of tbl, part of the groff package, was released
337: in 1990 by James Clark.
338: A standalone tbl implementation was written by Kristaps Dzonsons in
339: 2010.
340: This formed the basis of the implementation that is part of the
341: .Xr mandoc 1
342: utility.
343: .Sh AUTHORS
1.14 kristaps 344: This
1.1 kristaps 345: .Nm
346: reference was written by
1.14 kristaps 347: .An Kristaps Dzonsons ,
348: .Mt kristaps@bsd.lv .
CVSweb