[groff] 05/46: [docs]: Revise hyphenation discussion.

[G. Branden Robinson]

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

commit fc719bf85667c605d53591949dc04d895128c40d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Apr 6 14:50:08 2021 +1000

    [docs]: Revise hyphenation discussion.
    
    * doc/groff.texi (Manipulating Hyphenation):
      - Recast introductory paragraph to better distinguish between the
        automatic breaking of words and placement of hyphens at
        user-specified hyphenation points (done with the \% escape) and
        automatic determination of hyphenation points within words (what the
        pattern files and most of the hyphenation mode parameters are for).
        Clarify that what our manual calls "automatic hyphenation" pertains
        only to the latter.
      - Tweak narrative motivating manual hyphenation.
      - <hw> Correct over-general claim; hyphenation exceptions defined with
        the .hw request _do_ honor .hy value 2 (don't break a word at the
        bottom of a page), but none of the others.
      - <\:> Clarify that escape is an input word boundary.
      - <shc> Reorganize discussion of soft hyphen glyph-setting request.
        Recast; "hyphenation" as defined in this manual always implies a
        break.  Clarify that the soft hyphen glyph is applied to manual as
        well as automatically-determined hyphenation points.  (This further
        distinguishes such points from "explicit" hyphens, as in
        "mother-in-law".)  Change more uses of soft hyphen "character" to
        "glyph".  Tighten wording.
      - Move concept index entry for "automatic hyphenation" to first
        discussion of the concept instead of immediately prior to the .hy
        request entry.
      - Add concept index entries for "automatic hyphenation parameters",
        "explicit hyphenation", "manual hyphenation", and altenate orderings
        of these words.
      - <hy> Recharacterize as setting the _automatic_ hyphenation mode.
        Tighten wording in footnote regarding vertical location traps.  Note
        that restrictions apart from value 2 are not applied to words with
        manually-assigned hyphenation points.
    
    * man/groff_diff.7.man (Language/Escape sequences) <\:>: Drop example.
    
    * man/groff.7.man (Hyphenation): Mention .hw request and its purpose in
      introductory paragraph.  Contrast with default of automatic
      determination of hyphenation points.
    
    * man/groff_diff.7.man (Language/New requests) <shc>:
    * man/groff.7.man (Hyphenation): Resync with our Texinfo manual.
    
    Continues addressing <https://savannah.gnu.org/bugs/?60332>.
---
 ChangeLog            | 37 ++++++++++++++++------
 doc/groff.texi       | 87 +++++++++++++++++++++++++++-------------------------
 man/groff.7.man      | 39 +++++++++++++++--------
 man/groff_diff.7.man | 47 +++++++++-------------------
 4 files changed, 114 insertions(+), 96 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 4f6d0ef..d0157f1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,12 +1,31 @@
-2021-03-24  G. Branden Robinson <g.branden.robinson@gmail.com>
-
-       * doc/groff.texi (Manipulating Hyphenation): Recast description
-       of \% escape to emphasize independence of its two uses (e.g.,
-       "\%pseudo\%unununium" is hyphenated only after "pseudo-", if at
-       all).  Add example.  Note that .nh affects only automatic
-       hyphenation.
-       * man/groff.7.man (Requests/Request short reference) <.nh>:
-       Clarify that the request disables only _automatic_ hyphenation.
+2021-04-06  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * doc/groff.texi (Manipulating Hyphenation):
+       Recast introductory paragraph to better distinguish between the
+       automatic breaking of words and placement of hyphens at
+       user-specified hyphenation points (done with the \% escape) and
+       automatic determination of hyphenation points within words (what
+       the pattern files and most of the hyphenation mode parameters
+       are for).  Clarify that what our manual calls "automatic
+       hyphenation" pertains only to the latter.
+       <hw> Correct over-general claim; hyphenation exceptions defined
+       with the .hw request _do_ honor .hy value 2 (don't break a word
+       at the bottom of a page), but none of the others.
+       <\%> Recast description of escape to emphasize independence of
+       its two uses (e.g., "\%pseudo\%unununium" is hyphenated only
+       after "pseudo-", if at all).
+       <\:> Clarify that escape is an input word boundary.
+       <shc> Clarify that the soft hyphen glyph is applied to manual as
+       well as automatically-determined hyphenation points.
+       <hy> Recharacterize as setting the _automatic_ hyphenation mode.
+       Note that restrictions apart from value 2 are not applied to
+       words with manually-assigned hyphenation points.
+       <nh> Note that request affects only automatic hyphenation.
+
+       * man/groff.7.man (Requests/Request short reference) <.hy,.nh>:
+       Clarify that requests deal with _automatic_ hyphenation.
+       (Registers/Read-only registers) <.hy>:
+       Clarify that register applies to _automatic_ hyphenation.
        (Hyphenation): Add new introductory paragraph summarizing manual
        hyphenation support and features, including notice that breaking
        at explicit hyphens is performed in fill mode, i.e., even if
