Annotation of mandoc/tbl.7, Revision 1.19
1.19 ! schwarze 1: .\" $Id: tbl.7,v 1.18 2013/09/16 22:39:19 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.19 ! schwarze 18: .Dd $Mdocdate: September 16 2013 $
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.1 kristaps 138: If the first line does not have a terminating semicolon, it is assumed
1.2 kristaps 139: that no options are specified and instead a
140: .Sx Layout
141: is processed.
1.3 kristaps 142: Some options accept arguments enclosed by parenthesis.
1.1 kristaps 143: The following case-insensitive options are available:
144: .Bl -tag -width Ds
145: .It Cm center
146: This option is not supported by
147: .Xr mandoc 1 .
148: This may also be invoked with
149: .Cm centre .
150: .It Cm delim
151: Accepts a two-character argument.
152: This option is not supported by
153: .Xr mandoc 1 .
154: .It Cm expand
155: This option is not supported by
156: .Xr mandoc 1 .
157: .It Cm box
158: Draw a single-line box around the table.
159: This may also be invoked with
160: .Cm frame .
161: .It Cm doublebox
162: Draw a double-line box around the table.
163: This may also be invoked with
164: .Cm doubleframe .
165: .It Cm allbox
166: This option is not supported by
167: .Xr mandoc 1 .
168: .It Cm tab
169: Accepts a single-character argument.
1.3 kristaps 170: This character is used as a delimiter between data cells, which otherwise
1.1 kristaps 171: defaults to the tab character.
172: .It Cm linesize
173: Accepts a natural number (all digits).
174: This option is not supported by
175: .Xr mandoc 1 .
176: .It Cm nokeep
177: This option is not supported by
178: .Xr mandoc 1 .
179: .It Cm decimalpoint
180: Accepts a single-character argument.
181: This character will be used as the decimal point with the
182: .Cm n
183: layout key.
184: .It Cm nospaces
185: This option is not supported by
186: .Xr mandoc 1 .
187: .El
1.2 kristaps 188: .Ss Layout
189: The table layout follows
190: .Sx Options
191: or a
192: .Sq \&T&
193: macro invocation.
1.1 kristaps 194: Layout specifies how data rows are displayed on output.
195: Each layout line corresponds to a line of data; the last layout line
196: applies to all remaining data lines.
197: Layout lines may also be separated by a comma.
198: Each layout cell consists of one of the following case-insensitive keys:
1.19 ! schwarze 199: .Bl -tag -width 2n
1.1 kristaps 200: .It Cm c
201: Centre a literal string within its column.
202: .It Cm r
203: Right-justify a literal string within its column.
204: .It Cm l
205: Left-justify a literal string within its column.
206: .It Cm n
1.6 kristaps 207: Justify a number around its last decimal point.
1.1 kristaps 208: If the decimal point is not found on the number, it's assumed to trail
209: the number.
210: .It Cm s
1.12 schwarze 211: Horizontally span columns from the last
212: .No non- Ns Cm s
1.9 kristaps 213: data cell.
1.8 kristaps 214: It is an error if spanning columns follow a
215: .Cm \-
216: or
217: .Cm \(ba
218: cell, or come first.
1.9 kristaps 219: This option is not supported by
220: .Xr mandoc 1 .
1.1 kristaps 221: .It Cm a
1.7 kristaps 222: Left-justify a literal string and pad with one space.
1.1 kristaps 223: .It Cm ^
1.12 schwarze 224: Vertically span rows from the last
225: .No non- Ns Cm ^
1.9 kristaps 226: data cell.
227: It is an error to invoke a vertical span on the first layout row.
1.10 kristaps 228: Unlike a horizontal spanner, you must specify an empty cell (if it not
229: empty, the data is discarded) in the corresponding data cell.
1.1 kristaps 230: .It Cm \-
231: Replace the data cell (its contents will be lost) with a single
232: horizontal line.
233: This may also be invoked with
234: .Cm _ .
235: .It Cm =
236: Replace the data cell (its contents will be lost) with a double
237: horizontal line.
238: .It Cm \(ba
239: Emit a vertical bar instead of data.
240: .It Cm \(ba\(ba
241: Emit a double-vertical bar instead of data.
242: .El
243: .Pp
244: Keys may be followed by a set of modifiers.
245: A modifier is either a modifier key or a natural number for specifying
1.5 kristaps 246: the minimum width of a column.
1.1 kristaps 247: The following case-insensitive modifier keys are available:
1.19 ! schwarze 248: .Bl -tag -width 2n
! 249: .It Cm b
! 250: Use a bold font for the contents of this column.
! 251: .It Cm f
! 252: The next character selects the font to use for this column.
! 253: See the
! 254: .Xr roff 7
! 255: manual for supported one-character font names.
! 256: .It Cm i
! 257: Use an italic font for the contents of this column.
! 258: .El
! 259: .Pp
! 260: The modifiers
! 261: .Cm d ,
1.1 kristaps 262: .Cm e ,
1.19 ! schwarze 263: .Cm r ,
1.1 kristaps 264: .Cm t ,
1.19 ! schwarze 265: .Cm u ,
1.16 kristaps 266: and
1.19 ! schwarze 267: .Cm z
! 268: are ignored by
1.1 kristaps 269: .Xr mandoc 1 .
1.5 kristaps 270: .Pp
271: For example, the following layout specifies a centre-justified column of
272: minimum width 10, followed by vertical bar, followed by a left-justified
1.19 ! schwarze 273: column of minimum width 10, another vertical bar, then a column using
! 274: bold font justified about the decimal point in numbers:
1.5 kristaps 275: .Pp
1.19 ! schwarze 276: .Dl c10 | l10 | nfB
1.2 kristaps 277: .Ss Data
1.1 kristaps 278: The data section follows the last layout row.
279: By default, cells in a data section are delimited by a tab.
280: This behaviour may be changed with the
281: .Cm tab
282: option.
283: If
284: .Cm _
285: or
286: .Cm =
287: is specified, a single or double line, respectively, is drawn across the
288: data field.
289: If
290: .Cm \e-
291: or
292: .Cm \e=
1.3 kristaps 293: is specified, a line is drawn within the data field (i.e. terminating
1.1 kristaps 294: within the cell and not draw to the border).
295: If the last cell of a line is
296: .Cm T{ ,
297: all subsequent lines are included as part of the cell until
298: .Cm T}
1.4 kristaps 299: is specified as its own data cell.
300: It may then be followed by a tab
301: .Pq or as designated by Cm tab
302: or an end-of-line to terminate the row.
1.1 kristaps 303: .Sh COMPATIBILITY
304: This section documents compatibility between mandoc and other
305: .Nm
306: implementations, at this time limited to GNU tbl.
307: .Pp
308: .Bl -dash -compact
309: .It
310: In GNU tbl, comments and macros are disallowed prior to the data block
311: of a table.
312: The
313: .Xr mandoc 1
314: implementation allows them.
315: .El
316: .Sh SEE ALSO
317: .Xr mandoc 1 ,
1.3 kristaps 318: .Xr man 7 ,
1.1 kristaps 319: .Xr mandoc_char 7 ,
1.3 kristaps 320: .Xr mdoc 7 ,
321: .Xr roff 7
1.1 kristaps 322: .Rs
323: .%A M. E. Lesk
324: .%T Tbl\(emA Program to Format Tables
325: .%D June 11, 1976
326: .Re
327: .Sh HISTORY
328: The tbl utility, a preprocessor for troff, was originally written by M.
329: E. Lesk at Bell Labs in 1975.
330: The GNU reimplementation of tbl, part of the groff package, was released
331: in 1990 by James Clark.
332: A standalone tbl implementation was written by Kristaps Dzonsons in
333: 2010.
334: This formed the basis of the implementation that is part of the
335: .Xr mandoc 1
336: utility.
337: .Sh AUTHORS
1.14 kristaps 338: This
1.1 kristaps 339: .Nm
340: reference was written by
1.17 schwarze 341: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
CVSweb