xref: /dragonfly/contrib/mdocml/tbl.7 (revision 25a2db75)
1.\"	$Id: tbl.7,v 1.16 2011/09/03 00:29:21 kristaps Exp $
2.\"
3.\" Copyright (c) 2010, 2011 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: September 3 2011 $
18.Dt TBL 7
19.Os
20.Sh NAME
21.Nm tbl
22.Nd tbl language reference for mandoc
23.Sh DESCRIPTION
24The
25.Nm tbl
26language is a table-formatting language.
27It is used within
28.Xr mdoc 7
29and
30.Xr man 7
31.Ux
32manual pages.
33This manual describes the subset of the
34.Nm
35language accepted by the
36.Xr mandoc 1
37utility.
38.Pp
39Tables within
40.Xr mdoc 7
41or
42.Xr man 7
43are enclosed by the
44.Sq TS
45and
46.Sq TE
47macro tags, whose precise syntax is documented in
48.Xr roff 7 .
49Tables consist of a series of options on a single line, followed by the
50table layout, followed by data.
51.Pp
52For example, the following creates a boxed table with digits centred in
53the cells.
54.Bd -literal -offset indent
55\&.TS
56tab(:) box;
57c5 c5 c5.
581:2:3
594:5:6
60\&.TE
61.Ed
62.Pp
63When formatted, the following output is produced:
64.Bd -filled -offset indent -compact
65.TS
66tab(:) box;
67c5 c5 c5.
681:2:3
694:5:6
70.TE
71.Ed
72.Pp
73The
74.Nm
75implementation in
76.Xr mandoc 1
77is
78.Ud
79.Sh TABLE STRUCTURE
80Tables are enclosed by the
81.Sq TS
82and
83.Sq TE
84.Xr roff 7
85macros.
86A table consists of an optional single line of table
87.Sx Options
88terminated by a semicolon, followed by one or more lines of
89.Sx Layout
90specifications terminated by a period, then
91.Sx Data .
92All input must be 7-bit ASCII.
93Example:
94.Bd -literal -offset indent
95\&.TS
96box tab(:);
97c | c
98| c | c.
991:2
1003:4
101\&.TE
102.Ed
103.Pp
104Table data is
105.Em pre-processed ,
106that is, data rows are parsed then inserted into the underlying stream
107of input data.
108This allows data rows to be interspersed by arbitrary
109.Xr roff 7 ,
110.Xr mdoc 7 ,
111and
112.Xr man 7
113macros such as
114.Bd -literal -offset indent
115\&.TS
116tab(:);
117c c c.
1181:2:3
119\&.Ao
1203:2:1
121\&.Ac
122\&.TE
123.Ed
124.Pp
125in the case of
126.Xr mdoc 7
127or
128.Bd -literal -offset indent
129\&.TS
130tab(:);
131c c c.
132\&.ds ab 2
1331:\e*(ab:3
134\&.I
1353:2:1
136\&.TE
137.Ed
138.Pp
139in the case of
140.Xr man 7 .
141.Ss Options
142The first line of a table consists of space-separated option keys and
143modifiers terminated by a semicolon.
144If the first line does not have a terminating semicolon, it is assumed
145that no options are specified and instead a
146.Sx Layout
147is processed.
148Some options accept arguments enclosed by parenthesis.
149The following case-insensitive options are available:
150.Bl -tag -width Ds
151.It Cm center
152This option is not supported by
153.Xr mandoc 1 .
154This may also be invoked with
155.Cm centre .
156.It Cm delim
157Accepts a two-character argument.
158This option is not supported by
159.Xr mandoc 1 .
160.It Cm expand
161This option is not supported by
162.Xr mandoc 1 .
163.It Cm box
164Draw a single-line box around the table.
165This may also be invoked with
166.Cm frame .
167.It Cm doublebox
168Draw a double-line box around the table.
169This may also be invoked with
170.Cm doubleframe .
171.It Cm allbox
172This option is not supported by
173.Xr mandoc 1 .
174.It Cm tab
175Accepts a single-character argument.
176This character is used as a delimiter between data cells, which otherwise
177defaults to the tab character.
178.It Cm linesize
179Accepts a natural number (all digits).
180This option is not supported by
181.Xr mandoc 1 .
182.It Cm nokeep
183This option is not supported by
184.Xr mandoc 1 .
185.It Cm decimalpoint
186Accepts a single-character argument.
187This character will be used as the decimal point with the
188.Cm n
189layout key.
190.It Cm nospaces
191This option is not supported by
192.Xr mandoc 1 .
193.El
194.Ss Layout
195The table layout follows
196.Sx Options
197or a
198.Sq \&T&
199macro invocation.
200Layout specifies how data rows are displayed on output.
201Each layout line corresponds to a line of data; the last layout line
202applies to all remaining data lines.
203Layout lines may also be separated by a comma.
204Each layout cell consists of one of the following case-insensitive keys:
205.Bl -tag -width Ds
206.It Cm c
207Centre a literal string within its column.
208.It Cm r
209Right-justify a literal string within its column.
210.It Cm l
211Left-justify a literal string within its column.
212.It Cm n
213Justify a number around its last decimal point.
214If the decimal point is not found on the number, it's assumed to trail
215the number.
216.It Cm s
217Horizontally span columns from the last
218.No non- Ns Cm s
219data cell.
220It is an error if spanning columns follow a
221.Cm \-
222or
223.Cm \(ba
224cell, or come first.
225This option is not supported by
226.Xr mandoc 1 .
227.It Cm a
228Left-justify a literal string and pad with one space.
229.It Cm ^
230Vertically span rows from the last
231.No non- Ns Cm ^
232data cell.
233It is an error to invoke a vertical span on the first layout row.
234Unlike a horizontal spanner, you must specify an empty cell (if it not
235empty, the data is discarded) in the corresponding data cell.
236.It Cm \-
237Replace the data cell (its contents will be lost) with a single
238horizontal line.
239This may also be invoked with
240.Cm _ .
241.It Cm =
242Replace the data cell (its contents will be lost) with a double
243horizontal line.
244.It Cm \(ba
245Emit a vertical bar instead of data.
246.It Cm \(ba\(ba
247Emit a double-vertical bar instead of data.
248.El
249.Pp
250Keys may be followed by a set of modifiers.
251A modifier is either a modifier key or a natural number for specifying
252the minimum width of a column.
253The 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 ,
261.Cm r ,
262and
263.Cm f
264.Po
265followed by
266.Cm b ,
267.Cm i ,
268.Cm r ,
269.Cm 3 ,
270.Cm 2 ,
271or
272.Cm 1
273.Pc .
274All of these are ignored by
275.Xr mandoc 1 .
276.Pp
277For example, the following layout specifies a centre-justified column of
278minimum width 10, followed by vertical bar, followed by a left-justified
279column of minimum width 10, another vertical bar, then a column
280justified about the decimal point in numbers:
281.Pp
282.Dl c10 | l10 | n
283.Ss Data
284The data section follows the last layout row.
285By default, cells in a data section are delimited by a tab.
286This behaviour may be changed with the
287.Cm tab
288option.
289If
290.Cm _
291or
292.Cm =
293is specified, a single or double line, respectively, is drawn across the
294data field.
295If
296.Cm \e-
297or
298.Cm \e=
299is specified, a line is drawn within the data field (i.e. terminating
300within the cell and not draw to the border).
301If the last cell of a line is
302.Cm T{ ,
303all subsequent lines are included as part of the cell until
304.Cm T}
305is specified as its own data cell.
306It may then be followed by a tab
307.Pq or as designated by Cm tab
308or an end-of-line to terminate the row.
309.Sh COMPATIBILITY
310This section documents compatibility between mandoc and other
311.Nm
312implementations, at this time limited to GNU tbl.
313.Pp
314.Bl -dash -compact
315.It
316In GNU tbl, comments and macros are disallowed prior to the data block
317of a table.
318The
319.Xr mandoc 1
320implementation allows them.
321.El
322.Sh SEE ALSO
323.Xr mandoc 1 ,
324.Xr man 7 ,
325.Xr mandoc_char 7 ,
326.Xr mdoc 7 ,
327.Xr roff 7
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
334The tbl utility, a preprocessor for troff, was originally written by M.
335E. Lesk at Bell Labs in 1975.
336The GNU reimplementation of tbl, part of the groff package, was released
337in 1990 by James Clark.
338A standalone tbl implementation was written by Kristaps Dzonsons in
3392010.
340This formed the basis of the implementation that is part of the
341.Xr mandoc 1
342utility.
343.Sh AUTHORS
344This
345.Nm
346reference was written by
347.An Kristaps Dzonsons ,
348.Mt kristaps@bsd.lv .
349