diff --git a/doc/groff.texi b/doc/groff.texi
index 9a4b739..7789362 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -7246,19 +7246,24 @@ If @emph{undiscardable} space is required, use the 
@code{\h} escape.
 @cindex manipulating hyphenation
 @cindex hyphenation, manipulating
 
-GNU @code{troff} hyphenates words automatically by default.  Automatic
-hyphenation of words in natural languages is a subject requiring
+@cindex hyphenation, automatic
+@cindex automatic hyphenation
+GNU @code{troff} normally hyphenates words where necessary.  The
+machine-driven determination of hyphenation points in words requires
 algorithms and data, and is susceptible to conventions and preferences.
-Before tackling automatic hyphenation, let us consider how it can be
-done manually.
+Before tackling such @dfn{automatic hyphenation}, let us consider how
+hyphenation points can be set manually.
 
+@cindex hyphenation, explicit
+@cindex explicit hyphenation
+@cindex hyphenation, manual
+@cindex manual hyphenation
 Explicitly hyphenated words such as ``mother-in-law'' are eligible for
 breaking after each of their hyphens when GNU @code{troff} fills lines.
 Relatively few words in a language offer such obvious break points,
 however, and automatic hyphenation is not perfect, particularly for
-unusual words found in domain-specific jargon.  We may wish to
-explicitly instruct GNU @code{troff} how to hyphenate words if the need
-arises.
+unusual words found in technical literature.  We may wish to instruct
+GNU @code{troff} how to hyphenate specific words if the need arises.
 
 @cindex hyphenation exceptions
 @Defreq {hw, word @dots{}}
@@ -7281,7 +7286,8 @@ than once.
 
 @cindex @code{hw} request, and @code{hy} restrictions
 Hyphenation points specified with @code{hw} are not subject to the
-restrictions given by the @code{hy} request (see below).
+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
@@ -7333,9 +7339,8 @@ just prior to it; most likely this isn't what you want.
 @cindex breaking URLs (@code{\:})
 The @code{\:} escape inserts a non-printing break point; that is, the
 word can break there, but the soft hyphen glyph is not written to the
-output if it does.  Breaks are word boundaries, so if a break is
-inserted, the remainder of the (input) word is subject to hyphenation as
-normal.
+output if it does.  This escape is an input word boundary, so the
+remainder of the word is subject to hyphenation as normal.
 
 You can use @code{\:} and @code{\%} in combination to control breaking
 of a file name or URL or to permit hyphenation after only certain
@@ -7368,39 +7373,39 @@ The hyphenation character is associated with the 
current environment
 @cindex soft hyphen glyph (@code{hy})
 @cindex @code{char} request, and soft hyphen character
 @cindex @code{tr} request, and soft hyphen character
