Annotation of mandoc/tbl.7, Revision 1.36
1.36 ! schwarze 1: .\" $Id: tbl.7,v 1.35 2021/08/10 12:55:04 schwarze Exp $
1.1 kristaps 2: .\"
1.12 schwarze 3: .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.33 schwarze 4: .\" Copyright (c) 2014,2015,2017,2018,2019 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.36 ! schwarze 18: .Dd $Mdocdate: August 10 2021 $
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.
1.36 ! schwarze 97: This is a GNU extension.
1.23 schwarze 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.30 schwarze 150: .It Cm \(ha
1.12 schwarze 151: Vertically span rows from the last
1.30 schwarze 152: .Pf non- Cm \(ha
1.28 schwarze 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.35 schwarze 181: The next one or two characters select the font to use for this cell.
182: One-character font names must be followed by a blank or period.
1.19 schwarze 183: See the
184: .Xr roff 7
1.35 schwarze 185: manual for supported font names.
1.19 schwarze 186: .It Cm i
1.28 schwarze 187: Use an italic font for the contents of this cell.
1.24 schwarze 188: .It Cm m
189: Specify a cell start macro.
190: This is a GNU extension and currently unsupported.
191: .It Cm p
192: Set the point size to the following unsigned argument,
193: or change it by the following signed argument.
194: Currently ignored.
195: .It Cm v
196: Set the vertical line spacing to the following unsigned argument,
197: or change it by the following signed argument.
198: Currently ignored.
199: .It Cm t
1.28 schwarze 200: Do not vertically center content in this vertical span,
201: leave it in the top row.
1.24 schwarze 202: Currently ignored.
203: .It Cm u
1.28 schwarze 204: Move cell content up by half a table row.
1.24 schwarze 205: Currently ignored.
206: .It Cm w
1.28 schwarze 207: Specify a minimum column width.
1.20 schwarze 208: .It Cm x
209: After determining the width of all other columns, distribute the
210: rest of the line length among all columns having the
211: .Cm x
212: modifier.
213: .It Cm z
214: Do not use this cell for determining the width of this column.
1.28 schwarze 215: .It Cm \&|
216: Draw a single vertical line to the right of this cell.
217: .It Cm ||
218: Draw a double vertical line to the right of this cell.
1.19 schwarze 219: .El
1.5 kristaps 220: .Pp
1.28 schwarze 221: If a modifier consists of decimal digits,
222: it specifies a minimum spacing in units of
223: .Cm n
224: between this column and the next column to the right.
225: The default is 3.
226: If there is a vertical line, it is drawn inside the spacing.
1.2 kristaps 227: .Ss Data
1.28 schwarze 228: The data section follows the last
229: .Sx Layout
230: line.
231: Each data line consists of one or more data cells, delimited by
1.1 kristaps 232: .Cm tab
1.28 schwarze 233: characters.
234: .Pp
1.30 schwarze 235: If a data cell contains only the two bytes
236: .Ql \e\(ha ,
237: the cell above spans to this row, as if the layout specification
238: of this cell were
239: .Cm \(ha .
240: .Pp
241: If a data cell contains only the single character
1.28 schwarze 242: .Ql _
243: or
244: .Ql = ,
245: a single or double horizontal line is drawn across the cell,
246: joining its neighbours.
1.32 schwarze 247: If a data cell contains only the two character sequence
1.28 schwarze 248: .Ql \e_
249: or
250: .Ql \e= ,
251: a single or double horizontal line is drawn inside the cell,
252: not joining its neighbours.
253: If a data line contains nothing but the single character
254: .Ql _
1.1 kristaps 255: or
1.28 schwarze 256: .Ql = ,
257: a horizontal line across the whole table is inserted
258: without consuming a layout row.
259: .Pp
260: In place of any data cell, a text block can be used.
261: It starts with
262: .Ic \&T{
263: at the end of a physical input line.
264: Input line breaks inside the text block
265: neither end the text block nor its data cell.
266: It only ends if
267: .Ic \&T}
268: occurs at the beginning of a physical input line and is followed
269: by an end-of-cell indicator.
270: If the
271: .Ic \&T}
272: is followed by the end of the physical input line, the text block,
273: the data cell, and the data line ends at this point.
274: If the
275: .Ic \&T}
276: is followed by the
277: .Cm tab
278: character, only the text block and the data cell end,
279: but the data line continues with the data cell following the
280: .Cm tab
281: character.
1.1 kristaps 282: If
1.28 schwarze 283: .Ic \&T}
284: is followed by any other character, it does not end the text block,
285: which instead continues to the following physical input line.
286: .Sh EXAMPLES
287: String justification and font selection:
288: .Bd -literal -offset indent
289: \&.TS
290: rb c lb
291: r ci l.
292: r center l
293: ri ce le
294: right c left
295: \&.TE
296: .Ed
297: .Bd -filled -offset indent
298: .TS
299: rb c lb
300: r ci l.
301: r center l
302: ri ce le
303: right c left
304: .TE
305: .Ed
306: .Pp
307: Some ports in
308: .Ox 6.1
309: to show number alignment and line drawing:
310: .Bd -literal -offset indent
311: \&.TS
312: box tab(:);
313: r| l
314: r n.
315: software:version
316: _
317: AFL:2.39b
318: Mutt:1.8.0
319: Ruby:1.8.7.374
320: TeX Live:2015
321: \&.TE
322: .Ed
323: .Bd -filled -offset indent
324: .TS
325: box tab(:);
326: r| l
327: r n.
328: software:version
329: _
330: AFL:2.39b
331: Mutt:1.8.0
332: Ruby:1.8.7.374
1.31 schwarze 333: TeX Live:2015
1.28 schwarze 334: .TE
335: .Ed
336: .sp 2v
337: Spans and skipping width calculations:
338: .Bd -literal -offset indent
339: \&.TS
340: box tab(:);
341: lz s | rt
1.30 schwarze 342: lt| cb| \(ha
343: \(ha | rz s.
1.28 schwarze 344: left:r
345: l:center:
346: :right
347: \&.TE
348: .Ed
349: .Bd -filled -offset indent
350: .TS
351: box tab(:);
352: lz s | rt
353: lt| cb| ^
354: ^ | rz s.
355: left:r
356: l:center:
357: :right
358: .TE
359: .Ed
360: .sp 2v
361: Text blocks, specifying spacings and specifying and equalizing
362: column widths, putting lines into individual cells, and overriding
363: .Cm allbox :
364: .Bd -literal -offset indent
365: \&.TS
366: allbox tab(:);
367: le le||7 lw10.
368: The fourth line:_:line 1
369: of this column:=:line 2
370: determines:\_:line 3
371: the column width.:T{
372: This text is too wide to fit into a column of width 17.
373: T}:line 4
374: T{
375: No break here.
376: T}::line 5
377: \&.TE
378: .Ed
379: .Bd -filled -offset indent
380: .TS
381: allbox tab(:);
382: le le||7 lw10.
383: The fourth line:_:line 1
384: of this column:=:line 2
385: determines:\_:line 3
386: the column width.:T{
387: This text is too wide to fit into a column of width 17.
388: T}:line 4
389: T{
390: No break here.
391: T}::line 5
392: .TE
393: .Ed
394: .sp 2v
395: These examples were constructed to demonstrate many
396: .Nm
397: features in a compact way.
1.34 schwarze 398: In real manual pages, keep tables as simple as possible.
399: They usually look better, are less fragile, and are more portable.
1.1 kristaps 400: .Sh COMPATIBILITY
401: The
402: .Xr mandoc 1
1.26 schwarze 403: implementation of
404: .Nm
405: doesn't support
406: .Xr mdoc 7
407: and
408: .Xr man 7
409: macros and
410: .Xr eqn 7
411: equations inside tables.
1.1 kristaps 412: .Sh SEE ALSO
413: .Xr mandoc 1 ,
1.3 kristaps 414: .Xr man 7 ,
1.1 kristaps 415: .Xr mandoc_char 7 ,
1.3 kristaps 416: .Xr mdoc 7 ,
417: .Xr roff 7
1.1 kristaps 418: .Rs
419: .%A M. E. Lesk
420: .%T Tbl\(emA Program to Format Tables
421: .%D June 11, 1976
422: .Re
423: .Sh HISTORY
424: The tbl utility, a preprocessor for troff, was originally written by M.
425: E. Lesk at Bell Labs in 1975.
426: The GNU reimplementation of tbl, part of the groff package, was released
427: in 1990 by James Clark.
428: A standalone tbl implementation was written by Kristaps Dzonsons in
429: 2010.
1.29 schwarze 430: This formed the basis of the implementation that first appeared in
431: .Ox 4.9
432: as a part of the
1.1 kristaps 433: .Xr mandoc 1
434: utility.
435: .Sh AUTHORS
1.14 kristaps 436: This
1.1 kristaps 437: .Nm
438: reference was written by
1.28 schwarze 439: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
440: and
441: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
1.33 schwarze 442: .Sh BUGS
443: In
444: .Fl T
445: .Cm utf8
446: output mode, heavy lines are drawn instead of double lines.
447: This cannot be improved because the Unicode standard only provides
448: an incomplete set of box drawing characters with double lines,
449: whereas it provides a full set of box drawing characters
450: with heavy lines.
451: It is unlikely this can be improved in the future because the box
452: drawing characters are already marked in Unicode as characters
453: intended only for backward compatibility with legacy systems,
454: and their use is not encouraged.
455: So it seems unlikely that the missing ones might get added in the future.
CVSweb