Annotation of mandoc/tbl.7, Revision 1.2
1.2 ! kristaps 1: .\" $Id: tbl.7,v 1.1 2011/01/04 23:32:21 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: .\"
17: .Dd $Mdocdate: January 4 2011 $
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.
101: This allows data rows to be interspersed by arbitrary
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.1 kristaps 141: Some options accept arguments enclosed by paranthesis.
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.
169: This character is used a delimiter between data cells, which otherwise
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: For example, following layout specifies a centre-justified column of
235: minimum width 10, followed by vertical bar, followed by a left-justified
236: column of minimum width 10, another vertical bar, then a column
237: justified about the decimal point in numbers:
238: .Pp
239: .Dl c10 | l10 | n
240: .Pp
241: Keys may be followed by a set of modifiers.
242: A modifier is either a modifier key or a natural number for specifying
243: spacing.
244: The following case-insensitive modifier keys are available:
245: .Cm z ,
246: .Cm u ,
247: .Cm e ,
248: .Cm t ,
249: .Cm d ,
250: .Cm f ,
251: .Cm b ,
252: .Cm i ,
253: .Cm b ,
254: and
255: .Cm i .
256: All of these are ignored by
257: .Xr mandoc 1 .
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=
274: is specified, a line is drawn within the data field (i.e., terminating
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}
280: is specified on its own line.
281: .Sh COMPATIBILITY
282: This section documents compatibility between mandoc and other
283: .Nm
284: implementations, at this time limited to GNU tbl.
285: .Pp
286: .Bl -dash -compact
287: .It
288: In GNU tbl, comments and macros are disallowed prior to the data block
289: of a table.
290: The
291: .Xr mandoc 1
292: implementation allows them.
293: .El
294: .Sh SEE ALSO
295: .Xr mandoc 1 ,
296: .Xr mandoc_char 7 ,
297: .Xr roff 7 ,
298: .Xr man 7 ,
299: .Xr mdoc 7
300: .Rs
301: .%A M. E. Lesk
302: .%T Tbl\(emA Program to Format Tables
303: .%D June 11, 1976
304: .Re
305: .Sh HISTORY
306: The tbl utility, a preprocessor for troff, was originally written by M.
307: E. Lesk at Bell Labs in 1975.
308: The GNU reimplementation of tbl, part of the groff package, was released
309: in 1990 by James Clark.
310: A standalone tbl implementation was written by Kristaps Dzonsons in
311: 2010.
312: This formed the basis of the implementation that is part of the
313: .Xr mandoc 1
314: utility.
315: .Sh AUTHORS
316: This partial
317: .Nm
318: reference was written by
319: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb