[groff] 01/01: groff.texi: Improve documentation of `.hy' request.

[Werner LEMBERG]

wl pushed a commit to branch master
in repository groff.

commit d592d320cd43cf4ecee67a7aa80b52691671465d
Author: Werner Lemberg <address@hidden>
Date:   Sun Mar 4 08:34:20 2018 +0100

    groff.texi: Improve documentation of `.hy' request.
---
 doc/groff.texi | 35 ++++++++++++++++++++++++++++-------
 1 file changed, 28 insertions(+), 7 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index cbaf495..3abd114 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -7044,13 +7044,34 @@ value is larger address@hidden
 Using values 4 address@hidden can't be used together since they contradict
 each other; the same holds for values 8 address@hidden
 
-For historical reasons the default value of the @code{hy} request
-doesn't fit the American English hyphenation patterns that are used by
-groff as the default.  These patterns expect that neither the first
-character nor the last two characters are to be hyphenated; this
-corresponds to address@hidden  Consequently, @code{hy}'s default
address@hidden or even setting values 16 address@hidden might lead to
-(additional) incorrect hyphenation points.
+The number of characters at the beginning of a word after which the
+first hyphenation point should be inserted is determined by the patterns
+themselves; it can't be reduced further without introducing additional,
+invalid hyphenation points (unfortunately, this information is not part
+of a pattern file, you have to know it in advance).  The same is true
+for the number of characters at the end of word before the last
+hyphenation point should be inserted.  For example, the code
+
address@hidden
+.ll 1
+.hy 48
address@hidden
+
+returns
+
address@hidden
+s-
+plit-
+t-
+in-
+g
address@hidden
+
+instead of the correct `split-ting'.  US-English patterns as distributed
+with groff need two characters at the beginning and three characters at
+the end; this means that address@hidden of @code{hy} is mandatory.
address@hidden is possible as an additional restriction, but address@hidden
+(the default!), 16, address@hidden should be avoided.
 
 Hyphenation exceptions within pattern files (i.e., the words within a
 @code{\hyphenation} group) also obey the hyphenation restrictions given