Annotation of mandoc/tbl.7, Revision 1.21
1.21 ! schwarze 1: .\" $Id: tbl.7,v 1.20 2014/10/14 02:16:06 schwarze Exp $
1.1 kristaps 2: .\"
1.12 schwarze 3: .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.19 schwarze 4: .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
1.1 kristaps 5: .\"
6: .\" Permission to use, copy, modify, and distribute this software for any
7: .\" purpose with or without fee is hereby granted, provided that the above
8: .\" copyright notice and this permission notice appear in all copies.
9: .\"
10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17: .\"
1.21 ! schwarze 18: .Dd $Mdocdate: October 14 2014 $
1.1 kristaps 19: .Dt TBL 7
20: .Os
21: .Sh NAME
22: .Nm tbl
23: .Nd tbl language reference for mandoc
24: .Sh DESCRIPTION
25: The
26: .Nm tbl
27: language is a table-formatting language.
28: It is used within
29: .Xr mdoc 7
30: and
31: .Xr man 7
32: .Ux
33: manual pages.
34: This manual describes the subset of the
35: .Nm
36: language accepted by the
37: .Xr mandoc 1
38: utility.
39: .Pp
40: Tables within
41: .Xr mdoc 7
42: or
43: .Xr man 7
44: are enclosed by the
45: .Sq TS
46: and
47: .Sq TE
48: macro tags, whose precise syntax is documented in
49: .Xr roff 7 .
50: Tables consist of a series of options on a single line, followed by the
51: table layout, followed by data.
52: .Pp
1.15 kristaps 53: For example, the following creates a boxed table with digits centred in
1.1 kristaps 54: the cells.
55: .Bd -literal -offset indent
56: \&.TS
57: tab(:) box;
58: c5 c5 c5.
59: 1:2:3
60: 4:5:6
61: \&.TE
62: .Ed
63: .Pp
64: When formatted, the following output is produced:
65: .Bd -filled -offset indent -compact
66: .TS
67: tab(:) box;
68: c5 c5 c5.
69: 1:2:3
70: 4:5:6
71: .TE
72: .Ed
73: .Sh TABLE STRUCTURE
74: Tables are enclosed by the
75: .Sq TS
76: and
77: .Sq TE
78: .Xr roff 7
79: macros.
1.2 kristaps 80: A table consists of an optional single line of table
81: .Sx Options
82: terminated by a semicolon, followed by one or more lines of
83: .Sx Layout
84: specifications terminated by a period, then
85: .Sx Data .
1.1 kristaps 86: All input must be 7-bit ASCII.
87: Example:
88: .Bd -literal -offset indent
89: \&.TS
90: box tab(:);
91: c | c
92: | c | c.
93: 1:2
94: 3:4
95: \&.TE
96: .Ed
97: .Pp
98: Table data is
99: .Em pre-processed ,
100: that is, data rows are parsed then inserted into the underlying stream
101: of input data.
1.3 kristaps 102: This allows data rows to be interspersed by arbitrary
1.1 kristaps 103: .Xr roff 7 ,
104: .Xr mdoc 7 ,
105: and
106: .Xr man 7
107: macros such as
108: .Bd -literal -offset indent
109: \&.TS
110: tab(:);
111: c c c.
112: 1:2:3
113: \&.Ao
114: 3:2:1
115: \&.Ac
116: \&.TE
117: .Ed
118: .Pp
119: in the case of
120: .Xr mdoc 7
121: or
122: .Bd -literal -offset indent
123: \&.TS
124: tab(:);
125: c c c.
126: \&.ds ab 2
127: 1:\e*(ab:3
128: \&.I
129: 3:2:1
130: \&.TE
131: .Ed
132: .Pp
133: in the case of
134: .Xr man 7 .
1.2 kristaps 135: .Ss Options
136: The first line of a table consists of space-separated option keys and
137: modifiers terminated by a semicolon.
1.21 ! schwarze 138: For GNU compatibility, option keys can also be separated by commas.
1.1 kristaps 139: If the first line does not have a terminating semicolon, it is assumed
1.2 kristaps 140: that no options are specified and instead a
141: .Sx Layout
142: is processed.
1.3 kristaps 143: Some options accept arguments enclosed by parenthesis.
1.1 kristaps 144: The following case-insensitive options are available:
145: .Bl -tag -width Ds
146: .It Cm center
147: This option is not supported by
148: .Xr mandoc 1 .
149: This may also be invoked with
150: .Cm centre .
151: .It Cm delim
152: Accepts a two-character argument.
153: This option is not supported by
154: .Xr mandoc 1 .
155: .It Cm expand
156: This option is not supported by
157: .Xr mandoc 1 .
158: .It Cm box
159: Draw a single-line box around the table.
160: This may also be invoked with
161: .Cm frame .
162: .It Cm doublebox
163: Draw a double-line box around the table.
164: This may also be invoked with
165: .Cm doubleframe .
166: .It Cm allbox
167: This option is not supported by
168: .Xr mandoc 1 .
169: .It Cm tab
170: Accepts a single-character argument.
1.3 kristaps 171: This character is used as a delimiter between data cells, which otherwise
1.1 kristaps 172: defaults to the tab character.
173: .It Cm linesize
174: Accepts a natural number (all digits).
175: This option is not supported by
176: .Xr mandoc 1 .
177: .It Cm nokeep
178: This option is not supported by
179: .Xr mandoc 1 .
180: .It Cm decimalpoint
181: Accepts a single-character argument.
182: This character will be used as the decimal point with the
183: .Cm n
184: layout key.
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:
1.19 schwarze 200: .Bl -tag -width 2n
1.1 kristaps 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
1.12 schwarze 212: Horizontally span columns from the last
213: .No non- Ns Cm s
1.9 kristaps 214: data cell.
1.8 kristaps 215: It is an error if spanning columns follow a
216: .Cm \-
217: or
218: .Cm \(ba
219: cell, or come first.
1.9 kristaps 220: This option is not supported by
221: .Xr mandoc 1 .
1.1 kristaps 222: .It Cm a
1.7 kristaps 223: Left-justify a literal string and pad with one space.
1.1 kristaps 224: .It Cm ^
1.12 schwarze 225: Vertically span rows from the last
226: .No non- Ns Cm ^
1.9 kristaps 227: data cell.
228: It is an error to invoke a vertical span on the first layout row.
1.10 kristaps 229: Unlike a horizontal spanner, you must specify an empty cell (if it not
230: empty, the data is discarded) in the corresponding data cell.
1.1 kristaps 231: .It Cm \-
232: Replace the data cell (its contents will be lost) with a single
233: horizontal line.
234: This may also be invoked with
235: .Cm _ .
236: .It Cm =
237: Replace the data cell (its contents will be lost) with a double
238: horizontal line.
239: .It Cm \(ba
240: Emit a vertical bar instead of data.
241: .It Cm \(ba\(ba
242: Emit a double-vertical bar instead of data.
243: .El
244: .Pp
245: Keys may be followed by a set of modifiers.
246: A modifier is either a modifier key or a natural number for specifying
1.5 kristaps 247: the minimum width of a column.
1.1 kristaps 248: The following case-insensitive modifier keys are available:
1.19 schwarze 249: .Bl -tag -width 2n
250: .It Cm b
251: Use a bold font for the contents of this column.
1.20 schwarze 252: .It Cm e
253: Make this column wider to match the maximum width
254: of any other column also having the
255: .Cm e
256: modifier.
1.19 schwarze 257: .It Cm f
258: The next character selects the font to use for this column.
259: See the
260: .Xr roff 7
261: manual for supported one-character font names.
262: .It Cm i
263: Use an italic font for the contents of this column.
1.20 schwarze 264: .It Cm x
265: After determining the width of all other columns, distribute the
266: rest of the line length among all columns having the
267: .Cm x
268: modifier.
269: .It Cm z
270: Do not use this cell for determining the width of this column.
1.19 schwarze 271: .El
272: .Pp
273: The modifiers
274: .Cm d ,
1.1 kristaps 275: .Cm t ,
1.19 schwarze 276: .Cm u ,
1.16 kristaps 277: and
1.20 schwarze 278: .Cm w
1.19 schwarze 279: are ignored by
1.1 kristaps 280: .Xr mandoc 1 .
1.5 kristaps 281: .Pp
282: For example, the following layout specifies a centre-justified column of
283: minimum width 10, followed by vertical bar, followed by a left-justified
1.19 schwarze 284: column of minimum width 10, another vertical bar, then a column using
285: bold font justified about the decimal point in numbers:
1.5 kristaps 286: .Pp
1.19 schwarze 287: .Dl c10 | l10 | nfB
1.2 kristaps 288: .Ss Data
1.1 kristaps 289: The data section follows the last layout row.
290: By default, cells in a data section are delimited by a tab.
291: This behaviour may be changed with the
292: .Cm tab
293: option.
294: If
295: .Cm _
296: or
297: .Cm =
298: is specified, a single or double line, respectively, is drawn across the
299: data field.
300: If
301: .Cm \e-
302: or
303: .Cm \e=
1.3 kristaps 304: is specified, a line is drawn within the data field (i.e. terminating
1.1 kristaps 305: within the cell and not draw to the border).
306: If the last cell of a line is
307: .Cm T{ ,
308: all subsequent lines are included as part of the cell until
309: .Cm T}
1.4 kristaps 310: is specified as its own data cell.
311: It may then be followed by a tab
312: .Pq or as designated by Cm tab
313: or an end-of-line to terminate the row.
1.1 kristaps 314: .Sh COMPATIBILITY
315: This section documents compatibility between mandoc and other
316: .Nm
317: implementations, at this time limited to GNU tbl.
318: .Pp
319: .Bl -dash -compact
320: .It
321: In GNU tbl, comments and macros are disallowed prior to the data block
322: of a table.
323: The
324: .Xr mandoc 1
325: implementation allows them.
326: .El
327: .Sh SEE ALSO
328: .Xr mandoc 1 ,
1.3 kristaps 329: .Xr man 7 ,
1.1 kristaps 330: .Xr mandoc_char 7 ,
1.3 kristaps 331: .Xr mdoc 7 ,
332: .Xr roff 7
1.1 kristaps 333: .Rs
334: .%A M. E. Lesk
335: .%T Tbl\(emA Program to Format Tables
336: .%D June 11, 1976
337: .Re
338: .Sh HISTORY
339: The tbl utility, a preprocessor for troff, was originally written by M.
340: E. Lesk at Bell Labs in 1975.
341: The GNU reimplementation of tbl, part of the groff package, was released
342: in 1990 by James Clark.
343: A standalone tbl implementation was written by Kristaps Dzonsons in
344: 2010.
345: This formed the basis of the implementation that is part of the
346: .Xr mandoc 1
347: utility.
348: .Sh AUTHORS
1.14 kristaps 349: This
1.1 kristaps 350: .Nm
351: reference was written by
1.17 schwarze 352: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
CVSweb