1 files changed, 236 insertions, 91 deletions
diff --git a/src/preproc/tbl/tbl.man b/src/preproc/tbl/tbl.man
index fa0cc36f..4e6edc70 100644
--- a/src/preproc/tbl/tbl.man
+++ b/src/preproc/tbl/tbl.man
@@ -1,3 +1,4 @@
+'\" t
 .ig
 Copyright (C) 1989-1995, 2001, 2002, 2003, 2004, 2006, 2007, 2008
   Free Software Foundation, Inc.
@@ -82,6 +83,9 @@ expects to find table descriptions wrapped in the
 (table start) and
 .B .TE
 (table end) macros.
+.
+.
+.SS Global options
 The line immediately following the
 .B .TS
 macro may contain any of the following global options (ignoring the case of
@@ -129,6 +133,9 @@ Same as doublebox (GNU tbl only).
 .B expand
 Make the table as wide as the current line length (providing a column
 separation factor).
+Ignored if one or more `x' column specifiers are used (see below).
+.
+.IP
 In case the sum of the column widths is larger than the current line length,
 the column separation factor is set to zero; such tables extend into the
 right margin, and there is no column separation at all.
@@ -150,7 +157,7 @@ type.
 Don't use diversions to prevent page breaks (GNU tbl only).
 Normally
 .B tbl
-attempts to prevent undesirable breaks in the table by using diversions.
+attempts to prevent undesirable breaks in boxed tables by using diversions.
 This can sometimes interact badly with macro packages' own use of
 diversions, when footnotes, for example, are used.
 .
@@ -168,16 +175,17 @@ instead of a tab to separate items in a line of input data.
 The global options must end with a semicolon.
 There might be whitespace between an option and its argument in parentheses.
 .
-.LP
+.
+.SS Table format specification
 After global options come lines describing the format of each line of
 the table.
 Each such format line describes one line of the table itself, except that
 the last format line (which you must end with a period) describes all
 remaining lines of the table.
-A single key character describes each column of each line of the table.
+A single-key character describes each column of each line of the table.
 Key characters can be separated by spaces or tabs.
-You may run format specs for multiple lines together on the same line by
-separating them with commas.
+You may run format specifications for multiple lines together on the same
+line by separating them with commas.
 .
 .LP
 You may follow each key character with specifiers that determine the font
@@ -198,6 +206,50 @@ The available key characters are:
 .BR a , A
 Center longest line in this column and then left-justifies all other lines
 in this column with respect to that centered line.
+The idea is to use such alphabetic subcolumns (hence the name of the key
+character) in combination with\~
+.BR L ;
+they are called subcolumns because
+.BR A \~items
+are indented by\~1n relative to
+.BR L \~entries.
+Example:
+.RS
+.IP
+.EX
+\&.TS
+\&tab(;);
+\&ln,an.
+\&item one;1
+\&subitem two;2
+\&subitem three;3
+\&.T&
+\&ln,an.
+\&item eleven;11
+\&subitem twentytwo;22
+\&subitem thirtythree;33
+\&.TE
+.EE
+.RE
+.
+.IP
+Result:
+.
+.RS
+.IP
+.TS
+tab(;);
+ln,an.
+item one;1
+subitem two;2
+subitem three;3
+.T&
+ln,an.
+item eleven;11
+subitem twentytwo;22
+subitem thirtythree;33
+.TE
+.RE
 .
 .TP
 .BR c , C
@@ -211,6 +263,80 @@ Left-justify item within the column.
 .BR n , N
 Numerically justify item in the column: Units positions of numbers are
 aligned vertically.
+If there is one or more dots adjacent to a digit, use the rightmost one for
+vertical alignment.
+If there is no dot, use the rightmost digit for vertical alignment;
+otherwise, center the item within the column.
+Alignment can be forced to a certain position using `\[rs]&'; if there is
+one or more instances of this special (non-printing) character present
+within the data, use the leftmost one for alignment.
+Example:
+.RS
+.IP
+.EX
+\&.TS
+\&n.
+\&1
+\&1.5
+\&1.5.3
+\&abcde
+\&a\[rs]&bcde
+\&.TE
+.EE
+.RE
+.
+.IP
+Result:
+.
+.RS
+.IP
+.TS
+n.
+1
+1.5
+1.5.3
+abcde
+a\&bcde
+.TE
+.RE
+.
+.IP
+If numerical entries are combined with
+.B L
+or
+.BR R \~entries
+\[en] this can happen if the table format is changed with
+.B .T&
+\%\[en],
+center the widest
+.I number
+(of the data entered under the
+.BR N \~specifier
+regime) relative to the widest
+.B L
+or
+.BR R \~entry,
+preserving the alignment of all numerical entries.
+Contrary to
+.BR A \~type
+entries, there is no extra indentation.
+.
+.IP
+Using equations (to be processed with
+.BR eqn )
+within columns which use the
+.BR N \~specifier
+is problematic in most cases due to
+.BR tbl 's
+algorithm for finding the vertical alignment, as described above.
+Using the global
+.B delim
+option, however, it is possible to make
+.B tbl
+ignore the data within
+.B eqn
+delimiters for that purpose.
+.
 .
 .TP
 .BR r , R
@@ -219,10 +345,12 @@ Right-justify item within the column.
 .TP
 .BR s , S
 Span previous item on the left into this column.
+Not allowed for the first column.
 .
 .TP
 .B ^
 Span down entry from previous row in this column.
+Not allowed for the first row.
 .
 .TP
 .BR _ , -
@@ -239,11 +367,22 @@ The corresponding column becomes a vertical rule (if two of these are
 adjacent, a double vertical rule).
 .
 .LP
-A vertical bar to the left of the first key-letter or to the right of the
+A vertical bar to the left of the first key letter or to the right of the
 last one produces a line at the edge of the table.
 .
 .LP
-Here are the specifiers that can appear in suffixes to column key letters:
+To change the data format within a table, use the
+.B .T&
+command (at the start of a line).
+It is followed by format and data lines (but no global options) similar to
+the
+.B .TS
+request.
+.
+.
+.SS Column specifiers
+Here are the specifiers that can appear in suffixes to column key letters
+(in any order):
 .
 .TP
 .BR b , B
@@ -259,6 +398,7 @@ than vertically centering it (GNU tbl only).
 .TP
 .BR e , E
 Make equally-spaced columns.
+All columns marked with this specifier get the same width.
 .
 .TP
 .BR f , F
@@ -340,6 +480,17 @@ If used multiple times to specify the width for a particular column,
 the last entry takes effect.
 .
 .TP
+.BR x , X
+An expanded column.
+After computing all column widths without an
+.BR x \~specifier,
+use the remaining line width for this column.
+If there is more than one expanded column, distribute the remaining
+horizontal space evenly among the affected columns (this is a GNU
+extension).
+This feature has the same effect as specifying a minimum column width.
+.
+.TP
 .BR z , Z
 Ignore the corresponding column for width-calculation purposes, this is,
 don't use the fields but only the specifiers of this column to compute
@@ -353,6 +504,16 @@ option is on \[en] in case of overfull tables this might be zero).
 Default separation is 3n.
 .
 .LP
