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