[groff] 21/46: doc/groff.texi (Manipulating Hyphenation): Tweak.

[G. Branden Robinson]

gbranden pushed a commit to branch dev-gropdf-boxes
in repository groff.

commit 62373e779f0ca76aeb8c5ed62385cc6ebc28b89a
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Apr 11 10:40:44 2021 +1000

    doc/groff.texi (Manipulating Hyphenation): Tweak.
    
    - Clarify forward reference within node.
    - Shift description of .hy register and environment association to lead
      paragraph of .hy request description since over a page and a half is
      given over to discussion of the semantics of the argument and its
      interaction with hyphenation pattern files.
    - Recast forward reference to table since it has a tendency to end up on
      the next page.
    - Note that .hy value 2 applies even to manual hyphenation points.
    - Follow "U.S." with Texinfo @: command since the Texinfo manual
      recommends it.
    - Add forward reference within node.
    - Adjust wording of hcode example.
---
 doc/groff.texi | 70 ++++++++++++++++++++++++++++------------------------------
 1 file changed, 34 insertions(+), 36 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 9118886..813bbb8 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -7300,9 +7300,9 @@ within-word placement restrictions imposed by the 
@code{hy} request (see
 below).
 
 Hyphenation exceptions specified with the @code{hw} request are
-associated with the hyphenation language (see below) and environment
-(@pxref{Environments}); calling the @code{hw} request in the absence of
-a hyphenation language is an error.
+associated with the hyphenation language (see the @code{hla} request
+below) and environment (@pxref{Environments}); calling the @code{hw}
+request in the absence of a hyphenation language is an error.
 
 The request is ignored if there are no parameters.
 @endDefreq
@@ -7411,10 +7411,13 @@ lines have been hyphenated (@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}).
 
+@cindex hyphenation mode register (@code{.hy})
 @DefreqList {hy, [@Var{mode}]}
 @DefregListEndx {.hy}
-Set automatic hyphenation mode to @var{mode}.  The optional numeric
-argument @var{mode} encodes conditions for hyphenation.
+Set automatic hyphenation mode to @var{mode}, an integer encoding
+conditions for hyphenation.  The hyphenation mode is available in the
+read-only register @samp{.hy}; it is associated with the environment
+(@pxref{Environments}).
 
 Typesetting practice generally does not avail itself of every
 opportunity for hyphenation, but the details differ by language and site
@@ -7429,9 +7432,9 @@ sought.@footnote{The mode is a vector of booleans encoded 
as an integer.
 To a programmer, this fact is easily deduced from the exclusive use of
 powers of two for the configuration parameters; they are computationally
 easy to ``mask off'' and compare to zero.  To almost everyone else, the
-arrangement seems recondite and unfriendly.}  The entries in the table
-below are termed @dfn{values}, and the sum of the desired values is the
-@dfn{mode}.
+arrangement seems recondite and unfriendly.}  The entries in the
+following table are termed @dfn{values}; the sum of the desired
+values is the @dfn{mode}.
 
 @table @code
 @item 0
@@ -7449,14 +7452,14 @@ restrictions relative to that basis.
 
 @table @code
 @item 2
-disables hyphenation of the last word on a page.@footnote{This value
-prevents hyphenation if the next page location trap is closer than the
-next text baseline would be.  GNU @code{troff} automatically inserts an
-implicit vertical position trap at the end of each page to cause a page
+disables hyphenation of the last word on a page,@footnote{Hyphenation is
+prevented if the next page location trap is closer than the next text
+baseline would be.  GNU @code{troff} automatically inserts an implicit
+vertical position trap at the end of each page to cause a page
 transition.  Users or macro packages can set such traps explicitly to
 prevent hyphenation of the last word in a column in multi-column page
-layouts or before floating figures or tables.
-@xref{Page Location Traps}.}
+layouts or before floating figures or tables.  @xref{Page Location
+Traps}.} even for manually hyphenated words.
 
 @item 4
 disables hyphenation before the last two characters of a word.
@@ -7510,12 +7513,12 @@ s- plit- t- in- g
 @endExample
 
 @noindent
-instead of the correct `split- ting'.  U.S. English patterns as
+instead of the correct `split- ting'.  U.S.@: English patterns as
 distributed with GNU @code{troff} need two characters at the beginning
 and three characters at the end; this means that value@tie{}4 of
 @code{hy} is mandatory.  Value@tie{}8 is possible as an additional
 restriction, but values@tie{}16 and@tie{}32 should be avoided, as should
