Annotation of mandoc/tbl.7, Revision 1.34
1.34 ! schwarze 1: .\" $Id: tbl.7,v 1.33 2019/02/09 16:46:13 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.34 ! schwarze 18: .Dd $Mdocdate: February 9 2019 $
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.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.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
1.30 schwarze 234: If a data cell contains only the two bytes
235: .Ql \e\(ha ,
236: the cell above spans to this row, as if the layout specification
237: of this cell were
238: .Cm \(ha .
239: .Pp
240: If a data cell contains only the single character
1.28 schwarze 241: .Ql _
242: or
243: .Ql = ,
244: a single or double horizontal line is drawn across the cell,
245: joining its neighbours.
1.32 schwarze 246: If a data cell contains only the two character sequence
1.28 schwarze 247: .Ql \e_
248: or
249: .Ql \e= ,
250: a single or double horizontal line is drawn inside the cell,
251: not joining its neighbours.
252: If a data line contains nothing but the single character
253: .Ql _
1.1 kristaps 254: or
1.28 schwarze 255: .Ql = ,
256: a horizontal line across the whole table is inserted
257: without consuming a layout row.
258: .Pp
259: In place of any data cell, a text block can be used.
260: It starts with
261: .Ic \&T{
262: at the end of a physical input line.
263: Input line breaks inside the text block
264: neither end the text block nor its data cell.
265: It only ends if
266: .Ic \&T}
267: occurs at the beginning of a physical input line and is followed
268: by an end-of-cell indicator.
269: If the
270: .Ic \&T}
271: is followed by the end of the physical input line, the text block,
272: the data cell, and the data line ends at this point.
273: If the
274: .Ic \&T}
275: is followed by the
276: .Cm tab
277: character, only the text block and the data cell end,
278: but the data line continues with the data cell following the
279: .Cm tab
280: character.
1.1 kristaps 281: If
1.28 schwarze 282: .Ic \&T}
283: is followed by any other character, it does not end the text block,
284: which instead continues to the following physical input line.
285: .Sh EXAMPLES
286: String justification and font selection:
287: .Bd -literal -offset indent
288: \&.TS
289: rb c lb
290: r ci l.
291: r center l
292: ri ce le
293: right c left
294: \&.TE
295: .Ed
296: .Bd -filled -offset indent
297: .TS
298: rb c lb
299: r ci l.
300: r center l
301: ri ce le
302: right c left
303: .TE
304: .Ed
305: .Pp
306: Some ports in
307: .Ox 6.1
308: to show number alignment and line drawing:
309: .Bd -literal -offset indent
310: \&.TS
311: box tab(:);
312: r| l
313: r n.
314: software:version
315: _
316: AFL:2.39b
317: Mutt:1.8.0
318: Ruby:1.8.7.374
319: TeX Live:2015
320: \&.TE
321: .Ed
322: .Bd -filled -offset indent
323: .TS
324: box tab(:);
325: r| l
326: r n.
327: software:version
328: _
329: AFL:2.39b
330: Mutt:1.8.0
331: Ruby:1.8.7.374
1.31 schwarze 332: TeX Live:2015
1.28 schwarze 333: .TE
334: .Ed
335: .sp 2v
336: Spans and skipping width calculations:
337: .Bd -literal -offset indent
338: \&.TS
339: box tab(:);
340: lz s | rt
1.30 schwarze 341: lt| cb| \(ha
342: \(ha | rz s.
1.28 schwarze 343: left:r
344: l:center:
345: :right
346: \&.TE
347: .Ed
348: .Bd -filled -offset indent
349: .TS
350: box tab(:);
351: lz s | rt
352: lt| cb| ^
353: ^ | rz s.
354: left:r
355: l:center:
356: :right
357: .TE
358: .Ed
359: .sp 2v
360: Text blocks, specifying spacings and specifying and equalizing
361: column widths, putting lines into individual cells, and overriding
362: .Cm allbox :
363: .Bd -literal -offset indent
364: \&.TS
365: allbox tab(:);
366: le le||7 lw10.
367: The fourth line:_:line 1
368: of this column:=:line 2
369: determines:\_:line 3
370: the column width.:T{
371: This text is too wide to fit into a column of width 17.
372: T}:line 4
373: T{
374: No break here.
375: T}::line 5
376: \&.TE
377: .Ed
378: .Bd -filled -offset indent
379: .TS
380: allbox tab(:);
381: le le||7 lw10.
382: The fourth line:_:line 1
383: of this column:=:line 2
384: determines:\_:line 3
385: the column width.:T{
386: This text is too wide to fit into a column of width 17.
387: T}:line 4
388: T{
389: No break here.
390: T}::line 5
391: .TE
392: .Ed
393: .sp 2v
394: These examples were constructed to demonstrate many
395: .Nm
396: features in a compact way.
1.34 ! schwarze 397: In real manual pages, keep tables as simple as possible.
! 398: They usually look better, are less fragile, and are more portable.
1.1 kristaps 399: .Sh COMPATIBILITY
400: The
401: .Xr mandoc 1
1.26 schwarze 402: implementation of
403: .Nm
404: doesn't support
405: .Xr mdoc 7
406: and
407: .Xr man 7
408: macros and
409: .Xr eqn 7
410: equations inside tables.
1.1 kristaps 411: .Sh SEE ALSO
412: .Xr mandoc 1 ,
1.3 kristaps 413: .Xr man 7 ,
1.1 kristaps 414: .Xr mandoc_char 7 ,
1.3 kristaps 415: .Xr mdoc 7 ,
416: .Xr roff 7
1.1 kristaps 417: .Rs
418: .%A M. E. Lesk
419: .%T Tbl\(emA Program to Format Tables
420: .%D June 11, 1976
421: .Re
422: .Sh HISTORY
423: The tbl utility, a preprocessor for troff, was originally written by M.
424: E. Lesk at Bell Labs in 1975.
425: The GNU reimplementation of tbl, part of the groff package, was released
426: in 1990 by James Clark.
427: A standalone tbl implementation was written by Kristaps Dzonsons in
428: 2010.
1.29 schwarze 429: This formed the basis of the implementation that first appeared in
430: .Ox 4.9
431: as a part of the
1.1 kristaps 432: .Xr mandoc 1
433: utility.
434: .Sh AUTHORS
1.14 kristaps 435: This
1.1 kristaps 436: .Nm
437: reference was written by
1.28 schwarze 438: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
439: and
440: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
1.33 schwarze 441: .Sh BUGS
442: In
443: .Fl T
444: .Cm utf8
445: output mode, heavy lines are drawn instead of double lines.
446: This cannot be improved because the Unicode standard only provides
447: an incomplete set of box drawing characters with double lines,
448: whereas it provides a full set of box drawing characters
449: with heavy lines.
450: It is unlikely this can be improved in the future because the box
451: drawing characters are already marked in Unicode as characters
452: intended only for backward compatibility with legacy systems,
453: and their use is not encouraged.
454: So it seems unlikely that the missing ones might get added in the future.
CVSweb