-Set the @dfn{soft hyphen character} to @var{glyph}.@footnote{``Soft
-hyphen @emph{character}'' is a misnomer since it is an output glyph.}
-If the argument is omitted, the soft hyphen character is set to the
-default, @code{\[hy]}.  The @dfn{soft hyphen character} is the glyph
-that is inserted when a word is automatically hyphenated at a line
-break.@footnote{It is ``soft'' because it only appears in output where
-hyphenation is actually performed; a ``hard'' hyphen, as in
-``long-term'', always appears.}  If the soft hyphen character does not
-exist in the font of the character immediately preceding a potential
-break point, then the line is not broken at that point.  Neither
+Set the @dfn{soft hyphen character},@footnote{``Soft hyphen
+@emph{character}'' is a misnomer since it is an output glyph.} inserted
+when a word is hyphenated automatically or at a hyphenation character
+@code{\%}, to@tie{}@var{glyph}.@footnote{It is ``soft'' because it only
+appears in output where hyphenation is actually performed; a ``hard''
+hyphen, as in ``long-term'', always appears.}  If the argument is
+omitted, the soft hyphen glyph is set to the default, @code{\[hy]}.  If
+the selected glyph does not exist in the font in use at a potential
+hyphenation point, then the line is not broken at that point.  Neither
 character definitions (specified with the @code{char} and similar
 requests) nor translations (specified with the @code{tr} request) are
-considered when assigning the soft hyphen character.
+considered when assigning the soft hyphen glyph.
 @endDefreq
 
-@cindex hyphenation, automatic
+@cindex hyphenation parameters, automatic
+@cindex automatic hyphenation parameters
 Several requests influence automatic hyphenation.  Because conventions
 vary, a variety of hyphenation modes is available to the @code{hy}
-request; these determine whether automatic hyphenation will apply to a
+request; these determine whether hyphenation will apply to a
 word prior to breaking a line at the end of a page (more or less; see
-below for details), and at which positions within that word hyphenation
-is 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
-because too many previous 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}).
+below for details), and at which positions within that word
+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 because too many previous
+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}).
 
 @DefreqList {hy, [@Var{mode}]}
 @DefregListEndx {.hy}
-Set hyphenation mode to @var{mode}.  The optional numeric argument
-@var{mode} encodes conditions for hyphenation.
+Set automatic hyphenation mode to @var{mode}.  The optional numeric
+argument @var{mode} encodes conditions for hyphenation.
 
 Typesetting practice generally does not avail itself of every
 opportunity for hyphenation, but the details differ by language and site
@@ -7439,9 +7444,9 @@ 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
-transition.  This value can be used in traps planted by users or macro
-packages to prevent hyphenation of the last word in a column in
-multi-column page layouts or before floating figures or tables.
+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}.}
 
 @item 4
@@ -7457,10 +7462,10 @@ enables hyphenation before the last character of a word.
 enables hyphenation after the first character of a word.
 @end table
 
-Any 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.
+Apart from value 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.
 
 The nonzero values in the previous table are additive.  For example,
 value@tie{}12 causes GNU @code{troff} to hyphenate neither the last two
diff --git a/man/groff.7.man b/man/groff.7.man
index 7080ce1..43a15f5 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1958,24 +1958,27 @@ with each hyphen
 .RB \[lq] \- \[rq]
 indicating a hyphenation point.
 .
+.
 .TPx
 .REQ .hy
-Set hyphenation mode to
-.B 1
-(the default).
+Set automatic hyphenation mode to
+.BR 1 .
+.
 .
 .TPx
 .REQ .hy \fB0\fP
-Disable hyphenation;
+Disable automatic hyphenation;
 same as
 .BR .nh .
 .
+.
 .TPx
 .REQ .hy mode
-Set hyphenation mode to
+Set automatic hyphenation mode to
 .IR mode ;
 see section \[lq]Hyphenation\[rq] below.
 .
+.
 .TPx
 .REQ .hym
 Set the (right) hyphenation margin to
@@ -2510,16 +2513,19 @@ Define global fallback character (or glyph)\~\c
 as string
 .IR anything .
 .
+.
 .TPx
 .REQ .shc