-mode@tie{}1 (the default!).  Modes@tie{}4 and@tie{}6 are typical.
+mode@tie{}1.  Modes@tie{}4 and@tie{}6 are typical.
 
 A table of left and right minimum character counts for hyphenation as
 needed by the patterns distributed with GNU @code{troff} follows; see
@@ -7536,12 +7539,6 @@ Hyphenation exceptions within pattern files (i.e., the 
words within a
 @TeX{} @code{\hyphenation} group) also obey the hyphenation restrictions
 given by @code{hy}.  However, exceptions specified with @code{hw} do
 not.
-
-The hyphenation mode is associated with the environment
-(@pxref{Environments}).
-
-@cindex hyphenation mode register (@code{.hy})
-The hyphenation mode can be found in the read-only register @samp{.hy}.
 @endDefreq
 
 @Defreq {nh, }
@@ -7617,9 +7614,9 @@ be used.  By default, every code maps to itself except 
those for letters
 @pindex hyphen.us
 @pindex hyphenex.us
 The set of hyphenation patterns is associated with the language set by
-the @code{hla} request.  The @code{hpf} request is usually invoked by
-the @file{troffrc} or @file{troffrc-end} file; by default,
-@file{troffrc} loads hyphenation patterns and exceptions for U.S.
+the @code{hla} request (see below).  The @code{hpf} request is usually
+invoked by the @file{troffrc} or @file{troffrc-end} file; by default,
+@file{troffrc} loads hyphenation patterns and exceptions for U.S.@:
 English (in files @file{hyphen.us} and @file{hyphenex.us}).
 
 A second call to @code{hpf} (for the same language) replaces the
@@ -7651,9 +7648,10 @@ they assume that the words `FOO' and `Foo' should be 
hyphenated exactly
 as `foo' is.  The @code{hcode} request extends this principle to letters
 outside the Unicode basic Latin alphabet; without it, words containing
 such letters won't be hyphenated properly even if the corresponding
-hyphenation patterns contain them.  For example, the following
-@code{hcode} requests are necessary to assign hyphenation codes to the
-letters @samp{�������} (needed for German):
+hyphenation patterns contain them.
+
+For example, the following @code{hcode} requests are necessary to assign
+hyphenation codes to the letters @samp{�������}, needed for German.
 
 @Example
 .hcode � �  � �
@@ -7662,13 +7660,13 @@ letters @samp{
 .hcode � �
 @endExample
 
-Without those assignments, GNU @code{troff} treats German words like
-@w{`Kinderg�rten'} (the plural form of `kindergarten') as two substrings
+Without these assignments, GNU @code{troff} treats the German word
+@w{`Kinderg�rten'} (the plural form of `kindergarten') as two words
 @w{`kinderg'} and @w{`rten'} because the hyphenation code of the
-umlaut@tie{}a is zero by default.  There is a German hyphenation pattern
-that covers @w{`kinder'}, so GNU @code{troff} finds the hyphenation
-`kin-der'.  The other two hyphenation points (`kin-der-g�r-ten') are
-missed.
+umlaut@tie{}a is zero by default, just like a space.  There is a German
+hyphenation pattern that covers @w{`kinder'}, so GNU @code{troff} finds
+the hyphenation `kin-der'.  The other two hyphenation points
+(`kin-der-g�r-ten') are missed.
 @endDefreq
 
 @DefreqList {hla, lang}
@@ -7682,7 +7680,7 @@ specified with the @code{hw} request and hyphenation 
patterns and
 exceptions specified with the @code{hpf} and @code{hpfa} requests are
 associated with the hyphenation language.  The @code{hla} request is
 usually invoked by the @file{troffrc} or @file{troffrc-end} files;
-@file{troffrc} sets the default language to @samp{us} (U.S. English).
+@file{troffrc} sets the default language to @samp{us} (U.S.@: English).
 
 @cindex hyphenation language register (@code{.hla})
 The hyphenation language is available in the read-only string-valued
@@ -15406,7 +15404,7 @@ implementations.
 @cindex hyphenation, incompatibilities with @acronym{AT&T} @code{troff}
 GNU @code{troff} does not always hyphenate words as @acronym{AT&T}
 @code{troff} does.  The @acronym{AT&T} implementation uses a set of
-hard-coded rules specific to U.S. English, while GNU @code{troff} uses
+hard-coded rules specific to U.S.@: English, while GNU @code{troff} uses
 language-specific hyphenation pattern files derived from @TeX{}.
 Furthermore, in old versions of @code{troff} there was a limited amount
 of space to store hyphenation exceptions (arguments to the @code{hw}