+The column specifiers
+.BR e ,
+.BR w ,
+and
+.B x
+are mutually exclusive; if specified multiple times for a particular column,
+the last entry takes effect.
+.
+.
+.SS Table data
 The format lines are followed by lines containing the actual data for the
 table, followed finally by
 .BR .TE .
@@ -370,44 +531,36 @@ computes the column widths line by line, applying \[rs]w on each entry
 which isn't a text block.
 As a consequence, constructions like
 .IP
-.B .TS
-.br
-.B c,l.
-.br
-.B \[rs]s[20]MM
-.br
-.B MMMM
-.br
-.B .TE
-.br
+.EX
+\&.TS
+\&c,l.
+\&\[rs]s[20]MM
+\&MMMM
+\&.TE
+.EE
 .
 .LP
 fail; you must either say
 .IP
-.B .TS
-.br
-.B cp20,lp20.
-.br
-.B MM
-.br
-.B MMMM
-.br
-.B .TE
-.br
+.EX
+\&.TS
+\&cp20,lp20.
+\&MM
+\&MMMM
+\&.TE
+.EE
 .
 .LP
 or
+.
 .IP
-.B .TS
-.br
-.B c,l.
-.br
-.B \[rs]s[20]MM
-.br
-.B \[rs]s[20]MMMM
-.br
-.B .TE
-.br
+.EX
+\&.TS
+\&c,l.
+\&\[rs]s[20]MM
+\&\[rs]s[20]MMMM
+\&.TE
+.EE
 .
 .LP
 A dot starting a line, followed by anything but a digit is handled as a
@@ -432,7 +585,8 @@ neighbours).
 A data item consisting only of `\[rs]^' indicates that the field immediately
 above spans downward over this row.
 .
-.LP
+.
+.SS Text blocks
 A text block can be used to enter data as a single entry which would be
 too long as a simple string between tabs.
 It is started with `T{' and closed with `T}'.
@@ -441,6 +595,8 @@ followed by other data columns (separated with tabs or the character given
 with the
 .B tab
 global option).
+.
+.LP
 By default, the text block is formatted with the settings which were
 active before entering the table, possibly overridden by the
 .BR m ,
@@ -455,25 +611,25 @@ right before the starting
 (and
 .B .ad
 after the table).
-If `w' specifiers are not given for all columns of a text block span, the
-default length of the text block (to be more precise, the line length used
-to process the text block diversion) is computed as L\[tmu]C/(N+1), where
-`L' is the current line length, `C' the number of columns spanned by the
-text block, and `N' the total number of columns in the table.
-Note, however, that the actual diversion width as given in register
+.
+.LP
+If either `w' or `x' specifiers are not given for
+.I all
+columns of a text block span, the default length of the text block (to be
+more precise, the line length used to process the text block diversion) is
+computed as L\[tmu]C/(N+1), where `L' is the current line length, `C' the
+number of columns spanned by the text block, and `N' the total number of
+columns in the table.
+Note, however, that the actual diversion width as returned in register
 .B \[rs]n[dl]
 is used eventually as the text block width.
+If necessary, you can also control the text block width with a direct
+insertion of a
+.B .ll
+request right after `T{'.
 .
-.LP
-To change the data format within a table, use the
-.B .T&
-command (at the start of a line).
-It is followed by format and data lines (but no global options) similar to
-the
-.B .TS
-request.
 .
-.LP
+.SS Miscellaneous
 The number register
 .B \[rs]n[TW]
 holds the table width; it can't be used within the table itself but is defined
@@ -540,29 +696,20 @@ defines its own macros (right before each table) it is necessary to use
 an `end-of-macro' macro.  Additionally, the escape character has to be switched
 off.  Here an example.
 .IP
-.B .eo
-.br
-.B .de ATABLE ..
-.br
-.B .TS
-.br
-.B allbox tab(;);
-.br
-.B cl.
-.br
-.B \[rs]$1;\[rs]$2
-.br
-.B .TE
-.br
-.B ...
-.br
-.B .ec
-.br
-.B .ATABLE A table
-.br
-.B .ATABLE Another table
-.br
-.B .ATABLE And \[dq]another one\[dq]
+.EX
+\&.eo
+\&.de ATABLE ..
+\&.TS
+\&allbox tab(;);
+\&cl.
+\&\[rs]$1;\[rs]$2
+\&.TE
+\&...
+\&.ec
+\&.ATABLE A table
+\&.ATABLE Another table
+\&.ATABLE And \[dq]another one\[dq]
+.EE
 .
 .LP
 Note, however, that not all features of
@@ -602,15 +749,14 @@ request cannot be used to force a page-break in a multi-page table.
 Instead, define
 .B BP
 as follows
+.
 .IP
-.B .de BP
-.br
-.B .ie '\[rs]\[rs]n(.z'' .bp \[rs]\[rs]$1
-.br
-.B .el \[rs]!.BP \[rs]\[rs]$1
-.br
-.B ..
-.br
+.EX
+\&.de BP
+\&.  ie '\[rs]\[rs]n(.z'' .bp \[rs]\[rs]$1
+\&.  el \[rs]!.BP \[rs]\[rs]$1
+\&..
+.EE
 .
 .LP
 and use
@@ -626,17 +772,16 @@ This is correct behaviour: \[rs]a is an
 leader.
 To get leaders use a real leader, either by using a control A or like
 this:
+.
 .IP
-.nf
-.ft B
+.EX
 \&.ds a \[rs]a
 \&.TS
-tab(;);
-lw(1i) l.
-A\[rs]*a;B
+\&tab(;);
+\&lw(1i) l.
+\&A\[rs]*a;B
 \&.TE
-.ft
-.fi
+.EE
 .
 .
 .SH REFERENCE