summaryrefslogtreecommitdiff
path: root/usr/src/man/man7/tbl.7
diff options
context:
space:
mode:
Diffstat (limited to 'usr/src/man/man7/tbl.7')
-rw-r--r--usr/src/man/man7/tbl.7455
1 files changed, 455 insertions, 0 deletions
diff --git a/usr/src/man/man7/tbl.7 b/usr/src/man/man7/tbl.7
new file mode 100644
index 0000000000..67b24ec019
--- /dev/null
+++ b/usr/src/man/man7/tbl.7
@@ -0,0 +1,455 @@
+.\" $Id: tbl.7,v 1.37 2021/09/18 12:34:27 schwarze Exp $
+.\"
+.\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2014,2015,2017,2018,2019 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: September 18 2021 $
+.Dt TBL 7
+.Os
+.Sh NAME
+.Nm tbl
+.Nd tbl language reference for mandoc
+.Sh DESCRIPTION
+The
+.Nm tbl
+language formats tables.
+It is used within
+.Xr mdoc 7
+and
+.Xr man 7
+pages.
+This manual describes the subset of the
+.Nm
+language accepted by the
+.Xr mandoc 1
+utility.
+.Pp
+Each table is started with a
+.Xr mandoc_roff 7
+.Ic \&TS
+macro, consist of at most one line of
+.Sx Options ,
+one or more
+.Sx Layout
+lines, one or more
+.Sx Data
+lines, and ends with a
+.Ic \&TE
+macro.
+All input must be 7-bit ASCII.
+.Ss Options
+If the first input line of a table ends with a semicolon, it contains
+case-insensitive options separated by spaces, tabs, or commas.
+Otherwise, it is interpreted as the first
+.Sx Layout
+line.
+.Pp
+The following options are available.
+Some of them require arguments enclosed in parentheses:
+.Bl -tag -width Ds
+.It Cm allbox
+Draw a single-line box around each table cell.
+.It Cm box
+Draw a single-line box around the table.
+For GNU compatibility, this may also be invoked with
+.Cm frame .
+.It Cm center
+Center the table instead of left-adjusting it.
+For GNU compatibility, this may also be invoked with
+.Cm centre .
+.It Cm decimalpoint
+Use the single-character argument as the decimal point with the
+.Cm n
+layout key.
+This is a GNU extension.
+.It Cm delim
+Use the two characters of the argument as
+.Xr eqn 7
+delimiters.
+Currently unsupported.
+.It Cm doublebox
+Draw a double-line box around the table.
+For GNU compatibility, this may also be invoked with
+.Cm doubleframe .
+.It Cm expand
+Increase the width of the table to the current line length.
+Currently ignored.
+.It Cm linesize
+Draw lines with the point size given by the unsigned integer argument.
+Currently ignored.
+.It Cm nokeep
+Allow page breaks within the table.
+This is a GNU extension and currently ignored.
+.It Cm nospaces
+Ignore leading and trailing spaces in data cells.
+This is a GNU extension.
+.It Cm nowarn
+Suppress warnings about tables exceeding the current line length.
+This is a GNU extension and currently ignored.
+.It Cm tab
+Use the single-character argument as a delimiter between data cells.
+By default, the horizontal tabulator character is used.
+.El
+.Ss Layout
+The table layout follows an
+.Sx Options
+line or a
+.Xr mandoc_roff 7
+.Ic \&TS
+or
+.Ic \&T&
+macro.
+Each layout line specifies how one line of
+.Sx Data
+is formatted.
+The last layout line ends with a full stop.
+It also applies to all remaining data lines.
+Multiple layout lines can be joined by commas on a single physical
+input line.
+.Pp
+Each layout line consists of one or more layout cell specifications,
+optionally separated by whitespace.
+The following case-insensitive key characters start a new cell
+specification:
+.Bl -tag -width 2n
+.It Cm c
+Center the string in this cell.
+.It Cm r
+Right-justify the string in this cell.
+.It Cm l
+Left-justify the string in this cell.
+.It Cm n
+Justify a number around its last decimal point.
+If no decimal point is found in the number,
+it is assumed to trail the number.
+.It Cm s
+Horizontally span columns from the last
+.Pf non- Cm s
+layout cell.
+It is an error if a column span follows a
+.Cm _
+or
+.Cm =
+cell, or comes first on a layout line.
+The combined cell as a whole consumes only one cell
+of the corresponding data line.
+.It Cm a
+Left-justify a string and pad with one space.
+.It Cm \(ha
+Vertically span rows from the last
+.Pf non- Cm \(ha
+layout cell.
+It is an error to invoke a vertical span on the first layout line.
+Unlike a horizontal span, a vertical span consumes a data cell
+and discards the content.
+.It Cm _
+Draw a single horizontal line in this cell.
+This consumes a data cell and discards the content.
+It may also be invoked with
+.Cm \- .
+.It Cm =
+Draw a double horizontal line in this cell.
+This consumes a data cell and discards the content.
+.El
+.Pp
+Each cell key may be followed by zero or more of the following
+case-insensitive modifiers:
+.Bl -tag -width 2n
+.It Cm b
+Use a bold font for the contents of this cell.
+.It Cm d
+Move content down to the last row of this vertical span.
+Currently ignored.
+.It Cm e
+Make this column wider to match the maximum width
+of any other column also having the
+.Cm e
+modifier.
+.It Cm f
+The next one or two characters select the font to use for this cell.
+One-character font names must be followed by a blank or period.
+See the
+.Xr mandoc_roff 7
+manual for supported font names.
+.It Cm i
+Use an italic font for the contents of this cell.
+.It Cm m
+Specify a cell start macro.
+This is a GNU extension and currently unsupported.
+.It Cm p
+Set the point size to the following unsigned argument,
+or change it by the following signed argument.
+Currently ignored.
+.It Cm v
+Set the vertical line spacing to the following unsigned argument,
+or change it by the following signed argument.
+Currently ignored.
+.It Cm t
+Do not vertically center content in this vertical span,
+leave it in the top row.
+Currently ignored.
+.It Cm u
+Move cell content up by half a table row.
+Currently ignored.
+.It Cm w
+Specify a minimum column width.
+.It Cm x
+After determining the width of all other columns, distribute the
+rest of the line length among all columns having the
+.Cm x
+modifier.
+.It Cm z
+Do not use this cell for determining the width of this column.
+.It Cm \&|
+Draw a single vertical line to the right of this cell.
+.It Cm ||
+Draw a double vertical line to the right of this cell.
+.El
+.Pp
+If a modifier consists of decimal digits,
+it specifies a minimum spacing in units of
+.Cm n
+between this column and the next column to the right.
+The default is 3.
+If there is a vertical line, it is drawn inside the spacing.
+.Ss Data
+The data section follows the last
+.Sx Layout
+line.
+Each data line consists of one or more data cells, delimited by
+.Cm tab
+characters.
+.Pp
+If a data cell contains only the two bytes
+.Ql \e\(ha ,
+the cell above spans to this row, as if the layout specification
+of this cell were
+.Cm \(ha .
+.Pp
+If a data cell contains only the single character
+.Ql _
+or
+.Ql = ,
+a single or double horizontal line is drawn across the cell,
+joining its neighbours.
+If a data cell contains only the two character sequence
+.Ql \e_
+or
+.Ql \e= ,
+a single or double horizontal line is drawn inside the cell,
+not joining its neighbours.
+If a data line contains nothing but the single character
+.Ql _
+or
+.Ql = ,
+a horizontal line across the whole table is inserted
+without consuming a layout row.
+.Pp
+In place of any data cell, a text block can be used.
+It starts with
+.Ic \&T{
+at the end of a physical input line.
+Input line breaks inside the text block
+neither end the text block nor its data cell.
+It only ends if
+.Ic \&T}
+occurs at the beginning of a physical input line and is followed
+by an end-of-cell indicator.
+If the
+.Ic \&T}
+is followed by the end of the physical input line, the text block,
+the data cell, and the data line ends at this point.
+If the
+.Ic \&T}
+is followed by the
+.Cm tab
+character, only the text block and the data cell end,
+but the data line continues with the data cell following the
+.Cm tab
+character.
+If
+.Ic \&T}
+is followed by any other character, it does not end the text block,
+which instead continues to the following physical input line.
+.Sh EXAMPLES
+String justification and font selection:
+.Bd -literal -offset indent
+\&.TS
+rb c lb
+r ci l.
+r center l
+ri ce le
+right c left
+\&.TE
+.Ed
+.Bd -filled -offset indent
+.TS
+rb c lb
+r ci l.
+r center l
+ri ce le
+right c left
+.TE
+.Ed
+.Pp
+Some ports in
+.Ox 6.1
+to show number alignment and line drawing:
+.Bd -literal -offset indent
+\&.TS
+box tab(:);
+r| l
+r n.
+software:version
+_
+AFL:2.39b
+Mutt:1.8.0
+Ruby:1.8.7.374
+TeX Live:2015
+\&.TE
+.Ed
+.Bd -filled -offset indent
+.TS
+box tab(:);
+r| l
+r n.
+software:version
+_
+AFL:2.39b
+Mutt:1.8.0
+Ruby:1.8.7.374
+TeX Live:2015
+.TE
+.Ed
+.sp 2v
+Spans and skipping width calculations:
+.Bd -literal -offset indent
+\&.TS
+box tab(:);
+lz s | rt
+lt| cb| \(ha
+\(ha | rz s.
+left:r
+l:center:
+:right
+\&.TE
+.Ed
+.Bd -filled -offset indent
+.TS
+box tab(:);
+lz s | rt
+lt| cb| ^
+^ | rz s.
+left:r
+l:center:
+:right
+.TE
+.Ed
+.sp 2v
+Text blocks, specifying spacings and specifying and equalizing
+column widths, putting lines into individual cells, and overriding
+.Cm allbox :
+.Bd -literal -offset indent
+\&.TS
+allbox tab(:);
+le le||7 lw10.
+The fourth line:_:line 1
+of this column:=:line 2
+determines:\_:line 3
+the column width.:T{
+This text is too wide to fit into a column of width 17.
+T}:line 4
+T{
+No break here.
+T}::line 5
+\&.TE
+.Ed
+.Bd -filled -offset indent
+.TS
+allbox tab(:);
+le le||7 lw10.
+The fourth line:_:line 1
+of this column:=:line 2
+determines:\_:line 3
+the column width.:T{
+This text is too wide to fit into a column of width 17.
+T}:line 4
+T{
+No break here.
+T}::line 5
+.TE
+.Ed
+.sp 2v
+These examples were constructed to demonstrate many
+.Nm
+features in a compact way.
+In real manual pages, keep tables as simple as possible.
+They usually look better, are less fragile, and are more portable.
+.Sh COMPATIBILITY
+The
+.Xr mandoc 1
+implementation of
+.Nm
+doesn't support
+.Xr mdoc 7
+and
+.Xr man 7
+macros and
+.Xr eqn 7
+equations inside tables.
+.Sh SEE ALSO
+.Xr mandoc 1 ,
+.Xr man 7 ,
+.Xr mandoc_char 7 ,
+.Xr mandoc_roff 7 ,
+.Xr mdoc 7
+.Rs
+.%A M. E. Lesk
+.%T Tbl \(em A Program to Format Tables
+.%D June 11, 1976
+.Re
+.Sh HISTORY
+The tbl utility, a preprocessor for troff, was originally written by M.
+E. Lesk at Bell Labs in 1975.
+The GNU reimplementation of tbl, part of the groff package, was released
+in 1990 by James Clark.
+A standalone tbl implementation was written by Kristaps Dzonsons in
+2010.
+This formed the basis of the implementation that first appeared in
+.Ox 4.9
+as a part of the
+.Xr mandoc 1
+utility.
+.Sh AUTHORS
+This
+.Nm
+reference was written by
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
+and
+.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
+.Sh BUGS
+In
+.Fl T
+.Cm utf8
+output mode, heavy lines are drawn instead of double lines.
+This cannot be improved because the Unicode standard only provides
+an incomplete set of box drawing characters with double lines,
+whereas it provides a full set of box drawing characters
+with heavy lines.
+It is unlikely this can be improved in the future because the box
+drawing characters are already marked in Unicode as characters
+intended only for backward compatibility with legacy systems,
+and their use is not encouraged.
+So it seems unlikely that the missing ones might get added in the future.
generated by cgit v1.2.3 (git 2.46.0) at 2025-12-08 03:36:52 +0000