-Reset soft hyphen glyph to
-.esc (hy .
+Reset the soft hyphen glyph to
+.esc [hy] .
+.
 .
 .TPx
 .REQ .shc c
 Set the soft hyphen glyph
 .RI to\~ c .
 .
+.
 .TPx
 .REQ .shift "n"
 In a macro, shift the arguments by
@@ -4407,7 +4413,7 @@ current environment.
 .
 .TPx
 .REG .hy
-The hyphenation mode in the current environment.
+The automatic hyphenation mode in the current environment.
 .
 .TPx
 .REG .hym
@@ -4879,11 +4885,17 @@ The hyphenation
 .RB character\~ \[rs]%
 and non-printing break
 .RB point\~ \[rs]:
-escapes may be used to control the hyphenation of individual words.
+escapes may be used to control the hyphenation and breaking of
+individual words.
+.
+The
+.B .hw
+request sets user-defined hyphenation points for specified words at any
+subsequent occurrence.
 .
 Otherwise,
 .I groff
-hyphenates words automatically by default.
+determines hyphenation points automatically by default.
 .
 .
 .P
@@ -4893,11 +4905,12 @@ Because conventions vary,
 a variety of hyphenation modes are available to the
 .B .hy
 request;
-these determine whether automatic hyphenation will apply to a word prior
-to breaking a line at the end of a page
+these determine whether hyphenation will apply to a word prior to
+breaking a line at the end of a page
 (more or less;
 see below for details),
-and at which positions within that word hyphenation is permissible.
+and at which positions within that word automatically determined
+hyphenation points are permissible.
 .
 The default is
 .RB \[lq] 1 \[rq]
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 8d548dc..096718c 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -814,6 +814,7 @@ It is a good idea to use this escape sequence whenever a 
roman
 glyph is immediately followed by an italic glyph without any
 intervening space.
 .
+.
 .TP
 .B \[rs]:
 Insert a non-printing break point.
@@ -824,27 +825,8 @@ but the soft hyphen glyph is not written to the output if 
it does
 (in contrast to
 .RB \[lq] \[rs]% \[rq]).
 .
-Note that breaks are word boundaries,
-so if a break is inserted,
-the remainder of the (input) word is subject to hyphenation as normal.
-.
-.
-.IP
-You can use
-.B \[rs]:
-and
-.B \[rs]%
-in combination to control breaking of a filename or URL.
-.
-.
-.RS
-.RS
-.IP
-.EX
-\&.\|.\|.\& check \e%/var/log/\e:\e%httpd/\e:\e%access_log .\|.\|.
-.EE
-.RE
-.RE
+This escape is an input word boundary,
+so the remainder of the word is subject to hyphenation as normal.
 .
 .
 .TP
@@ -2797,25 +2779,24 @@ is searched after the list of fonts declared with the
 .B special
 request but before the mounted special fonts.
 .
+.
 .TP
 .BI .shc\~ glyph
-Set the soft hyphen character
+Set the soft hyphen glyph,
+inserted when a word is hyphenated automatically or at a hyphenation
+character
+.BR \[rs]% ,
 .RI to\~ glyph .
 .
-If
-.I glyph
-is omitted,
-the soft hyphen character is set to the default,
+If the argument is omitted,
+the soft hyphen glyph is set to the default,
 .BR \[rs][hy] .
 .
-The soft hyphen character is the glyph that is inserted when a word is
-automatically hyphenated at a line break.
-.
-If the soft hyphen character does not exist in the font of the character
-immediately preceding a potential break point,
+If the selected glyph does not exist in the font in use at a potential
+hyphenation point,
 then the line is not broken at that point.
 .
-Neither definitions
+Neither character definitions
 (specified with the
 .B .char
 request)
@@ -2823,7 +2804,7 @@ nor translations
 (specified with the
 .B .tr
 request)
-are considered when determining the soft hyphen character.
+are considered when assigning the soft hyphen glyph.
 .
 .
 .TP