Hello, Werner.
Here is what I came up with. Feel free to edit to
your own taste or reject :)
Anton
--- groff.texinfo 2011-08-21 23:08:07.187500000 +0400
+++ groff.texinfo.new 2011-08-27 01:04:15.546875000 +0400
@@ -6882,7 +6882,11 @@
@cindex manipulating hyphenation
@cindex hyphenation, manipulating
-Here a description of requests which influence hyphenation.
+To compute the hyphenation points for a word, @code{groff} converts it
+into a sequence of hyphenation codes (see @code{hcode} request) which is
+then matched against hyphenation patterns (see @code{hpf} request).
+Following is a detailed description of the requests that control
+hyphenation.
@DefreqList {hy, [@Var{mode}]}
@DefregListEnd {.hy}
@@ -7029,7 +7033,7 @@
the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is
searched for if the @option{-m@var{name}} option is specified.
-It should have the same format as (simple) @TeX{} patterns files. More
+It should have the same format as (simple) @TeX{} pattern files. More
specifically, the following scanning rules are implemented.
@itemize @bullet
@@ -7055,8 +7059,8 @@
@code{@{} and @code{@}} are not allowed in patterns.
@item
-Similarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation
-exceptions.
+Similarly, @code{\hyphenation@{@dots{}@}} specifies a list of
+hyphenation exceptions.
@item
@code{\endinput} is recognized also.
@@ -7103,23 +7107,38 @@
@Defreq {hcode, c1 code1 [c2 code2 @dots{}]}
@cindex hyphenation code (@code{hcode})
@cindex code, hyphenation (@code{hcode})
-Set the hyphenation code of character @var{c1} to @var{code1}, that of
-@var{c2} to @var{code2}, etc. A hyphenation code must be a single input
-character (not a special character) other than a digit or a space.
-
-To make hyphenation work, hyphenation codes must be set up. At
-start-up, groff only assigns hyphenation codes to the letters
-@samp{a}-@samp{z} (mapped to themselves) and to the letters
-@samp{A}-@samp{Z} (mapped to @samp{a}-@samp{z}); all other hyphenation
-codes are set to zero. Normally, hyphenation patterns contain only
-lowercase letters which should be applied regardless of case. In
-other words, the words `FOO' and `Foo' should be hyphenated exactly the
-same way as the word `foo' is hyphenated, and this is what @code{hcode}
-is good for. Words which contain other letters won't be hyphenated
-properly if the corresponding hyphenation patterns actually do contain
-them. For example, the following @code{hcode} requests are necessary to
-assign hyphenation codes to the letters @samp{ÄäÖöÜüß} (this is needed
-for German):
+Set the hyphenation code of glyph name @var{c1} to @var{code1}, that of
+@var{c2} to @var{code2}, etc. A hyphenation code is a single input
+character (not a special character) other than a digit or a space. This
+request works on the level of glyph names and the existence of glyphs is
+not checked.
+
+Hyphenation codes are used to link @code{groff}'s character entities
+with hyphenation patterns. By default, a hyphenation code corresponds
+with an identical character in the pattern file (see @code{hpf}
+request), but this can be changed (see @code{hpfcode} request).
+
+To make hyphenation work, a hyphenation code must be available for every
+glyph that may be part of a word (i.e. for letters, but not for digits
+or punctuation marks). If no hyphenation code has been assigned to a
+glyph, @code{groff} will check if an input character exists that
+translates (@pxref{Character Translations}) to it, and will use its
+hyphenation code instead. If this too fails, words containing this
+glyph won't be hyphenated correctly even if correct hyphenation patterns
+are loaded.
+
+At start-up, groff only assigns hyphenation codes to letters
+@samp{a}-@samp{z} (mapped to themselves) and @samp{A}-@samp{Z} (mapped
+to @samp{a}-@samp{z}); all other hyphenation codes are set to zero. To
+enable hyphenation of words contaning other letters additional
+hyphenation codes should be defined.
+
+Hyphenation patterns normally contain only lowercase letters and should
+be applied regardless of case. For example, the words `FOO' and `Foo'
+should be hyphenated exactly the same way as the word `foo' is
+hyphenated, and this is what @code{hcode} is good for. For example, the
+following @code{hcode} requests are necessary to assign hyphenation
+codes to letters @samp{ÄäÖöÜüß} (this is needed for German):
@Example
.hcode ä ä Ä ä
@@ -8004,6 +8023,11 @@
not possible to map the space character to any other glyph; requests
like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead.
+Note, that calling @w{@samp{.tr za}} and then undoing it with
+@w{@samp{.tr zz}} has a side effect of assigning the character entity
+@samp{'a'} the hyphenation code @samp{'z'}, which can be restored by
+calling @w{@samp{.hcode a a}} (@pxref{Manipulating Hyphenation}).
+
If justification is active, lines are justified in spite of the `empty'
space character (but there is no minimal distance, i.e.@: the space
character, between words).
