[groff] 03/03: [docs]: Improve hyphenation discussion.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 83526199d83e66a2af38082b54394cef9f760d74
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Apr 4 20:43:23 2021 +1000

    [docs]: Improve hyphenation discussion.
    
    * 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.
    
      (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 _automatic_
      hyphenation is disabled.
    
    Thanks to Peter Schaffter for the report.
    
    Fixes <https://savannah.gnu.org/bugs/?60332>.
---
 ChangeLog       | 18 ++++++++++++++++++
 doc/groff.texi  | 23 ++++++++++++++---------
 man/groff.7.man | 21 +++++++++++++++++++--
 3 files changed, 51 insertions(+), 11 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 5295c42..4f6d0ef 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,21 @@
+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.
+       (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
+       _automatic_ hyphenation is disabled.
+
+       Thanks to Peter Schaffter for the report.
+
+       Fixes <https://savannah.gnu.org/bugs/?60332>.
+
 2021-03-27  Deri James  <deri@chuzzlewit.myzen.co.uk>
 
        Changes to the ghostscript fontnames (9.53.3).
diff --git a/doc/groff.texi b/doc/groff.texi
index 4269855..687c534 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -7310,11 +7310,11 @@ places without hyphens.
 @cindex hyphenation, disabling (@code{\%})
 To tell GNU @code{troff} how to hyphenate words as they occur in input,
 use the @code{\%} escape, also known as the @dfn{hyphenation character}.
-Preceding a word with this escape prevents it from being automatically
-hyphenated; each instance within a word indicates to GNU @code{troff}
-that the word may be hyphenated at that point.  This mechanism affects
-only that occurrence of the word; to change the hyphenation of a word
-for the remainder of the document, use the @code{hw} request.
+Each instance within a word indicates to GNU @code{troff} that the
+word may be hyphenated at that point, while prefixing a word with this
+escape prevents it from being otherwise hyphenated.  This mechanism
+affects only that occurrence of the word; to change the hyphenation of a
+word for the remainder of the document, use the @code{hw} request.
 
 @cindex @code{\X}, followed by @code{\%}
 @cindex @code{\Y}, followed by @code{\%}
@@ -7339,10 +7339,15 @@ inserted, the remainder of the (input) word is subject 
to hyphenation as
 normal.
 
 You can use @code{\:} and @code{\%} in combination to control breaking
-of a file name or URL.
+of a file name or URL or to permit hyphenation after only certain
+explicit hyphens within a word.
 
 @Example
-@dots{} check \%/var/log/\:\%httpd/\:\%access_log @dots{}
+@c Wrap example at 56 columns.
+The \%Lethbridge-Stewart-\:\%Sackville-Baggins divorce
+was, in retrospect, inevitable once the contents of
+\%/var/log/\:\%httpd/\:\%access_log on the family web
+server came to light, revealing visitors from Hogwarts.
 @endExample
 @endDefesc
 
@@ -7527,8 +7532,8 @@ The hyphenation mode can be found in the read-only 
register @samp{.hy}.
 @endDefreq
 
 @Defreq {nh, }
-Disable hyphenation; i.e., set the hyphenation mode to@tie{}0 (see
-above).  The hyphenation mode of the last call to @code{hy} is not
+Disable automatic hyphenation; i.e., set the hyphenation mode to@tie{}0
+(see above).  The hyphenation mode of the last call to @code{hy} is not
 remembered.
 @endDefreq
 
diff --git a/man/groff.7.man b/man/groff.7.man
index 7c2df5c..7080ce1 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2228,7 +2228,7 @@ No filling or adjusting of output lines.
 .
 .TPx
 .REQ .nh
-Disable hyphenation;
+Disable automatic hyphenation;
 same as
 .RB \[lq] ".hy 0" \[rq].
 .
@@ -4870,7 +4870,24 @@ instead.
 .SH Hyphenation
 .\" ====================================================================
 .
-Several requests influence hyphenation.
+Explicitly hyphenated words such as \[lq]mother-in-law\[rq] are eligible
+for breaking after each of their hyphens when
+.I groff
+fills lines.
+.
+The hyphenation
+.RB character\~ \[rs]%
+and non-printing break
+.RB point\~ \[rs]:
+escapes may be used to control the hyphenation of individual words.
+.
+Otherwise,
+.I groff
+hyphenates words automatically by default.
+.
+.
+.P
+Several requests influence automatic hyphenation.
 .
 Because conventions vary,
 a variety of hyphenation modes are available to the