Moved table stuff from roff.7 into the new tbl.7 (suggested by Jason McIntyre).

Added cross-links to tbl.7 from other manuals.

1 files changed, 312 insertions, 0 deletions

diff --git a/tbl.7 b/tbl.7
new file mode 100644
index 00000000..ec37fea7
--- /dev/null
+++ b/tbl.7
@@ -0,0 +1,312 @@
+.\"	$Id$
+.\"
+.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
+.\"
+.\" 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$
+.Dt TBL 7
+.Os
+.Sh NAME
+.Nm tbl
+.Nd tbl language reference for mandoc
+.Sh DESCRIPTION
+The
+.Nm tbl
+language is a table-formatting language.
+It is used within
+.Xr mdoc 7
+and
+.Xr man 7
+.Ux
+manual pages.
+This manual describes the subset of the
+.Nm
+language accepted by the
+.Xr mandoc 1
+utility.
+.Pp
+Tables within
+.Xr mdoc 7
+or
+.Xr man 7
+are enclosed by the
+.Sq TS
+and
+.Sq TE
+macro tags, whose precise syntax is documented in
+.Xr roff 7 .
+Tables consist of a series of options on a single line, followed by the
+table layout, followed by data.
+.Pp
+For example, the following creates a boxed table with digits centered in
+the cells.
+.Bd -literal -offset indent
+\&.TS
+tab(:) box;
+c5 c5 c5.
+1:2:3
+4:5:6
+\&.TE
+.Ed
+.Pp
+When formatted, the following output is produced:
+.Bd -filled -offset indent -compact
+.TS
+tab(:) box;
+c5 c5 c5.
+1:2:3
+4:5:6
+.TE
+.Ed
+.Sh TABLE STRUCTURE
+Tables are enclosed by the
+.Sq TS
+and
+.Sq TE
+.Xr roff 7
+macros.
+A table consists of an optional single line of table options terminated
+by a semicolon, followed by one or more lines of layout specification
+terminated by a period, then table data.
+All input must be 7-bit ASCII.
+Example:
+.Bd -literal -offset indent
+\&.TS
+box tab(:);
+c | c
+| c | c.
+1:2
+3:4
+\&.TE
+.Ed
+.Pp
+Table data is
+.Em 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 
+.Xr roff 7 ,
+.Xr mdoc 7 ,
+and
+.Xr man 7
+macros such as
+.Bd -literal -offset indent
+\&.TS
+tab(:);
+c c c.
+1:2:3
+\&.Ao
+3:2:1
+\&.Ac
+\&.TE
+.Ed
+.Pp
+in the case of
+.Xr mdoc 7
+or
+.Bd -literal -offset indent
+\&.TS
+tab(:);
+c c c.
+\&.ds ab 2
+1:\e*(ab:3
+\&.I
+3:2:1
+\&.TE
+.Ed
+.Pp
+in the case of
+.Xr man 7 .
+.Ss Table Options
+The first line of a table consists of its options, which consists of
+space-separated keys and modifiers 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 accept arguments enclosed by paranthesis.
+The following case-insensitive options are available:
+.Bl -tag -width Ds
+.It Cm center
+This option is not supported by
+.Xr mandoc 1 .
+This may also be invoked with
+.Cm centre .
+.It Cm delim
+Accepts a two-character argument.
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm expand
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm box
+Draw a single-line box around the table.
+This may also be invoked with
+.Cm frame .
+.It Cm doublebox
+Draw a double-line box around the table.
+This may also be invoked with
+.Cm doubleframe .
+.It Cm allbox
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm tab
+Accepts a single-character argument.
+This character is used a delimiter between data cells, which otherwise
+defaults to the tab character.
+.It Cm linesize
+Accepts a natural number (all digits).
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm nokeep
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm decimalpoint
+Accepts a single-character argument.
+This character will be used as the decimal point with the
+.Cm n
+layout key.
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm nospaces
+This option is not supported by
+.Xr mandoc 1 .
+.El
+.Ss Table Layout
+The table layout follows table options, except in the case of
+.Sx \&T& ,
+where it immediately procedes invocation.
+Layout specifies how data rows are displayed on output.
+Each layout line corresponds 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:
+.Bl -tag -width Ds
+.It Cm c
+Centre a literal string within its column.
+.It Cm r
+Right-justify a literal string within its column.
+.It Cm l
+Left-justify a literal string within its column.
+.It Cm n
+Justify a number around its decimal point.
+If the decimal point is not found on the number, it's assumed to trail
+the number.
+.It Cm s
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm a
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm ^
+This option is not supported by
+.Xr mandoc 1 .
+.It Cm \-
+Replace the data cell (its contents will be lost) with a single
+horizontal line.
+This may also be invoked with
+.Cm _ .
+.It Cm =
+Replace the data cell (its contents will be lost) with a double
+horizontal line.
+.It Cm \(ba
+Emit a vertical bar instead of data.
+.It Cm \(ba\(ba
+Emit a double-vertical bar instead of data.
+.El
+.Pp
+For example, following layout specifies a centre-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
+justified about the decimal point in numbers:
+.Pp
+.Dl c10 | l10 | n
+.Pp
+Keys may be followed by a set of modifiers.
+A modifier is either a modifier key or a natural number for specifying
+spacing.
+The following case-insensitive modifier keys are available:
+.Cm z ,
+.Cm u ,
+.Cm e ,
+.Cm t ,
+.Cm d ,
+.Cm f ,
+.Cm b ,
+.Cm i ,
+.Cm b ,
+and
+.Cm i .
+All of these are ignored by
+.Xr mandoc 1 .
+.Ss Table 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
+.Cm tab
+option.
+If
+.Cm _
+or
+.Cm =
+is specified, a single or double line, respectively, is drawn across the
+data field.
+If
+.Cm \e-
+or
+.Cm \e=
+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
+.Cm T{ ,
+all subsequent lines are included as part of the cell until
+.Cm T}
+is specified on its own line.
+.Sh COMPATIBILITY
+This section documents compatibility between mandoc and other
+.Nm
+implementations, at this time limited to GNU tbl.
+.Pp
+.Bl -dash -compact
+.It
+In GNU tbl, comments and macros are disallowed prior to the data block
+of a table.
+The
+.Xr mandoc 1
+implementation allows them.
+.El
+.Sh SEE ALSO
+.Xr mandoc 1 ,
+.Xr mandoc_char 7 ,
+.Xr roff 7 ,
+.Xr man 7 ,
+.Xr mdoc 7
+.Rs
+.%A M. E. Lesk
+.%T Tbl\(emA 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 is part of the
+.Xr mandoc 1
+utility.
+.Sh AUTHORS
+This partial
+.Nm
+reference was written by
+.An Kristaps Dzonsons Aq kristaps@bsd.lv .