Annotation of mandoc/tbl.7, Revision 1.20
1.20 ! schwarze 1: .\" $Id: tbl.7,v 1.19 2014/10/13 23:31:46 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.20 ! schwarze 18: .Dd $Mdocdate: October 13 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.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.
1.20 ! schwarze 251: .It Cm e
! 252: Make this column wider to match the maximum width
! 253: of any other column also having the
! 254: .Cm e
! 255: modifier.
1.19 schwarze 256: .It Cm f
257: The next character selects the font to use for this column.
258: See the
259: .Xr roff 7
260: manual for supported one-character font names.
261: .It Cm i
262: Use an italic font for the contents of this column.
1.20 ! schwarze 263: .It Cm x
! 264: After determining the width of all other columns, distribute the
! 265: rest of the line length among all columns having the
! 266: .Cm x
! 267: modifier.
! 268: .It Cm z
! 269: Do not use this cell for determining the width of this column.
1.19 schwarze 270: .El
271: .Pp
272: The modifiers
273: .Cm d ,
1.1 kristaps 274: .Cm t ,
1.19 schwarze 275: .Cm u ,
1.16 kristaps 276: and
1.20 ! schwarze 277: .Cm w
1.19 schwarze 278: are ignored by
1.1 kristaps 279: .Xr mandoc 1 .
1.5 kristaps 280: .Pp
281: For example, the following layout specifies a centre-justified column of
282: minimum width 10, followed by vertical bar, followed by a left-justified
1.19 schwarze 283: column of minimum width 10, another vertical bar, then a column using
284: bold font justified about the decimal point in numbers:
1.5 kristaps 285: .Pp
1.19 schwarze 286: .Dl c10 | l10 | nfB
1.2 kristaps 287: .Ss Data
1.1 kristaps 288: The data section follows the last layout row.
289: By default, cells in a data section are delimited by a tab.
290: This behaviour may be changed with the
291: .Cm tab
292: option.
293: If
294: .Cm _
295: or
296: .Cm =
297: is specified, a single or double line, respectively, is drawn across the
298: data field.
299: If
300: .Cm \e-
301: or
302: .Cm \e=
1.3 kristaps 303: is specified, a line is drawn within the data field (i.e. terminating
1.1 kristaps 304: within the cell and not draw to the border).
305: If the last cell of a line is
306: .Cm T{ ,
307: all subsequent lines are included as part of the cell until
308: .Cm T}
1.4 kristaps 309: is specified as its own data cell.
310: It may then be followed by a tab
311: .Pq or as designated by Cm tab
312: or an end-of-line to terminate the row.
1.1 kristaps 313: .Sh COMPATIBILITY
314: This section documents compatibility between mandoc and other
315: .Nm
316: implementations, at this time limited to GNU tbl.
317: .Pp
318: .Bl -dash -compact
319: .It
320: In GNU tbl, comments and macros are disallowed prior to the data block
321: of a table.
322: The
323: .Xr mandoc 1
324: implementation allows them.
325: .El
326: .Sh SEE ALSO
327: .Xr mandoc 1 ,
1.3 kristaps 328: .Xr man 7 ,
1.1 kristaps 329: .Xr mandoc_char 7 ,
1.3 kristaps 330: .Xr mdoc 7 ,
331: .Xr roff 7
1.1 kristaps 332: .Rs
333: .%A M. E. Lesk
334: .%T Tbl\(emA Program to Format Tables
335: .%D June 11, 1976
336: .Re
337: .Sh HISTORY
338: The tbl utility, a preprocessor for troff, was originally written by M.
339: E. Lesk at Bell Labs in 1975.
340: The GNU reimplementation of tbl, part of the groff package, was released
341: in 1990 by James Clark.
342: A standalone tbl implementation was written by Kristaps Dzonsons in
343: 2010.
344: This formed the basis of the implementation that is part of the
345: .Xr mandoc 1
346: utility.
347: .Sh AUTHORS
1.14 kristaps 348: This
1.1 kristaps 349: .Nm
350: reference was written by
1.17 schwarze 351: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tbl.7 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc