gbranden pushed a commit to branch master
in repository groff.
commit 79afd29a346f97c687fadb1878e66471803955b3
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
AuthorDate: Sun Oct 31 21:07:06 2021 +1100
tbl(1): Do some spot cleaning.
Content:
* Start standardizing the term "(table) region" as that material between
".TS" and the first subsequent ".TE".
* Start standardizing the term "(table) description". (A table region
consists of one (or more, separated by .T&) table description(s)).
* Add parenthetical paragraph aiding the reader who knows just enough
*roff to start making unwarranted assumptions (as I once did, and
probably will continue to do). Try to clarify the fact that ".TS",
".T&", ".TE" are input tokens to tbl, but macro calls to troff.
* When introducing the term "decimal separator", note that it is
configurable, in hopes of justifying the sesquipedalian terminology.
* Speak of "alignment", not "justification".
* Advise when tbl(1) generates *roff code to produce warning messages.
(There are other cases not yet noted.)
* Prefer "table entries" to "data items".
* Instead of talking about "whitespace", identify specific input
characters.
* Remove discussion of "column separator lines" (not allowing '_', '-',
or '='); I couldn't figure out what was meant.
Style:
* Recast to use more formal and idiomatic English.
* Stop ending sentences with colons.
* Speak consistently of "GNU extensions", not "GNU tbl only". Other
implementations might adopt GNU extensions.
* Say "AT&T", not "Unix", tbl. There are many Unices and not all
shipped AT&T troff (or not exclusively).
* Use "\[em]", not " \[en] ", to "break" (interrupt) a sentence.
* Turn some sentence fragments into parentheticals.
* Add space after commas in table format specifiers used as paragraph
tags.
Markup:
* Break input lines after commas.
* Break input lines before and after multi-word parentheticals.
* Use two empty requests where vertical space is expected.
* Protect non-sentential dots from end-of-sentence detection.
---
src/preproc/tbl/tbl.1.man | 359 +++++++++++++++++++++++++++++-----------------
1 file changed, 230 insertions(+), 129 deletions(-)
diff --git a/src/preproc/tbl/tbl.1.man b/src/preproc/tbl/tbl.1.man
index 045b79d..055fdda 100644
--- a/src/preproc/tbl/tbl.1.man
+++ b/src/preproc/tbl/tbl.1.man
@@ -120,20 +120,53 @@ the standard input stream is read.
.SS Overview
.\" ====================================================================
.
-.B tbl
-expects to find table descriptions wrapped in the
+.I \%@g@tbl
+expects to find table descriptions between input lines that begin with
.B .TS
-(table start) and
+(table start)
+and
.B .TE
-(table end) macros.
+(table end).
.
-Within each such table sections, another table can be defined by
-using the request
-.B .T&
-before the final command
-.BR .TE .
+Within each such table region,
+another description can be preceded with an input line beginning with
+.BR .T& .
+.
+.
+.P
+(Experienced
+.I roff
+users should observe that
+.I \%@g@tbl
+is not a
+.I roff
+language interpreter:
+the default control character must be used,
+and no spaces or tabs are permitted between the control character and
+the macro name.
+.
+These
+.I \%@g@tbl
+input tokens remain as-is in the output,
+where they become ordinary macro calls.
+.
+Macro packages often define
+.BR TS ,
+.BR T& ,
+and
+.B TE
+macros to handle issues of table placement on the page.
+.
+.I \%@g@tbl
+produces
+.I groff
+code to define these macros as empty if their definitions do not exist
+when the formatter encounters a table region.)
+.
+.
+.P
+Each table definition has the following structure.
.
-Each table definition has the following structure:
.
.TP
.I Global options
@@ -147,6 +180,7 @@ The
must always be finished by a
.B "semi-colon ;" .
.
+.
.TP
.I Table format specification
.
@@ -157,12 +191,12 @@ Each cell in a column is classified by being
centered,
left-aligned,
numeric
-(aligned to a decimal separator),
+(aligned to a configurable decimal separator),
and so on.
.
This specification can have several lines,
but must be finished by a
-.B dot .
+.B dot .\&
at the end of the last line.
.
After each cell definition,
@@ -187,81 +221,99 @@ is an arbitrary character.
.
The line immediately following the
.B .TS
-macro may contain any of the following global options (ignoring the
-case of characters \[en] Unix tbl only accepts options with all
-characters lowercase or all characters uppercase), separated by
-spaces, tabs, or commas:
+macro may contain any of the following global options
+(ignoring the
+case of characters\[em]AT&T
+.I tbl \" AT&T
+accepted only options with all characters in the same lettercase),
+separated by
+spaces,
+tabs,
+or commas.
+.
.
.TP
.B allbox
Enclose each item of the table in a box.
.
+.
.TP
.B box
Enclose the table in a box.
.
+.
.TP
.B center
-Center the table
-(default is left-justified).
+Center the table;
+the default is to left-align it.
.
-The alternative keyword name
+As a GNU extension,
+the alternative keyword name
.B centre
-is also recognized
-(this is a GNU
-.I tbl \" exception
-extension).
+is also recognized.
+.
.
.TP
.BI decimalpoint( c )
Set the character to be recognized as the decimal separator in numeric
-columns
-(GNU
-.I tbl \" exception
-only).
+columns.
+.
+This is a GNU extension.
+.
.
.TP
.BI delim( xy )
Use
.I x
.RI and\~ y
-as start and end delimiters for
+as the start and end delimiters for
.MR @g@eqn @MAN1EXT@ .
.
+.
.TP
.B doublebox
Enclose the table in a double box.
.
+.
.TP
.B doubleframe
Same as
-.B doublebox
-(GNU
-.I tbl \" exception
-only).
+.BR doublebox .
+.
+This is a GNU extension.
+.
.
.TP
.B expand
-Make the table as wide as the current line length (providing a column
+Make the table as wide as the current line length
+(providing a column
separation factor).
.
-Ignored if one or more \[oq]x\[cq] column specifiers are used (see
-below).
+Ignored if one or more
+.RB \[lq] x \[rq]
+column specifiers are used
+(see below).
+.
.
.IP
-In case the sum of the column widths is larger than the current line
-length,
+If 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.
.
+.I \%@g@tbl
+generates
+.I groff
+code to issue a diagnostic warning in this case.
+.
+.
.TP
.B frame
Same as
-.B box
-(GNU
-.I tbl \" exception
-only).
+.BR box .
+.
+This is a GNU extension.
+.
.
.TP
.BI linesize( n )
@@ -273,34 +325,37 @@ in
.IR n -point
type.
.
+.
.TP
.B nokeep
-Don't use diversions to prevent page breaks
-(GNU
-.I tbl
-only).
+Don't use diversions to prevent page breaks.
.
-Normally
+Normally,
.I \%@g@tbl
attempts to prevent undesirable breaks in boxed tables by using
diversions.
.
This can sometimes interact badly with macro packages' own use of
-diversions\[em]when footnotes, for example, are used.
+diversions\[em]when footnotes,
+for example,
+are used.
+.
+This is a GNU extension.
+.
.
.TP
.B nospaces
-Ignore leading and trailing spaces in data items
-(GNU
-.I tbl \" exception
-only).
+Ignore leading and trailing spaces in table entries.
+.
+This is a GNU extension.
+.
.
.TP
.B nowarn
-Turn off warnings related to tables exceeding the current line width
-(GNU
-.I tbl \" exception
-only).
+Turn off warnings related to tables exceeding the current line width.
+.
+This is a GNU extension.
+.
.
.TP
.BI tab( x )
@@ -312,8 +367,8 @@ instead of a tab to separate items in a line of input data.
.LP
The global options must end with a semicolon.
.
-There might be whitespace between an option and its argument in
-parentheses.
+Spaces and tabs are permitted between an option's name and its
+parenthesized argument.
.
.
.\" ====================================================================
@@ -505,55 +560,59 @@ delimiters for that purpose.
.
.TP
.BR r , R
-Right-justify item within the column.
+Right-align item within the column.
+.
.
.TP
-.BR s , S
-Span previous item on the left into this column.
+.BR s ,\~ S
+Span previous item on the left into this column
+(not allowed in the first column).
.
-Not allowed for the first column.
.
.TP
.B ^
-Span down entry from previous row in this column.
+Span down entry from previous row in this column
+(not allowed on the first row).
.
-Not allowed for the first row.
.
.TP
-.BR _ , -
-Replace this entry with a horizontal line.
+.BR _ ,\~ \-
+Replace table entry with a horizontal rule.
.
-Note that \[oq]_\[cq] and \[oq]-\[cq] can be used for table fields only,
-not for column separator lines.
.
.TP
.B =
+Replace table entry with a double horizontal rule.
.
-Replace this entry with a double horizontal line.
-.
-Note that \[oq]=\[cq] can be used for table fields only,
-not for column separator lines.
.
.TP
.B |
-The corresponding column becomes a vertical rule (if two of these are
-adjacent, a double vertical rule).
+Make the corresponding column a vertical rule
+(if two of these are adjacent,
+a double vertical rule).
.
.
-.LP
+.P
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
-To change the data format within a table, use the
+.P
+To change the table format within a
+.I tbl
+region,
+use the
.B .T&
-command (at the start of a line).
+token at the start of a line.
.
-It is followed by format and data lines (but no global options)
-similar to the
+It is followed by format and data lines
+(but no global options)
+similarly to the
.B .TS
-request.
+token.
+.
+The quantity of columns in a new table format thus introduced cannot
+increase relative to the previous table format.
.
.
.\" ====================================================================
@@ -692,7 +751,7 @@ and
The macro should contain only simple
.I roff
requests to change the text block formatting,
-like text adjustment,
+like adjustment,
hyphenation,
size,
or font.
@@ -827,17 +886,22 @@ Within such data lines, items are normally separated by
tab characters
option).
.
Long input lines can be broken across multiple lines if the last
-character on the line is \[oq]\[rs]\[cq] (which vanishes after
+character on the line is \[lq]\[rs]\[rq]
+(which vanishes after
concatenation).
.
.
-.LP
-Note that
+.P
.I \%@g@tbl
-computes the column widths line by line, applying \[rs]w on each entry
-which isn't a text block.
+computes the column widths line by line,
+applying the
+.I roff
+escape sequence
+.B \[rs]w
+to each entry that isn't a text block.
.
-As a consequence, constructions like
+As a consequence,
+constructions like
.IP
.EX
\&.TS
@@ -1046,9 +1110,11 @@ arithmetic.
.
.MR @g@tbl @MAN1EXT@
should always be called before
-.MR @g@eqn @MAN1EXT@
-.RI ( groff (@MAN1EXT@)
-automatically takes care of the correct order of preprocessors).
+.MR @g@eqn @MAN1EXT@ .
+.
+(\c
+.MR groff @MAN1EXT@
+automatically takes care of the correct order of preprocessors.)
.
Don't call the
.B EQ
@@ -1107,50 +1173,62 @@ you should avoid using any names beginning with
.
Since
.I \%@g@tbl
-defines its own macros (right before each table) it is necessary to use
-an \[oq]end-of-macro\[cq] macro.
-.
-Additionally, the escape character has to be switched off.
+defines its own macros at the beginning of each table region,
+it is necessary to call end macros instead of ending macro definitions
+with
+.RB \[lq] ..\& \[rq].
+.\" XXX: Why don't we fix that by ending all of tbl's own macro
+.\" definitions with a call to a macro in its own reserved name space?
.
-Here's an example.
+Additionally,
+the escape character must be disabled.
.
.
-.IP
+.RS
+.P
.EX
+\&.de END
+\&..
\&.eo
-\&.de ATABLE ..
+\&.de MYTABLE END
\&.TS
\&allbox tab(;);
\&cl.
-\&\[rs]$1;\[rs]$2
+\&This is table \[rs]$1.;\[rs]$2
\&.TE
-\&...
+\&.END
\&.ec
-\&.ATABLE A table
-\&.ATABLE Another table
-\&.ATABLE And \[dq]another one\[dq]
+\&.MYTABLE 1 alpha
+\&.MYTABLE 2 beta
+\&.MYTABLE 3 "gamma delta"
.EE
+.RE
.
.
-.LP
-Note, however, that not all features of
+.P
+However,
+not all features of
.I \%@g@tbl
-can be wrapped into a macro because
+can be exercised from such macros because
.I \%@g@tbl
-sees the input earlier than
-.IR \%@g@troff .
+is a
+.I roff
+preprocessor:
+it sees the input earlier than
+.I \%@g@troff
+does.
.
For example,
-number formatting with vertically aligned decimal separators fails if
-those numbers are passed on as macro parameters
-because decimal separator alignment is handled by
+vertically aligning decimal separators fails if the numbers containing
+them occur as macro parameters;
+the alignment is performed by
.I \%@g@tbl
-itself:
-it only sees
+itself,
+which sees only
.BR \[rs]$1 ,
.BR \[rs]$2 ,
-etc.,
-and therefore can't recognize the decimal separator.
+and so on,
+and therefore can't recognize a decimal separator that may be present.
.
.
.\" ====================================================================
@@ -1169,14 +1247,17 @@ all exit afterward.
.
.TP
.B \-C
-Enable compatibility mode to
+Enable AT&T compatibility mode:
recognize
.B .TS
and
.B .TE
even when followed by a character other than space or newline.
.
-Leader characters (\[rs]a) are handled as interpreted.
+The uninterpreted leader escape sequence,
+.BR \[rs]a ,
+.I is
+interpreted.
.
.
.\" ====================================================================
@@ -1205,7 +1286,7 @@ A text block within a table must be able to fit on one
page.
.LP
The
.B bp
-request cannot be used to force a page-break in a multi-page table.
+request cannot be used to force a page break in a multi-page table.
.
Instead, define
.B BP
@@ -1227,26 +1308,46 @@ instead of
.BR bp .
.
.
-.LP
-Using \[rs]a directly in a table to get leaders does not work (except in
-compatibility mode).
-.
-This is correct behavior: \[rs]a is an
-.B uninterpreted
+.P
+Using
+.B \[rs]a
+to put leaders in table entries does not work,
+except in compatibility mode.
+.
+This is correct behavior:
+.B \[rs]a
+is an
+.I uninterpreted
leader.
.
-To get leaders use a real leader, either by using a control A or like
-this:
+You can still use the
+.I roff
+leader character (Control+A) or define a string to use
+.B \[rs]a
+as it was designed:
+to be interpreted only in copy mode.
+.
.
-.IP
+.RS
+.P
.EX
\&.ds a \[rs]a
\&.TS
-\&tab(;);
-\&lw(1i) l.
-\&A\[rs]*a;B
+\&box center tab(;);
+\&lw(2i)0 l.
+\&Population\[rs]*a;6,327,119
\&.TE
.EE
+.RE
+.
+.
+.\" We use a real leader to avoid defining a string in a man page.
+.P
+.TS
+box center tab(;);
+lw(2i)0 l.
+Population;6,327,119
+.TE
.
.
.LP
_______________________________________________
Groff-commit mailing list
Groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit
