Annotation of mandoc/tbl.7, Revision 1.7
1.7 ! kristaps 1: .\" $Id: tbl.7,v 1.6 2011/01/08 17:16:48 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.6 kristaps 17: .Dd $Mdocdate: January 8 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
212: This option is not supported by
213: .Xr mandoc 1 .
214: .It Cm a
1.7 ! kristaps 215: Left-justify a literal string and pad with one space.
1.1 kristaps 216: .It Cm ^
217: This option is not supported by
218: .Xr mandoc 1 .
219: .It Cm \-
220: Replace the data cell (its contents will be lost) with a single
221: horizontal line.
222: This may also be invoked with
223: .Cm _ .
224: .It Cm =
225: Replace the data cell (its contents will be lost) with a double
226: horizontal line.
227: .It Cm \(ba
228: Emit a vertical bar instead of data.
229: .It Cm \(ba\(ba
230: Emit a double-vertical bar instead of data.
231: .El
232: .Pp
233: Keys may be followed by a set of modifiers.
234: A modifier is either a modifier key or a natural number for specifying
1.5 kristaps 235: the minimum width of a column.
1.1 kristaps 236: The following case-insensitive modifier keys are available:
237: .Cm z ,
238: .Cm u ,
239: .Cm e ,
240: .Cm t ,
241: .Cm d ,
242: .Cm f ,
243: .Cm b ,
244: .Cm i ,
245: .Cm b ,
246: and
247: .Cm i .
248: All of these are ignored by
249: .Xr mandoc 1 .
1.5 kristaps 250: .Pp
251: For example, the following layout specifies a centre-justified column of
252: minimum width 10, followed by vertical bar, followed by a left-justified
253: column of minimum width 10, another vertical bar, then a column
254: justified about the decimal point in numbers:
255: .Pp
256: .Dl c10 | l10 | n
1.2 kristaps 257: .Ss Data
1.1 kristaps 258: The data section follows the last layout row.
259: By default, cells in a data section are delimited by a tab.
260: This behaviour may be changed with the
261: .Cm tab
262: option.
263: If
264: .Cm _
265: or
266: .Cm =
267: is specified, a single or double line, respectively, is drawn across the
268: data field.
269: If
270: .Cm \e-
271: or
272: .Cm \e=
1.3 kristaps 273: is specified, a line is drawn within the data field (i.e. terminating
1.1 kristaps 274: within the cell and not draw to the border).
275: If the last cell of a line is
276: .Cm T{ ,
277: all subsequent lines are included as part of the cell until
278: .Cm T}
1.4 kristaps 279: is specified as its own data cell.
280: It may then be followed by a tab
281: .Pq or as designated by Cm tab
282: or an end-of-line to terminate the row.
1.1 kristaps 283: .Sh COMPATIBILITY
284: This section documents compatibility between mandoc and other
285: .Nm
286: implementations, at this time limited to GNU tbl.
287: .Pp
288: .Bl -dash -compact
289: .It
290: In GNU tbl, comments and macros are disallowed prior to the data block
291: of a table.
292: The
293: .Xr mandoc 1
294: implementation allows them.
295: .El
296: .Sh SEE ALSO
297: .Xr mandoc 1 ,
1.3 kristaps 298: .Xr man 7 ,
1.1 kristaps 299: .Xr mandoc_char 7 ,
1.3 kristaps 300: .Xr mdoc 7 ,
301: .Xr roff 7
1.1 kristaps 302: .Rs
303: .%A M. E. Lesk
304: .%T Tbl\(emA Program to Format Tables
305: .%D June 11, 1976
306: .Re
307: .Sh HISTORY
308: The tbl utility, a preprocessor for troff, was originally written by M.
309: E. Lesk at Bell Labs in 1975.
310: The GNU reimplementation of tbl, part of the groff package, was released
311: in 1990 by James Clark.
312: A standalone tbl implementation was written by Kristaps Dzonsons in
313: 2010.
314: This formed the basis of the implementation that is part of the
315: .Xr mandoc 1
316: utility.
317: .Sh AUTHORS
318: This partial
319: .Nm
320: reference was written by
321: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb