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