[groff] 03/12: tbl(1): Fix content problems and style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7168d599882915ed9ff3e7ced9d13ef597bd6f21
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Nov 16 12:47:42 2021 +1100

    tbl(1): Fix content problems and style nits.
    
    Content:
    * Fix error: region options must appear on one input line only.
    * Further clarify the scope of what they do.
    * Go lighter on the term "keyword".  The main reason to use it at all is
      to distinguish from the character-encoded format descriptors.
    * Clarify that the "center" option applies to the _region_, not a
      "table".  Whether ".T&" starts a "new table" or not depends largely on
      how it is used.
    * Clarify that the "delim" option enables tbl(1) to identify input for
      the purpose of ignoring it.
    * Clarify that the "nokeep" option has broader applicability than to
      boxed tables.
    * Introduce the syntax of format specifiers with more precision
      (character-based parsing, again).
    * Clarify that _all_ A-classified entries are indented, not just the
      ones that aren't the longest.
    * Demote the "sub-columns" term to a single mention.
    * Recast explanation of `\&` in N-classified entries.
    * Recast advice regarding changing the table format.
    * Exhaustively list the column modifiers that the `m` modifier might
      override.
    * When noting GNU tbl enhancements, direct reader to extensions already
      discussed.
    
    Style:
    * Use colon instead of semicolon when the second independent clause
      explains the first.
    * Tighten wording.
    * Fix typos.
---
 src/preproc/tbl/tbl.1.man | 90 ++++++++++++++++++++++-------------------------
 1 file changed, 43 insertions(+), 47 deletions(-)

diff --git a/src/preproc/tbl/tbl.1.man b/src/preproc/tbl/tbl.1.man
index c2d4ee3..526b4f1 100644
--- a/src/preproc/tbl/tbl.1.man
+++ b/src/preproc/tbl/tbl.1.man
@@ -183,27 +183,21 @@ These entries comprise the
 .SS "Region options"
 .\" ====================================================================
 .
-The lines immediately following the
+The line immediately following the
 .B .TS
-token may specify region options,
-keywords that influence the rendering of the tables in that region as a
-whole or all of their entries indiscriminately.
+token may specify region options:
+keywords that influence the interpretation or rendering of the region as
+a whole or all table entries within it indiscriminately.
 .
-Some of these keywords require a parenthesized argument.
+Some of these options require a parenthesized argument.
 .
-The option keywords can be specified in any lettercase and must be
-separated by commas,
+They can be specified in any lettercase and must be separated by commas,
 spaces,
-tabs,
-or newlines.
+or tabs.
 .
 (AT&T
 .I tbl \" AT&T
-accepted only options with all characters in the same lettercase,
-separated by
-spaces,
-tabs,
-or commas.)
+accepted only options with all characters in the same lettercase.)
 .
 Spaces and tabs are permitted between an option's name and its
 parenthesized argument.
@@ -244,7 +238,7 @@ is also recognized.
 .
 .TP
 .B center
-Center the table with respect to the current indentation and line
+Center the table region with respect to the current indentation and line
 length;
 the default is to left-align it.
 .
@@ -268,14 +262,15 @@ This is a GNU extension.
 .
 .TP
 .BI delim( xy )
-Use characters
+Recognize characters
 .I x
 .RI and\~ y
-as the start and end delimiters,
+as start and end delimiters,
 respectively,
 for
 .MR @g@eqn @MAN1EXT@
-input.
+input,
+and ignore input between them.
 .
 .
 .TP
@@ -331,8 +326,7 @@ Don't use diversions to prevent page breaks.
 .
 Normally,
 .I \%@g@tbl
-attempts to prevent undesirable breaks in boxed tables by using
-diversions.
+attempts to prevent undesirable breaks in tables by using diversions.
 .
 This can sometimes interact badly with macro packages' own use of
 diversions\[em]when footnotes,
@@ -369,7 +363,7 @@ instead of a tab to separate entries in a row of table data.
 .SS "Table format specification"
 .\" ====================================================================
 .
-The table format specification is mandatory;
+The table format specification is mandatory:
 it determines the number of columns in the table and directs how the
 entries within it are to be typeset.
 .
@@ -400,8 +394,10 @@ only some modifiers,
 described below,
 make separation necessary.
 .
-Most column classifiers and modifiers are letters;
-they are recognized case-insensitively.
+Column classifiers are letters or punctuation symbols,
+whereas modifiers consist of or begin with letters or numerals.
+.
+Both are recognized case-insensitively.
 .
 .
 .P
@@ -491,23 +487,20 @@ classifiers are the easiest to understand and use.
 .BR A ,\~ a
 Center longest entry in this column;
 left-align remaining entries in the column with respect to the centered
-entry and indent them by one en.
+entry,
+then indent them all by one en.
 .
-The idea is to use such alphabetic sub-columns
+Such \[lq]alphabetic\[rq] entries
 (hence the name of the classifier)
-in combination
-.RB with\~ L
-such that
-.B A
-and
-.B L
-classifications share a column,
+can be used in the same column as
+.BR L -classified
+entries,
 as in
 .RB \[lq] LL,AR.\& \[rq].
 .
 The
 .B A
-entries are termed sub-columns due to their indentation.
+entries are often termed \[lq]sub-columns\[rq] due to their indentation.
 .
 .
 .TP
@@ -534,10 +527,10 @@ use the rightmost digit for vertical alignment;
 otherwise,
 center the entry within the column.
 .
-Alignment can be forced to a certain position using
-.BR \[rs]& ;
-if multiple instances of this non-printing token are present in the
-data,
+The non-printing input token
+.B \[rs]&
+forces alignment to its position;
+if multiple instances of it occur in the data,
 use the leftmost one for alignment.
 .
 .
@@ -568,7 +561,7 @@ Using equations
 .IR \%@g@eqn )
 within
 .BR N -classified
-columms
+columns
 is often troublesome due to the foregoing algorithm for finding the
 vertical alignment.
 .
@@ -652,14 +645,14 @@ increase relative to the previous table format;
 in that case,
 you must end the table region and start another.
 .
-If that will not serve because the region uses box options or the column
-widths are incompatible,
-you must design the initial table format specification to designate the
+If that will not serve because the region uses box options or the
+columns align in an undesirable manner,
+you must design the initial table format specification to include the
 maximum quantity of columns required,
 and use the
 .B S
-horizontal spanning classifier to achieve the desired columnar
-alignment.
+horizontal spanning classifier where necessary to achieve the desired
+columnar alignment.
 .
 .
 .\" ====================================================================
@@ -778,10 +771,12 @@ like adjustment or hyphenation.
 .
 The macro is called
 .I after
-other column modifiers like
+other the column modifiers
 .BR b ,
 .BR f ,
-or
+.BR i ,
+.BR p ,
+and
 .B v
 take effect.
 .
@@ -1279,7 +1274,7 @@ contingent upon an
 .BR el ,
 or
 .B while
-requests)
+request)
 can result in misleading line numbers in subsequent diagnostics.
 .
 .I \%@g@tbl
@@ -1330,9 +1325,10 @@ will recognize them.
 .\" ====================================================================
 .
 .ne 3v
+In addition to extensions noted above,
 GNU
 .I tbl \" GNU
-removes many constraints endured by users of AT&T
+removes constraints endured by users of AT&T
 .IR tbl .\" AT&T
 .
 .