Annotation of mandoc/tbl.7, Revision 1.29
1.29 ! schwarze 1: .\" $Id: tbl.7,v 1.28 2017/06/28 00:59:57 schwarze Exp $
1.1 kristaps 2: .\"
1.12 schwarze 3: .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.27 schwarze 4: .\" Copyright (c) 2014, 2015, 2017 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.29 ! schwarze 18: .Dd $Mdocdate: June 28 2017 $
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
1.28 schwarze 27: language formats tables.
1.1 kristaps 28: It is used within
29: .Xr mdoc 7
30: and
31: .Xr man 7
1.28 schwarze 32: pages.
1.1 kristaps 33: This manual describes the subset of the
34: .Nm
35: language accepted by the
36: .Xr mandoc 1
37: utility.
38: .Pp
1.28 schwarze 39: Each table is started with a
1.1 kristaps 40: .Xr roff 7
1.28 schwarze 41: .Ic \&TS
42: macro, consist of at most one line of
43: .Sx Options ,
44: one or more
1.2 kristaps 45: .Sx Layout
1.28 schwarze 46: lines, one or more
47: .Sx Data
48: lines, and ends with a
49: .Ic \&TE
50: macro.
1.1 kristaps 51: All input must be 7-bit ASCII.
1.2 kristaps 52: .Ss Options
1.28 schwarze 53: If the first input line of a table ends with a semicolon, it contains
54: case-insensitive options separated by spaces, tabs, or commas.
55: Otherwise, it is interpreted as the first
1.2 kristaps 56: .Sx Layout
1.28 schwarze 57: line.
58: .Pp
59: The following options are available.
60: Some of them require arguments enclosed in parentheses:
1.1 kristaps 61: .Bl -tag -width Ds
1.23 schwarze 62: .It Cm allbox
63: Draw a single-line box around each table cell.
64: .It Cm box
65: Draw a single-line box around the table.
66: For GNU compatibility, this may also be invoked with
67: .Cm frame .
1.1 kristaps 68: .It Cm center
1.23 schwarze 69: Center the table instead of left-adjusting it.
70: For GNU compatibility, this may also be invoked with
1.1 kristaps 71: .Cm centre .
1.23 schwarze 72: .It Cm decimalpoint
73: Use the single-character argument as the decimal point with the
74: .Cm n
75: layout key.
76: This is a GNU extension.
1.1 kristaps 77: .It Cm delim
1.23 schwarze 78: Use the two characters of the argument as
79: .Xr eqn 7
80: delimiters.
81: Currently unsupported.
1.1 kristaps 82: .It Cm doublebox
83: Draw a double-line box around the table.
1.23 schwarze 84: For GNU compatibility, this may also be invoked with
1.1 kristaps 85: .Cm doubleframe .
1.23 schwarze 86: .It Cm expand
87: Increase the width of the table to the current line length.
88: Currently ignored.
1.1 kristaps 89: .It Cm linesize
1.23 schwarze 90: Draw lines with the point size given by the unsigned integer argument.
91: Currently ignored.
1.1 kristaps 92: .It Cm nokeep
1.23 schwarze 93: Allow page breaks within the table.
94: This is a GNU extension and currently ignored.
1.1 kristaps 95: .It Cm nospaces
1.23 schwarze 96: Ignore leading and trailing spaces in data cells.
97: This is a GNU extension and currently ignored.
98: .It Cm nowarn
99: Suppress warnings about tables exceeding the current line length.
100: This is a GNU extension and currently ignored.
101: .It Cm tab
102: Use the single-character argument as a delimiter between data cells.
1.28 schwarze 103: By default, the horizontal tabulator character is used.
1.1 kristaps 104: .El
1.2 kristaps 105: .Ss Layout
1.28 schwarze 106: The table layout follows an
1.2 kristaps 107: .Sx Options
1.28 schwarze 108: line or a
109: .Xr roff 7
110: .Ic \&TS
111: or
112: .Ic \&T&
113: macro.
114: Each layout line specifies how one line of
115: .Sx Data
116: is formatted.
117: The last layout line ends with a full stop.
118: It also applies to all remaining data lines.
119: Multiple layout lines can be joined by commas on a single physical
120: input line.
121: .Pp
122: Each layout line consists of one or more layout cell specifications,
123: optionally separated by whitespace.
124: The following case-insensitive key characters start a new cell
125: specification:
1.19 schwarze 126: .Bl -tag -width 2n
1.1 kristaps 127: .It Cm c
1.28 schwarze 128: Center the string in this cell.
1.1 kristaps 129: .It Cm r
1.28 schwarze 130: Right-justify the string in this cell.
1.1 kristaps 131: .It Cm l
1.28 schwarze 132: Left-justify the string in this cell.
1.1 kristaps 133: .It Cm n
1.6 kristaps 134: Justify a number around its last decimal point.
1.28 schwarze 135: If no decimal point is found in the number,
136: it is assumed to trail the number.
1.1 kristaps 137: .It Cm s
1.12 schwarze 138: Horizontally span columns from the last
1.28 schwarze 139: .Pf non- Cm s
140: layout cell.
141: It is an error if a column span follows a
142: .Cm _
1.8 kristaps 143: or
1.28 schwarze 144: .Cm =
145: cell, or comes first on a layout line.
146: The combined cell as a whole consumes only one cell
147: of the corresponding data line.
1.1 kristaps 148: .It Cm a
1.28 schwarze 149: Left-justify a string and pad with one space.
1.1 kristaps 150: .It Cm ^
1.12 schwarze 151: Vertically span rows from the last
1.28 schwarze 152: .Pf non- Cm ^
153: layout cell.
154: It is an error to invoke a vertical span on the first layout line.
155: Unlike a horizontal span, a vertical span consumes a data cell
156: and discards the content.
157: .It Cm _
158: Draw a single horizontal line in this cell.
159: This consumes a data cell and discards the content.
160: It may also be invoked with
161: .Cm \- .
1.1 kristaps 162: .It Cm =
1.28 schwarze 163: Draw a double horizontal line in this cell.
164: This consumes a data cell and discards the content.
1.1 kristaps 165: .El
166: .Pp
1.28 schwarze 167: Each cell key may be followed by zero or more of the following
168: case-insensitive modifiers:
1.19 schwarze 169: .Bl -tag -width 2n
170: .It Cm b
1.28 schwarze 171: Use a bold font for the contents of this cell.
1.24 schwarze 172: .It Cm d
1.28 schwarze 173: Move content down to the last row of this vertical span.
1.24 schwarze 174: Currently ignored.
1.20 schwarze 175: .It Cm e
176: Make this column wider to match the maximum width
177: of any other column also having the
178: .Cm e
179: modifier.
1.19 schwarze 180: .It Cm f
1.28 schwarze 181: The next character selects the font to use for this cell.
1.19 schwarze 182: See the
183: .Xr roff 7
184: manual for supported one-character font names.
185: .It Cm i
1.28 schwarze 186: Use an italic font for the contents of this cell.
1.24 schwarze 187: .It Cm m
188: Specify a cell start macro.
189: This is a GNU extension and currently unsupported.
190: .It Cm p
191: Set the point size to the following unsigned argument,
192: or change it by the following signed argument.
193: Currently ignored.
194: .It Cm v
195: Set the vertical line spacing to the following unsigned argument,
196: or change it by the following signed argument.
197: Currently ignored.
198: .It Cm t
1.28 schwarze 199: Do not vertically center content in this vertical span,
200: leave it in the top row.
1.24 schwarze 201: Currently ignored.
202: .It Cm u
1.28 schwarze 203: Move cell content up by half a table row.
1.24 schwarze 204: Currently ignored.
205: .It Cm w
1.28 schwarze 206: Specify a minimum column width.
1.20 schwarze 207: .It Cm x
208: After determining the width of all other columns, distribute the
209: rest of the line length among all columns having the
210: .Cm x
211: modifier.
212: .It Cm z
213: Do not use this cell for determining the width of this column.
1.28 schwarze 214: .It Cm \&|
215: Draw a single vertical line to the right of this cell.
216: .It Cm ||
217: Draw a double vertical line to the right of this cell.
1.19 schwarze 218: .El
1.5 kristaps 219: .Pp
1.28 schwarze 220: If a modifier consists of decimal digits,
221: it specifies a minimum spacing in units of
222: .Cm n
223: between this column and the next column to the right.
224: The default is 3.
225: If there is a vertical line, it is drawn inside the spacing.
1.2 kristaps 226: .Ss Data
1.28 schwarze 227: The data section follows the last
228: .Sx Layout
229: line.
230: Each data line consists of one or more data cells, delimited by
1.1 kristaps 231: .Cm tab
1.28 schwarze 232: characters.
233: .Pp
234: If a data cells contains only the single character
235: .Ql _
236: or
237: .Ql = ,
238: a single or double horizontal line is drawn across the cell,
239: joining its neighbours.
240: If a data cells contains only the two character sequence
241: .Ql \e_
242: or
243: .Ql \e= ,
244: a single or double horizontal line is drawn inside the cell,
245: not joining its neighbours.
246: If a data line contains nothing but the single character
247: .Ql _
1.1 kristaps 248: or
1.28 schwarze 249: .Ql = ,
250: a horizontal line across the whole table is inserted
251: without consuming a layout row.
252: .Pp
253: In place of any data cell, a text block can be used.
254: It starts with
255: .Ic \&T{
256: at the end of a physical input line.
257: Input line breaks inside the text block
258: neither end the text block nor its data cell.
259: It only ends if
260: .Ic \&T}
261: occurs at the beginning of a physical input line and is followed
262: by an end-of-cell indicator.
263: If the
264: .Ic \&T}
265: is followed by the end of the physical input line, the text block,
266: the data cell, and the data line ends at this point.
267: If the
268: .Ic \&T}
269: is followed by the
270: .Cm tab
271: character, only the text block and the data cell end,
272: but the data line continues with the data cell following the
273: .Cm tab
274: character.
1.1 kristaps 275: If
1.28 schwarze 276: .Ic \&T}
277: is followed by any other character, it does not end the text block,
278: which instead continues to the following physical input line.
279: .Sh EXAMPLES
280: String justification and font selection:
281: .Bd -literal -offset indent
282: \&.TS
283: rb c lb
284: r ci l.
285: r center l
286: ri ce le
287: right c left
288: \&.TE
289: .Ed
290: .Bd -filled -offset indent
291: .TS
292: rb c lb
293: r ci l.
294: r center l
295: ri ce le
296: right c left
297: .TE
298: .Ed
299: .Pp
300: Some ports in
301: .Ox 6.1
302: to show number alignment and line drawing:
303: .Bd -literal -offset indent
304: \&.TS
305: box tab(:);
306: r| l
307: r n.
308: software:version
309: _
310: AFL:2.39b
311: Mutt:1.8.0
312: Ruby:1.8.7.374
313: TeX Live:2015
314: \&.TE
315: .Ed
316: .Bd -filled -offset indent
317: .TS
318: box tab(:);
319: r| l
320: r n.
321: software:version
322: _
323: AFL:2.39b
324: Mutt:1.8.0
325: Ruby:1.8.7.374
326: TeX Live:2015
327: .TE
328: .Ed
329: .sp 2v
330: Spans and skipping width calculations:
331: .Bd -literal -offset indent
332: \&.TS
333: box tab(:);
334: lz s | rt
335: lt| cb| ^
336: ^ | rz s.
337: left:r
338: l:center:
339: :right
340: \&.TE
341: .Ed
342: .Bd -filled -offset indent
343: .TS
344: box tab(:);
345: lz s | rt
346: lt| cb| ^
347: ^ | rz s.
348: left:r
349: l:center:
350: :right
351: .TE
352: .Ed
353: .sp 2v
354: Text blocks, specifying spacings and specifying and equalizing
355: column widths, putting lines into individual cells, and overriding
356: .Cm allbox :
357: .Bd -literal -offset indent
358: \&.TS
359: allbox tab(:);
360: le le||7 lw10.
361: The fourth line:_:line 1
362: of this column:=:line 2
363: determines:\_:line 3
364: the column width.:T{
365: This text is too wide to fit into a column of width 17.
366: T}:line 4
367: T{
368: No break here.
369: T}::line 5
370: \&.TE
371: .Ed
372: .Bd -filled -offset indent
373: .TS
374: allbox tab(:);
375: le le||7 lw10.
376: The fourth line:_:line 1
377: of this column:=:line 2
378: determines:\_:line 3
379: the column width.:T{
380: This text is too wide to fit into a column of width 17.
381: T}:line 4
382: T{
383: No break here.
384: T}::line 5
385: .TE
386: .Ed
387: .sp 2v
388: These examples were constructed to demonstrate many
389: .Nm
390: features in a compact way.
391: In real manual pages, keep tables as simple as possible:
392: Like that, they usually look better, are less fragile, and more portable.
1.1 kristaps 393: .Sh COMPATIBILITY
394: The
395: .Xr mandoc 1
1.26 schwarze 396: implementation of
397: .Nm
398: doesn't support
399: .Xr mdoc 7
400: and
401: .Xr man 7
402: macros and
403: .Xr eqn 7
404: equations inside tables.
1.1 kristaps 405: .Sh SEE ALSO
406: .Xr mandoc 1 ,
1.3 kristaps 407: .Xr man 7 ,
1.1 kristaps 408: .Xr mandoc_char 7 ,
1.3 kristaps 409: .Xr mdoc 7 ,
410: .Xr roff 7
1.1 kristaps 411: .Rs
412: .%A M. E. Lesk
413: .%T Tbl\(emA Program to Format Tables
414: .%D June 11, 1976
415: .Re
416: .Sh HISTORY
417: The tbl utility, a preprocessor for troff, was originally written by M.
418: E. Lesk at Bell Labs in 1975.
419: The GNU reimplementation of tbl, part of the groff package, was released
420: in 1990 by James Clark.
421: A standalone tbl implementation was written by Kristaps Dzonsons in
422: 2010.
1.29 ! schwarze 423: This formed the basis of the implementation that first appeared in
! 424: .Ox 4.9
! 425: as a part of the
1.1 kristaps 426: .Xr mandoc 1
427: utility.
428: .Sh AUTHORS
1.14 kristaps 429: This
1.1 kristaps 430: .Nm
431: reference was written by
1.28 schwarze 432: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
433: and
434: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
CVSweb