Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
TBL(7)		   FreeBSD Miscellaneous Information Manual		TBL(7)

NAME
     tbl -- tbl	language reference for mandoc

DESCRIPTION
     The tbl language is a table-formatting language.  It is used within
     mdoc(7) and man(7)	UNIX manual pages.  This manual	describes the subset
     of	the tbl	language accepted by the mandoc(1) utility.

     Tables within mdoc(7) or man(7) are enclosed by the `TS' and `TE' macro
     tags, whose precise syntax	is documented in roff(7).  Tables consist of a
     series of options on a single line, followed by the table layout, fol-
     lowed by data.

     For example, the following	creates	a boxed	table with digits centered in
     the cells.

	   .TS
	   tab(:) box;
	   c5 c5 c5.
	   1:2:3
	   4:5:6
	   .TE

     When formatted, the following output is produced:
	   +--------------+
	   |1	  2	3 |
	   |4	  5	6 |
	   +--------------+
TABLE STRUCTURE
     Tables are	enclosed by the	`TS' and `TE' roff(7) macros.  A table con-
     sists of an optional single line of table Options terminated by a semi-
     colon, followed by	one or more lines of Layout specifications terminated
     by	a period, then Data.  All input	must be	7-bit ASCII.  Example:

	   .TS
	   box tab(:);
	   c | c
	   | c | c.
	   1:2
	   3:4
	   .TE

     Table data	is pre-processed, that is, data	rows are parsed	then inserted
     into the underlying stream	of input data.	This allows data rows to be
     interspersed by arbitrary roff(7),	mdoc(7), and man(7) macros such	as

	   .TS
	   tab(:);
	   c c c.
	   1:2:3
	   .Ao
	   3:2:1
	   .Ac
	   .TE

     in	the case of mdoc(7) or

	   .TS
	   tab(:);
	   c c c.
	   .ds ab 2
	   1:\*(ab:3
	   .I
	   3:2:1
	   .TE

     in	the case of man(7).

   Options
     The first line of a table may contain options separated by	spaces,	tabs,
     or	commas and terminated by a semicolon.  If the first line does not have
     a terminating semicolon, it is assumed that no options are	specified and
     instead a Layout is processed.  Some options require arguments enclosed
     by	parentheses.  The following case-insensitive options are available:

     allbox  Draw a single-line	box around each	table cell.  Currently treated
	     as	a synonym for box.

     box     Draw a single-line	box around the table.  For GNU compatibility,
	     this may also be invoked with frame.

     center  Center the	table instead of left-adjusting	it.  For GNU compati-
	     bility, this may also be invoked with centre.

     decimalpoint
	     Use the single-character argument as the decimal point with the n
	     layout key.  This is a GNU	extension.

     delim   Use the two characters of the argument as eqn(7) delimiters.
	     Currently unsupported.

     doublebox
	     Draw a double-line	box around the table.  For GNU compatibility,
	     this may also be invoked with doubleframe.

     expand  Increase the width	of the table to	the current line length.  Cur-
	     rently ignored.

     linesize
	     Draw lines	with the point size given by the unsigned integer
	     argument.	Currently ignored.

     nokeep  Allow page	breaks within the table.  This is a GNU	extension and
	     currently ignored.

     nospaces
	     Ignore leading and	trailing spaces	in data	cells.	This is	a GNU
	     extension and currently ignored.

     nowarn  Suppress warnings about tables exceeding the current line length.
	     This is a GNU extension and currently ignored.

     tab     Use the single-character argument as a delimiter between data
	     cells.  By	default, the tab character is used.

   Layout
     The table layout follows Options or a `T&'	macro invocation.  Layout
     specifies how data	rows are displayed on output.  Each layout line	corre-
     sponds to a line of data; the last	layout line applies to all remaining
     data lines.  Layout lines may also	be separated by	a comma.  Each layout
     cell consists of one of the following case-insensitive keys:

     c	 Center	a literal string within	its column.

     r	 Right-justify a literal string	within its column.

     l	 Left-justify a	literal	string within its column.

     n	 Justify a number around its last decimal point.  If the decimal point
	 is not	found on the number, it's assumed to trail the number.

     s	 Horizontally span columns from	the last non-s data cell.  It is an
	 error if spanning columns follow a - or | cell, or come first.	 This
	 option	is not supported by mandoc(1).

     a	 Left-justify a	literal	string and pad with one	space.

     ^	 Vertically span rows from the last non-^ data cell.  It is an error
	 to invoke a vertical span on the first	layout row.  Unlike a horizon-
	 tal spanner, you must specify an empty	cell (if it not	empty, the
	 data is discarded) in the corresponding data cell.

     -	 Replace the data cell (its contents will be lost) with	a single hori-
	 zontal	line.  This may	also be	invoked	with _.

     =	 Replace the data cell (its contents will be lost) with	a double hori-
	 zontal	line.

     |	 Emit a	vertical bar instead of	data.

     ||	 Emit a	double-vertical	bar instead of data.

     Keys may be followed by a set of modifiers.  A modifier is	either a modi-
     fier key or a natural number for specifying the minimum width of a	col-
     umn.  The following case-insensitive modifier keys	are available:

     b	 Use a bold font for the contents of this column.

     d	 Move cell content down	to the last cell of a vertical span.  Cur-
	 rently	ignored.

     e	 Make this column wider	to match the maximum width of any other	column
	 also having the e modifier.

     f	 The next character selects the	font to	use for	this column.  See the
	 roff(7) manual	for supported one-character font names.

     i	 Use an	italic font for	the contents of	this column.

     m	 Specify a cell	start macro.  This is a	GNU extension and currently
	 unsupported.

     p	 Set the point size to the following unsigned argument,	or change it
	 by the	following signed argument.  Currently ignored.

     v	 Set the vertical line spacing to the following	unsigned argument, or
	 change	it by the following signed argument.  Currently	ignored.

     t	 Do not	vertically center cell content in the vertical span, leave it
	 at the	top.  Currently	ignored.

     u	 Move cell content up by half a	table line.  Currently ignored.

     w	 Specify minimum column	width.	Currently ignored.

     x	 After determining the width of	all other columns, distribute the rest
	 of the	line length among all columns having the x modifier.

     z	 Do not	use this cell for determining the width	of this	column.

     For example, the following	layout specifies a center-justified column of
     minimum width 10, followed	by vertical bar, followed by a left-justified
     column of minimum width 10, another vertical bar, then a column using
     bold font justified about the decimal point in numbers:

	   c10 | l10 | nfB

   Data
     The data section follows the last layout row.  By default,	cells in a
     data section are delimited	by a tab.  This	behaviour may be changed with
     the tab option.  If _ or =	is specified, a	single or double line, respec-
     tively, is	drawn across the data field.  If \- or \= is specified,	a line
     is	drawn within the data field (i.e. terminating within the cell and not
     draw to the border).  If the last cell of a line is T{, all subsequent
     lines are included	as part	of the cell until T} is	specified as its own
     data cell.	 It may	then be	followed by a tab (or as designated by tab) or
     an	end-of-line to terminate the row.

COMPATIBILITY
     The mandoc(1) implementation of tbl doesn't support mdoc(7) and man(7)
     macros and	eqn(7) equations inside	tables.

SEE ALSO
     mandoc(1),	man(7),	mandoc_char(7),	mdoc(7), roff(7)

     M.	E. Lesk, Tbl--A	Program	to Format Tables, June 11, 1976.

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 is part of the mandoc(1) utility.

AUTHORS
     This tbl reference	was written by Kristaps	Dzonsons <kristaps@bsd.lv>.

FreeBSD	11.1		       October 17, 2018			  FreeBSD 11.1

NAME | DESCRIPTION | TABLE STRUCTURE | COMPATIBILITY | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tbl&sektion=7&manpath=FreeBSD+11.1-RELEASE+and+Ports>

home | help