[groff] 29/46: [docs]: Fix content, style, and markup nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit e6904b4bad23302e4168c1307a70805478798b59
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Dec 3 22:58:26 2022 -0600

    [docs]: Fix content, style, and markup nits.
    
    First, Dave Kemper rightly pointed out some fractured grammar in our
    Texinfo manual <https://lists.gnu.org/archive/html/groff/2022-12/\
    msg00002.html>.  I went to fix that, found that some tightening and
    terminology correction could be done, did it, synced with groff(7),
    and then found that my precious dead-tree page breaks were thrown off,
    producing widows and orphans through the remainder of the page.
    
    This is what happens when man(7) doesn't have keep macros...
    
    Content:
    * Fix "value"/"mode" confusion in hyphenation discussion.
    * Use (now-)standard terminology when discussing underlining.  Say
      "escape sequence" instead of "escape".  Say "underrule" instead of
      "underline character" (there is a difference, now explained).  Make
      example of \z and \(ul use slightly more realistic.
    
    Style:
    * Drop word "explicitly" in hyphenation discussion since we have already
      used "explicit" as a term for "literal" hyphens (e.g., "big-nosed").
    * Fix grammar gaffe.
    * Tighten wording.
    * Recast discussion of underlining.  (I continue to question the worth
      of having this material where it is.)
    
    Markup:
    * groff(7): Break input lines after commas.
---
 doc/groff.texi  |  14 +++----
 man/groff.7.man | 111 ++++++++++++++++++++++++++------------------------------
 2 files changed, 58 insertions(+), 67 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index dcfbe0c7c..9a9de097e 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -8381,9 +8381,9 @@ automatically determined hyphenation points are 
permissible.  The places
 within a word that are eligible for hyphenation are determined by
 language-specific data and lettercase relationships.  Furthermore,
 hyphenation of a word might be suppressed due to a limit on
-consecutive hyphenated lines (@code{hlm}), the line has not reached a
-certain minimum length (@code{hym}), or the line can instead be adjusted
-with up to a certain amount of additional inter-word space (@code{hys}).
+consecutive hyphenated lines (@code{hlm}), a minimum line length
+threshold, certain minimum length (@code{hym}), or because the line can
+instead be adjusted with additional inter-word space (@code{hys}).
 
 @cindex hyphenation mode register (@code{.hy})
 @DefreqList {hy, [@Var{mode}]}
@@ -8452,11 +8452,11 @@ enables hyphenation after the first character of a word.
 
 Apart from value@tie{}2, restrictions imposed by the hyphenation mode
 are @emph{not} respected for words whose hyphenations have been
-explicitly specified with the hyphenation character (@samp{\%} by
-default) or the @code{hw} request.
+specified with the hyphenation character (@samp{\%} by default) or the
+@code{hw} request.
 
-The nonzero values in the previous table are additive.  For example,
-value@tie{}12 causes GNU @code{troff} to hyphenate neither the last two
+Nonzero values in the previous table are additive.  For example,
+mode@tie{}12 causes GNU @code{troff} to hyphenate neither the last two
 nor the first two characters of a word.  Some values cannot be used
 together because they contradict; for instance, values 4 and@tie{}16,
 and values 8 and@tie{}32.  As noted, it is superfluous to add 1 to any
diff --git a/man/groff.7.man b/man/groff.7.man
index 5aebe5ff5..4334d00b4 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -6002,8 +6002,8 @@ enables hyphenation after the first character of a word.
 Apart from value\~2,
 restrictions imposed by the hyphenation mode are
 .I not
-respected for words whose hyphenations have been explicitly specified
-with the hyphenation character
+respected for words whose hyphenations have been specified with the
+hyphenation character
 .RB (\[lq] \|\[rs]% \[rq]
 by default)
 or the
@@ -6012,10 +6012,10 @@ request.
 .
 .
 .P
-The nonzero values above are additive.
+Nonzero values are additive.
 .
 For example,
-value\~12 causes
+mode\~12 causes
 .I groff
 to hyphenate neither the last two nor the first two characters of a
 word.
@@ -6045,10 +6045,10 @@ Furthermore,
 hyphenation of a word might be suppressed due to a limit on
 consecutive hyphenated lines
 .RB ( .hlm ),
-the line has not reached a certain minimum length
+a minimum line length threshold
 .RB ( .hym ),
-or the line can instead be adjusted with up to a certain amount of
-additional inter-word space
+or because the line can instead be adjusted with additional inter-word
+space
 .RB ( .hys ).
 .
 .
@@ -6599,9 +6599,12 @@ to
 .SS "Underlining without macro definitions"
 .\" ====================================================================
 .
-If one does not want to use macro definitions, e.g., when
-.B doclifter
-gets lost, use the following:
+If one does not want to use macro definitions,
+e.g.,
+when
+.I doclifter
+gets lost,
+use the following.
 .
 .RS
 .EX
@@ -6616,7 +6619,7 @@ gets lost, use the following:
 .RE
 .
 When using
-.BR doclifter ,
+.IR doclifter ,
 it might be necessary to change syntax forms such as
 .B \e[xy]
 and
@@ -6656,75 +6659,63 @@ after
 .
 .
 .\" ====================================================================
-.SS "Underlining with overstriking \ez and \e(ul"
+.SS "Underlining by overstriking with \e(ul"
 .\" ====================================================================
 .
-There is another possibility for underlining by using overstriking
-with
-.BI \ez c
-(print
-.I c
-with zero width without spacing) and
-.B \e(ul
-(underline character).
-.
-This produces the underlining of 1 character, both in
-.B nroff
-and in
-.BR troff .
+You can use the
+.B \[rs]z
+escape sequence to format a glyph while suppressing advancement of its
+drawing position;
+this is another form of overstriking.
 .
+Thus,
+.BI \[rs]z c \[rs](ul
+formats
+.I c
+without advancement,
+then draws the underrule glyph on top of it.
 .
-.P
-For example the underlining of a character say
-.B t
-looks like
-.B \ez\e[ul]t
-or
-.B \ez\e(ult
+Because video terminals implement the underrule glyph by setting the
+underline attribute on the character cell,
+this works in both
+.I nroff \" mode
+and
+.I troff \" mode
+modes.
 .
 .
 .P
-Longer words look then a bit strange, but a useful mode is to write
-each character into a whole own line.
+Long words may then look intimidating in the input;
+a clarifying approach might be to use the input line continuation escape
+sequence
+.BI \[rs] newline
+to place each underlined character on its own input line.
 .
-To underlines the 3 character part "tar" of the word "start":
+Thus,
 .
 .RS
 .EX
-.br
-before s\[rs]
-\[rs]z\[rs][ul]t\[rs]
-\[rs]z\[rs][ul]a\[rs]
-\[rs]z\[rs][ul]r\[rs]
-t after
+\&.nf
+\[rs]&\[rs]fB: ${\[rs]fIvar\[rs]fR\[rs]c
+\[rs]zo\[rs](ul\[rs]
+\[rs]zp\[rs](ul\[rs]c
+\[rs]&\[rs]fIvalue\[rs]fB}
+\&.fi
 .EE
 .RE
 .
-or
+produces
 .
 .RS
 .EX
-.br
-before s\[rs]
-\[rs]z\[rs](ult\[rs]
-\[rs]z\[rs](ula\[rs]
-\[rs]z\[rs](ulr\[rs]
-t after
+.BI ": ${" var \c
+\zo\(ul\
+\zp\(ul\c
+.IB value }
 .EE
 .RE
 .
-.
-.P
-The result looks like
-.RS
-.ft CR
-before s\
-\z\[ul]t\
-\z\[ul]a\
-\z\[ul]r\
-t after
-.ft R
-.RE
+as output.
 .
 .
 .\" ====================================================================