===================================================================
RCS file: /cvs/mandoc/tbl.7,v
retrieving revision 1.1
retrieving revision 1.12
diff -u -p -r1.1 -r1.12
--- mandoc/tbl.7	2011/01/04 23:32:21	1.1
+++ mandoc/tbl.7	2011/02/07 00:05:40	1.12
@@ -1,6 +1,6 @@
-.\"	$Id: tbl.7,v 1.1 2011/01/04 23:32:21 kristaps Exp $
+.\"	$Id: tbl.7,v 1.12 2011/02/07 00:05:40 schwarze Exp $
 .\"
-.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2010, 2011 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
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: January 4 2011 $
+.Dd $Mdocdate: February 7 2011 $
 .Dt TBL 7
 .Os
 .Sh NAME
@@ -76,9 +76,12 @@ 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.
+A table consists of an optional single line of table
+.Sx Options
+terminated by a semicolon, followed by one or more lines of
+.Sx Layout
+specifications terminated by a period, then
+.Sx Data .
 All input must be 7-bit ASCII.
 Example:
 .Bd -literal -offset indent
@@ -95,7 +98,7 @@ 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 
+This allows data rows to be interspersed by arbitrary
 .Xr roff 7 ,
 .Xr mdoc 7 ,
 and
@@ -128,12 +131,14 @@ c c c.
 .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.
+.Ss Options
+The first line of a table consists of space-separated option 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.
+that no options are specified and instead a
+.Sx Layout
+is processed.
+Some options accept arguments enclosed by parenthesis.
 The following case-insensitive options are available:
 .Bl -tag -width Ds
 .It Cm center
@@ -161,7 +166,7 @@ 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
+This character is used as a delimiter between data cells, which otherwise
 defaults to the tab character.
 .It Cm linesize
 Accepts a natural number (all digits).
@@ -175,16 +180,16 @@ 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.
+.Ss Layout
+The table layout follows
+.Sx Options
+or a
+.Sq \&T&
+macro 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.
@@ -198,18 +203,29 @@ 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.
+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.
 .It Cm s
+Horizontally span columns from the last
+.No non- Ns Cm s
+data cell.
+It is an error if spanning columns follow a
+.Cm \-
+or
+.Cm \(ba
+cell, or come first.
 This option is not supported by
 .Xr mandoc 1 .
 .It Cm a
-This option is not supported by
-.Xr mandoc 1 .
+Left-justify a literal string and pad with one space.
 .It Cm ^
-This option is not supported by
-.Xr mandoc 1 .
+Vertically span rows from the last
+.No non- Ns Cm ^
+data cell.
+It is an error to invoke a vertical span on the first layout row.
+Unlike a horizontal spanner, you must specify an empty cell (if it not
+empty, the data is discarded) in the corresponding data cell.
 .It Cm \-
 Replace the data cell (its contents will be lost) with a single
 horizontal line.
@@ -224,16 +240,9 @@ Emit a vertical bar instead of data.
 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 minimum width of a column.
 The following case-insensitive modifier keys are available:
 .Cm z ,
 .Cm u ,
@@ -248,7 +257,14 @@ and
 .Cm i .
 All of these are ignored by
 .Xr mandoc 1 .
-.Ss Table Data
+.Pp
+For example, the 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
+.Ss 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
@@ -264,13 +280,16 @@ If
 .Cm \e-
 or
 .Cm \e=
-is specified, a line is drawn within the data field (i.e., terminating
+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.
+is specified as its own data cell.
+It may then be followed by a tab
+.Pq or as designated by Cm tab
+or an end-of-line to terminate the row.
 .Sh COMPATIBILITY
 This section documents compatibility between mandoc and other
 .Nm
@@ -286,10 +305,10 @@ implementation allows them.
 .El
 .Sh SEE ALSO
 .Xr mandoc 1 ,
-.Xr mandoc_char 7 ,
-.Xr roff 7 ,
 .Xr man 7 ,
-.Xr mdoc 7
+.Xr mandoc_char 7 ,
+.Xr mdoc 7 ,
+.Xr roff 7
 .Rs
 .%A M. E. Lesk
 .%T Tbl\(emA Program to Format Tables