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

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

6 files changed, 335 insertions, 212 deletions

diff --git a/Makefile b/Makefile
index 13cb9e3e..20416b85 100644
--- a/Makefile
+++ b/Makefile
@@ -99,30 +99,30 @@ HEADS	   = mdoc.h libmdoc.h man.h libman.h term.h \
 
 GSGMLS	   = mandoc.1.sgml mdoc.3.sgml mdoc.7.sgml \
 	     mandoc_char.7.sgml man.7.sgml man.3.sgml roff.7.sgml \
-	     roff.3.sgml 
+	     roff.3.sgml tbl.7.sgml
 
 SGMLS	   = index.sgml
 
 XHTMLS	   = mandoc.1.xhtml mdoc.3.xhtml \
 	     man.3.xhtml mdoc.7.xhtml man.7.xhtml mandoc_char.7.xhtml \
-	     roff.7.xhtml roff.3.xhtml 
+	     roff.7.xhtml roff.3.xhtml tbl.7.xhtml
 
 HTMLS	   = ChangeLog.html index.html man.h.html mdoc.h.html \
 	     mandoc.h.html roff.h.html mandoc.1.html mdoc.3.html \
 	     man.3.html mdoc.7.html man.7.html mandoc_char.7.html \
-	     roff.7.html roff.3.html 
+	     roff.7.html roff.3.html tbl.7.html
 
 PSS	   = mandoc.1.ps mdoc.3.ps man.3.ps mdoc.7.ps man.7.ps \
-	     mandoc_char.7.ps roff.7.ps roff.3.ps 
+	     mandoc_char.7.ps roff.7.ps roff.3.ps tbl.7.ps
 
 PDFS	   = mandoc.1.pdf mdoc.3.pdf man.3.pdf mdoc.7.pdf man.7.pdf \
-	     mandoc_char.7.pdf roff.7.pdf roff.3.pdf 
+	     mandoc_char.7.pdf roff.7.pdf roff.3.pdf tbl.7.pdf
 
 XSLS	   = ChangeLog.xsl
 
 TEXTS	   = mandoc.1.txt mdoc.3.txt man.3.txt mdoc.7.txt man.7.txt \
 	     mandoc_char.7.txt ChangeLog.txt \
-	     roff.7.txt roff.3.txt 
+	     roff.7.txt roff.3.txt tbl.7.txt
 
 EXAMPLES   = example.style.css
 
@@ -135,7 +135,7 @@ MD5S	   = mdocml-$(VERSION).md5
 TARGZS	   = mdocml-$(VERSION).tar.gz
 
 MANS	   = mandoc.1 mdoc.3 mdoc.7 mandoc_char.7 man.7 \
-	     man.3 roff.7 roff.3 
+	     man.3 roff.7 roff.3 tbl.7
 
 BINS	   = mandoc
 
@@ -179,7 +179,7 @@ install:
 	mkdir -p $(DESTDIR)$(MANDIR)/man7
 	$(INSTALL_PROGRAM) mandoc $(DESTDIR)$(BINDIR)
 	$(INSTALL_MAN) mandoc.1 $(DESTDIR)$(MANDIR)/man1
-	$(INSTALL_MAN) man.7 mdoc.7 roff.7 mandoc_char.7 $(DESTDIR)$(MANDIR)/man7
+	$(INSTALL_MAN) man.7 mdoc.7 roff.7 tbl.7 mandoc_char.7 $(DESTDIR)$(MANDIR)/man7
 	$(INSTALL_DATA) example.style.css $(DESTDIR)$(EXAMPLEDIR)
 
 uninstall:
@@ -187,6 +187,7 @@ uninstall:
 	rm -f $(DESTDIR)$(MANDIR)/man1/mandoc.1
 	rm -f $(DESTDIR)$(MANDIR)/man7/mdoc.7
 	rm -f $(DESTDIR)$(MANDIR)/man7/roff.7
+	rm -f $(DESTDIR)$(MANDIR)/man7/tbl.7
 	rm -f $(DESTDIR)$(MANDIR)/man7/man.7
 	rm -f $(DESTDIR)$(MANDIR)/man7/mandoc_char.7
 	rm -f $(DESTDIR)$(EXAMPLEDIR)/example.style.css
diff --git a/man.7 b/man.7
index 52391b90..be88f6bb 100644
--- a/man.7
+++ b/man.7
@@ -913,7 +913,9 @@ In GNU troff, this would result in strange behaviour.
 .Xr man 1 ,
 .Xr mandoc 1 ,
 .Xr mandoc_char 7 ,
-.Xr mdoc 7
+.Xr mdoc 7 ,
+.Xr roff 7 ,
+.Xr tbl 7
 .Sh HISTORY
 The
 .Nm
diff --git a/mandoc.1 b/mandoc.1
index aef520fb..902085f1 100644
--- a/mandoc.1
+++ b/mandoc.1
@@ -531,7 +531,9 @@ lists render similarly.
 .Sh SEE ALSO
 .Xr man 7 ,
 .Xr mandoc_char 7 ,
-.Xr mdoc 7
+.Xr mdoc 7 ,
+.Xr roff 7 ,
+.Xr tbl 7
 .Sh AUTHORS
 The
 .Nm
diff --git a/mdoc.7 b/mdoc.7
index c7d230f1..e927c18e 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -2903,7 +2903,10 @@ This is not supported by mandoc.
 .Sh SEE ALSO
 .Xr man 1 ,
 .Xr mandoc 1 ,
+.Xr man 7 ,
 .Xr mandoc_char 7
+.Xr roff 7 ,
+.Xr tbl 7
 .Sh HISTORY
 The
 .Nm
diff --git a/roff.7 b/roff.7
index 12a709d7..134bae5e 100644
--- a/roff.7
+++ b/roff.7
@@ -546,201 +546,9 @@ See
 .Sx \&TS .
 .Ss \&TS
 Begin a table, which formats input in aligned rows and columns.
-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.
-A table block may also include
-.Nm ,
-.Xr mdoc 7 ,
-or
-.Xr man 7
-macros.
-Example:
-.Bd -literal -offset indent
-\&.TS
-box tab(:);   \e" Table-wide options.
-c | c         \e" Layout for first line.
-| c | c.      \e" Layout for all subsequent lines.
-1:2           \e" Data...
-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 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 .
-.Pp
-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
-.Pp
-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 .
-.Pp
-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.
+See
+.Xr tbl 7
+for a description of the tbl language.
 .Sh COMPATIBILITY
 This section documents compatibility between mandoc and other other
 .Nm
@@ -771,13 +579,8 @@ using the next-line syntax.
 .Xr mandoc 1 ,
 .Xr man 7 ,
 .Xr mandoc_char 7 ,
-.Xr mdoc 7
-.Rs
-.%A M. E. Lesk
-.%T Tbl\(emA Program to Format Tables
-.%D June 11, 1976
-.%U http://www.kohala.com/start/troff/v7/man/tbl/tbl.ps
-.Re
+.Xr mdoc 7 ,
+.Xr tbl 7
 .Rs
 .%A Joseph F. Ossanna
 .%A Brian W. Kernighan
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 .