[groff] 05/05: Revise hyphenation documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 493a01c02d412f72f2cbeac9bebef4a9f9971d87
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Jun 28 19:08:09 2020 +1000

    Revise hyphenation documentation.
    
    * doc/groff.texi (Manipulating Hyphenation):
      + Add pargraphs introducing the topic, and begin discussion with
        considerations of manually-specifed hyphenation and within-word
        breaking.
      + Add @dfn for "hyphenation exceptions" and add it to concept index.
      + Note that hyphenation exceptions (.hw arguments) are associated with
        an environment.
      + Add bridging paragraph summarizing the several requests that
        manipulate automatic hyphenation.
      + .hy: Add paragraph trying to explain why the flags are so weird.
      + .hy: Add table entry for "0".
      + .hy: Remind user that .hy values don't affect .hw words.
      + .hy: Scrupulously observe the additive identity law.
      + .hy: Add @dfn for "pattern file" and add it to concept index.
      + .hy: Condense example by using a simple shell trick.
      + .hy: Add "hyphenation mode register" to concept index.
      + .hpf, .hpfa, .hys: Use phrase-style metasyntactic variables instead
         of C-style.
      + .hpf, .hpfa: Note that troffrc and troffrc-end are also potential
         places where the default hyphenation language can be set.  (In
         fact, the former is where it actually _has_ been set since 1993.)
      + .hpfa: Note that the request will fail if there is no hyphenation
        language.
      + .hpfcode: Clarify description of recognized '^^' patterns.
      + .hcode: Identify the initially assigned set of hyphenation codes as
        applying to the Unicode basic Latin alphabet.
      + .hcode: Characterize hyphenation codes of characters not
        automatically initialized as "undefined" rather than "zero".
      + .hla: Identify what the language "us" means since it's not an ISO
        639-1 code.
      + .hla: Note that the hyphenation language is associated with an
        environment.
      + Add "hyphenation consecutive line limit register", "hyphenation
        consecutive line count register", and "hyphenation space adjustment
        threshold" to concept index.
      + .hys: Use the last of the foregoing consistently; it's a mouthful,
        but communicates more than the vague "hyphenation space".
      + End sentences with "and so on" instead of "etc.".
      + Bracket node with @codequoteundirected and @codequotebacktick.
      + Use @dots{} instead of literal "..." in code example.
      + Replace convoluted Texinfo logic (apparently to work around an old
        makeinfo bug) with "@DefescListEndx {\:, , , }"; this also
        unconfuses syntax highlighting in Vim.
      + Say "GNU troff" instead of "gtroff".
      + Say "U.S. English" instead of "US English" or "American English".
      + Use semicolons in favor of comma splices and some parentheticals.
      + Recast some language for clarity.
      + Place adverbs more carefully.
      + Don't include the words "man page" inside a @cite{} to a man page.
      + Add footnote noting that '\%' no longer works as a hyphenation
        character if .hc is used to redefine it.
      + Add footnote illuminating "soft hyphen" term.
    
    * man/groff.7.man (Requests/Request short reference):
      + Parallelize descriptions of .hc, .hcode, .hla, .hlm, .hpf, .hpfa,
        .hpfcode, .hw, .hy, .hym, .hys, .nh, and .shc with first sentences
        of corresponding entries in groff.texi.
      + As part of the above:
        - Fix error in description of .hc; it changes the hyphenation
          character rather than supplying an additional one.
        - Summarize .hw more informatively.
      + Tidy up font escapes in arguments to page-local .REQ macro calls.
      + Remove unnecessary quotation marks from page-local .REQ macro calls.
      + Remove the word "current" from hyphenation-related request
        documentation.  A reader of this quick-reference document is
        expected to remember that most hyphenation parameters are tracked on
        a per-environment basis.
      + Mark up arguments to .hpfcode request correctly.
      + Use ellipsis in .hw request argument list.
      + Document ".hy 0" as an independent item since its semantics are
        unusual (it doesn't work like other modal requests like .ps or .ad)
      + Add forward reference to "Hyphenation" section in .hy request.
      + Identify synonymy of ".hy 0" and ".nh" in both places.
    
      (Escape Sequences/Single-character escapes [a misnomer!]): Drop
      "optional" from description of "\%".  The hyphenation character
      defined as such in groff documentation denotes an inherently optional
      hyphenation point.
    
      (Registers/Read-only registers): Update descriptions of .hla, .hlc,
      .hlm, .hy, .hym, and .hys registers to (1) note that they're coupled
      to environments; and (2) remove the "as set by the $FOO request"
      language--all have defaults either within the language or set by groff
      startup files like troffrc.  Moreover, the name of the corresponding
      request (applicable in every case except .hlc) is not difficult to
      infer.
    
      (Hyphenation): Parallelize with new and updated material from
      groff.texi.  Add cross-references to groff_diff(7) and the groff
      Texinfo manual.
    
    * man/groff_diff.7.man:
      (Language/Escape sequences): Tighten and increase precision of \:
      description.
    
      (Language/New requests):
      .hcode, .hpfcode: Place optional argument pairs in roman brackets and
      set ellipsis in roman, not italics (yuck!).
      .hla, .hpf, .hpfa: Remove the word "current" from description; the
      parameter thus controlled is documented as being associated with an
      environment.
      .hpfocde: Use \[ha] for ASCII circumflex, not ^.
      .hym, .hys: Mark argument as optional.
    
      (Implementation Differences): Note differences in hyphenation approach
      and limitations.
    
    * man/groff.7.man:
    * man/groff_diff.7.man:
      + Include leading dots when cross-referencing requests.
      + Reduce use of the "\~\cNEWLINE" antipattern.  This construction can
        be necessary inside an input trap, but not otherwise[1].  It seems
        to arise as a conceptual impediment afflicting page authors who are
        unaware of or phobic to part of the two-font macro namespace.  Some
        of our man pages (chem(1), eqn(1), grohtml(1), gropdf(1), grops(1),
        groff_font(5), groff_out(5), groff_tmac(5), groff(7), groff_diff(7),
        groff_mm(7), and groff_ms(7)) appear to have employed this technique
        extensively as if in ignorance of the existence of the .RB and .RI
        macros.  I plan to clean them up at some point, perhaps after
        crafting an appropriately sed-hold-space-shaped lightning bolt.
    
    [1] It can be also necessary on a line before a page-private macro, but
        we shouldn't be using page-private macros, either.
---
 ChangeLog            |   6 +
 doc/groff.texi       | 459 +++++++++++++++++++++++++--------------------
 man/groff.7.man      | 226 ++++++++++++++++-------
 man/groff_diff.7.man | 512 +++++++++++++++++++++++++++++++++++----------------
 4 files changed, 777 insertions(+), 426 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 6c9241a..b1516a9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2020-06-28  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * man/groff.7.man (Requests/Request short reference): Fix error
+       in description of .hc; it changes the hyphenation character
+       rather than supplying an additional one.
+
 2020-06-12  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * doc/groff.texi (Groff Options): Remove editorial comment about
diff --git a/doc/groff.texi b/doc/groff.texi
index 0d8c8d9..cb803df 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -6578,71 +6578,83 @@ right-justified is associated with the current 
environment
 @cindex manipulating hyphenation
 @cindex hyphenation, manipulating
 
-Here a description of requests that influence hyphenation.
+@codequotebacktick on
+@codequoteundirected on
+GNU @code{troff} hyphenates words automatically by default.  Automatic
+hyphenation of words in natural languages is a subject requiring
+algorithms and data, and susceptible to conventions and preferences.
+Before tackling automatic hyphenation, let us consider how it can be
+done manually.
+
+Explicitly hyphenated phrases such as ``mother-in-law'' are eligible for
+breaking after each of their hyphens.  Relatively few words in a
+language offer such obvious break points, however.  In a short document
+we may wish to disable automatic hyphenation and explicitly instruct GNU
+@code{troff} how words could be hyphenated if the need arises.
 
-@Defreq {hw, word1 word2 @dots{}}
-Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated.  The
-words must be given with hyphens at the hyphenation points.  For
-example:
+@cindex hyphenation exceptions
+@Defreq {hw, word @dots{}}
+Define each @dfn{hyphenation exception} @var{word} with each hyphen `-'
+in the word indicating a hyphenation point.  For example:
 
 @Example
 .hw in-sa-lub-rious
 @endExample
 
 @noindent
-Besides the space character, any character whose hyphenation code value
-is zero can be used to separate the arguments of @code{hw} (see the
-documentation for the @code{hcode} request below for more information).
-In addition, this request can be used more than once.
+Besides the space character, any character whose hyphenation code is
+zero can be used to separate the arguments of @code{hw} (see the
+@code{hcode} request below).  In addition, this request can be used more
+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.
+restrictions given by the @code{hy} request (see below).
 
 Hyphenation exceptions specified with the @code{hw} request are
-associated with the current hyphenation language; it causes an error if
-there is no current hyphenation language.
+associated with the hyphenation language and environment; calling the
+@code{hw} request in the absence of a hyphenation language is an error.
 
-This request is ignored if there is no parameter.
-
-In old versions of @code{troff} there was a limited amount of space to
-store such information; fortunately, with @code{gtroff}, this is no
-longer a restriction.
+The request is ignored if there is no parameter.
 @endDefreq
 
+These are known as hyphenation @emph{exceptions} in the expectation that
+most users will avail themselves of automatic hyphenation; these
+exceptions override any rules that would nomally apply to a word
+matching a hyphenation exception defined with @code{hw}.
+
+Situations also arise when only a specific occurrence of a word needs
+its hyphenation altered (or suppressed altogether), or when something
+that is not a word in a natural language, like a URL, needs to be broken
+in sensible places without hyphens.
+
 @DefescList {\\%, , , }
-@deffnx Escape @t{\:}
-@ifnotinfo
-@esindex \:
-@end ifnotinfo
-@ifinfo
-@esindex \@r{<colon>}
-@end ifinfo
+@DefescListEndx {\:, , , }
 @cindex hyphenation character (@code{\%})
 @cindex character, hyphenation (@code{\%})
 @cindex disabling hyphenation (@code{\%})
 @cindex hyphenation, disabling (@code{\%})
-To tell @code{gtroff} how to hyphenate words on the fly, use the
+To tell GNU @code{troff} how to hyphenate words on the fly, use the
 @code{\%} escape, also known as the @dfn{hyphenation character}.
 Preceding a word with this character prevents it from being
-hyphenated; putting it inside a word indicates to @code{gtroff} that
+hyphenated; putting it inside a word indicates to GNU @code{troff} that
 the word may be hyphenated at that point.  Note that this mechanism
 only affects that one occurrence of the word; to change the
 hyphenation of a word for the entire document, use the @code{hw}
 request.
 
-The @code{\:} escape inserts a zero-width break point (that is, the word
-breaks but without adding a hyphen).
+The @code{\:} escape inserts a zero-width break point; that is, the word
+can break there, but no hyphen is written to the output if it does.
 
 @Example
-... check the /var/log/\:httpd/\:access_log file ...
+@dots{} check the /var/log/\:httpd/\:access_log file @dots{}
 @endExample
 
 @cindex @code{\X}, followed by @code{\%}
 @cindex @code{\Y}, followed by @code{\%}
 @cindex @code{\%}, following @code{\X} or @code{\Y}
-Note that @code{\X} and @code{\Y} start a word, that is, the @code{\%}
-escape in (say) @w{@samp{\X'...'\%foobar}} and
+Note that @code{\X} and @code{\Y} start a word; that is, the @code{\%}
+escape in (say) @w{@samp{\X'...'\%foobar}} or
 @w{@samp{\Y'...'\%foobar}} no longer prevents hyphenation but inserts a
 hyphenation point at the beginning of @samp{foobar}; most likely this
 isn't what you want to do.
@@ -6650,9 +6662,10 @@ isn't what you want to do.
 
 @Defreq {hc, [@Var{char}]}
 Change the hyphenation character to @var{char}.  This character then
-works the same as the @code{\%} escape, and thus, no longer appears in
-the output.  Without an argument, @code{hc} resets the hyphenation
-character to be @code{\%} (the default) only.
+works as the @code{\%} escape normally does, and thus, no longer appears
+in the output.@footnote{@code{\%} itself stops marking hyphenation
+points but still produces no output glyph.}  Without an argument,
+@code{hc} resets the hyphenation character to @code{\%} (the default).
 
 The hyphenation character is associated with the current environment
 (@pxref{Environments}).
@@ -6665,62 +6678,99 @@ 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{@dfn{Soft
-hyphen character} is a misnomer since it is an output glyph.}  If the
-argument is omitted, the soft hyphen character is set to the default
-glyph @code{\(hy} (this is the start-up value of @code{gtroff} also).
-The soft hyphen character is the glyph that is inserted when a word is
-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, then the line is not broken at that point.  Neither definitions
-(specified with the @code{char} request) nor translations (specified
-with the @code{tr} request) are considered when finding the 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 ouput 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
+definitions (specified with the @code{char} request) nor translations
+(specified with the @code{tr} request) are considered when assigning
+the soft hyphen character.
 @endDefreq
 
+@cindex hyphenation, automatic
+Several requests influence automatic hyphenation.  Because conventions
+vary, a variety of hyphenation modes are available to the @code{hy}
+request; these determine whether automatic hyphenation will apply to a
+word prior to breaking a line at the end of a column or page, 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}).
+
 @DefreqList {hy, [@Var{mode}]}
 @DefregListEndx {.hy}
-Enable hyphenation.  The request has an optional numeric argument,
-@var{mode}, to restrict hyphenation if necessary:
+Set hyphenation mode to @var{mode}.  The optional numeric argument
+@var{mode} sets conditions on hyphenation.
+
+Typesetting practice generally does not avail itself of every
+opportunity for hyphenation, but the details differ by language and site
+mandates.  The hyphenation modes of @acronym{AT&T} @code{troff} were
+implemented with English-language publishing practices of the 1970s in
+mind, not a scrupulous enumeration of conceivable parameters.  GNU
+@code{troff} extends those modes such that finer-grained control is
+possible, retaining compatibility with older implementations at the
+expense of a more intuitive arrangement.
 
 @table @code
+@item 0
+disables hyphenation.
+
 @item 1
-The default argument if @var{mode} is omitted: hyphenation is enabled,
-and the first and the last characters of a word are not hyphenated.
-This is also the start-up value of @code{gtroff}.
+enables hyphenation except after the first and before the last character
+of a word; this is the default if @var{mode} is omitted and also the
+start-up value of GNU @code{troff}.
 
 @item 2
-Do not hyphenate the last word on a page or column.
+disables hyphenation of the last word on a page or column.
 
 @item 4
-Do not hyphenate the last two characters of a word.
+disables hyphenation before the last two characters of a word.
 
 @item 8
-Do not hyphenate the first two characters of a word.
+disables hyphenation after the first two characters of a word.
 
 @item 16
-Allow hyphenation before the last character of a word.
+enables hyphenation before the last character of a word.
 
 @item 32
-Allow hyphenation after the first character of a word.
+enables hyphenation after the first character of a word.
 @end table
 
-The values in the previous table are additive.  For example,
-value@tie{}12 causes @code{gtroff} to neither hyphenate the last two nor
-the first two characters of a word.  Note that value@tie{}13 would do
-exactly the same; in other words, value@tie{}1 need not be added if the
-value is larger than@tie{}1.
+Note that 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 (see below).
+
+The nonzero values in the previous table are additive.  For example,
+value@tie{}12 causes GNU @code{troff} to hyphenate neither the last two
+nor the first two characters of a word.  Note that value@tie{}13 would
+do exactly the same; in other words, value@tie{}1 need not be added if
+the value is larger than@tie{}1.
 
 Some values cannot be used together because they contradict; for
 instance, values 4 and@tie{}16, and values 8 and@tie{}32.
 
-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
+@cindex hyphenation pattern files
+@cindex pattern files, for hyphenation
+The automatic placement of hyphens in words is determined by
+@dfn{pattern files}, which are derived from @TeX{} and available for
+several languages.  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
+a word before the last hyphenation point should be inserted.  For
+example, supplying the following input to @samp{echo $(nroff)}
 
 @Example
 .ll 1
@@ -6728,31 +6778,31 @@ hyphenation point should be inserted.  For example, the 
code
 splitting
 @endExample
 
-returns
+@noindent
+yields
 
 @Example
-s-
-plit-
-t-
-in-
-g
+s- plit- t- in- g
 @endExample
 
-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 value@tie{}4 of @code{hy} is mandatory.
-Value@tie{}8 is possible as an additional restriction, but values@tie{}1
-(the default!), 16, and@tie{}32 should be avoided.
-
-Here is a table of left and right minimum values for hyphenation as needed
-by the patterns distributed with groff; see the @cite{groff_tmac(5) man
-page} (type @command{man groff_tmac} at the command line) for more
-information on groff's language macro files.
+@noindent
+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{}1 (the default!), 16, and@tie{}32 should be
+avoided.
+
+A table of left and right minimum values for hyphenation as needed by
+the patterns distributed with GNU @code{troff} follows; see the
+@cite{groff_tmac(5)} man page (type @command{man groff_tmac} at the
+command line) for more information on GNU @code{troff}'s language macro
+files.
 
 @multitable {German traditional}    {pattern name}    {left min}    {right min}
 @headitem    language           @tab pattern name @tab left min @tab right min
 @item        Czech              @tab cs           @tab 2        @tab 2
-@item        US English         @tab us           @tab 2        @tab 3
+@item        U.S. English       @tab us           @tab 2        @tab 3
 @item        French             @tab fr           @tab 2        @tab 3
 @item        German traditional @tab det          @tab 2        @tab 2
 @item        German reformed    @tab den          @tab 2        @tab 2
@@ -6761,35 +6811,34 @@ information on groff's language macro files.
 
 Hyphenation exceptions within pattern files (i.e., the words within a
 @code{\hyphenation} group) also obey the hyphenation restrictions given
-by @code{hy}.  However, exceptions specified with the @code{hw} do not.
-
-@cindex hyphenation restrictions register (@code{.hy})
-The current hyphenation restrictions can be found in the read-only
-number register @samp{.hy}.
+by @code{hy}.  However, exceptions specified with @code{hw} do not.
 
 The hyphenation mode is associated with the current environment
 (@pxref{Environments}).
+
+@cindex hyphenation mode register (@code{.hy})
+The hyphenation mode can be found in the read-only number register
+@samp{.hy}.
 @endDefreq
 
 @Defreq {nh, }
-Disable hyphenation (i.e., set the hyphenation mode to zero).  Note that
-the hyphenation mode of the last call to @code{hy} is not remembered.
-
-The hyphenation mode is associated with the current environment
-(@pxref{Environments}).
+Disable hyphenation; i.e., set the hyphenation mode to@tie{}0 (see
+above).  Note that the hyphenation mode of the last call to @code{hy} is
+not remembered.
 @endDefreq
 
-@DefreqList {hpf, pattern_file}
-@DefreqItemx {hpfa, pattern_file}
+@DefreqList {hpf, pattern-file}
+@DefreqItemx {hpfa, pattern-file}
 @DefreqListEndx {hpfcode, a b [c d @dots{}]}
 @cindex hyphenation patterns (@code{hpf})
 @cindex patterns for hyphenation (@code{hpf})
-Read in a file of hyphenation patterns.  This file is searched for in
-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.
+Read hyphenation patterns from @var{pattern-file}.  This file is sought
+in the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) if
+the @option{-m@var{name}} option is specified.
 
-It should have the same format as (simple) @TeX{} patterns files.  More
-specifically, the following scanning rules are implemented.
+The @var{pattern-file} should have the same format as (simple) @TeX{}
+pattern files.  More specifically, the following scanning rules are
+implemented.
 
 @itemize @bullet
 @item
@@ -6800,16 +6849,16 @@ preceded by a backslash.
 No support for `digraphs' like @code{\$}.
 
 @item
-@code{^^@var{xx}} (@var{x} is 0--9 or a--f) and @code{^^@var{x}}
-(character code of @var{x} in the range 0--127) are recognized; other use
-of @code{^} causes an error.
+@code{^^@var{xx}} (where each @var{x} is 0--9 or a--f) and
+@code{^^@var{c}} (character @var{c} in the code point range 0--127
+decimal) are recognized; other uses of @code{^} cause an error.
 
 @item
 No macro expansion.
 
 @item
 @code{hpf} checks for the expression @code{\patterns@{@dots{}@}}
-(possibly with whitespace before and after the braces).  Everything
+(possibly with whitespace before or after the braces).  Everything
 between the braces is taken as hyphenation patterns.  Consequently,
 @code{@{} and @code{@}} are not allowed in patterns.
 
@@ -6822,62 +6871,64 @@ exceptions.
 
 @item
 For backwards compatibility, if @code{\patterns} is missing, the whole
-file is treated as a list of hyphenation patterns (only recognizing the
-@code{%} character as the start of a comment).
+file is treated as a list of hyphenation patterns (except that the
+@code{%} character is recognized as the start of a comment).
 @end itemize
 
-If no @code{hpf} request is specified (either in the document or in a
-macro package), @code{gtroff} won't hyphenate at all.
-
 The @code{hpfa} request appends a file of patterns to the current list.
 
 The @code{hpfcode} request defines mapping values for character codes in
-hyphenation patterns.  @code{hpf} or @code{hpfa} then apply the mapping
-(after reading the patterns) before replacing or appending them to the
-current list of patterns.  Its arguments are pairs of character codes --
-integers from 0 to@tie{}255.  The request maps character
+pattern files.  @code{hpf} or @code{hpfa} apply the mapping
+after reading the patterns but before replacing or appending to the
+active list of patterns.  Its arguments are pairs of character
+codes---integers from 0 to@tie{}255.  The request maps character
 code@tie{}@var{a} to code@tie{}@var{b}, code@tie{}@var{c} to
-code@tie{}@var{d}, and so on.  You can use character codes that would
-be invalid otherwise.  By default, everything maps to itself except
-letters `A' to `Z', which map to `a' to `z'.
+code@tie{}@var{d}, and so on.  Character codes that would otherwise be
+invalid in GNU @code{troff} can be used.  By default, every code maps to
+itself except letters `A' to `Z', which map to `a' to `z'.
 
 @pindex troffrc
 @pindex troffrc-end
 @pindex hyphen.us
 @pindex hyphenex.us
-The set of hyphenation patterns is associated with the current 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 American
+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.
 English (in files @file{hyphen.us} and @file{hyphenex.us}).
 
 A second call to @code{hpf} (for the same language) replaces the
 hyphenation patterns with the new ones.
 
-Invoking @code{hpf} causes an error if there is no current hyphenation
-language.
+Invoking @code{hpf} or @code{hpfa} causes an error if there is no
+hyphenation language.
+
+If no @code{hpf} request is specified (either in the document, in a
+@file{troffrc} or @file{troffrc-end} file, or in a macro package), GNU
+@code{troff} won't automatically hyphenate at all.
 @endDefreq
 
 @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.
+@var{c2} to @var{code2}, and so on.  A hyphenation code must be a single
+input character (not a special character) other than a digit or a space.
+The request is ignored if it has no parameters.
 
-To make hyphenation work, hyphenation codes must be set up.  At
-start-up, groff only assigns hyphenation codes to the letters
+For hyphenation to work, hyphenation codes must be set up.  At
+start-up, GNU @code{troff} assigns hyphenation codes only 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 that 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):
+@samp{A}--@samp{Z} (mapped to @samp{a}--@samp{z}); all other characters
+have undefined hyphenation codes.  Normally, hyphenation patterns
+contain only lowercase letters which should be applied regardless of
+case.  In other words, 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):
 
 @Example
 .hcode � �  � �
@@ -6886,33 +6937,34 @@ for German):
 .hcode � �
 @endExample
 
-Without those assignments, groff treats German words like
+Without those assignments, GNU @code{troff} treats German words like
 @w{`Kinderg�rten'} (the plural form of `kindergarten') as two substrings
 @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 groff finds the hyphenation `kin-der'.
-The other two hyphenation points (`kin-der-g�r-ten') are missed.
-
-This request is ignored if it has no parameter.
+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, language}
+@DefreqList {hla, lang}
 @DefregListEndx {.hla}
 @cindex @code{hpf} request, and hyphenation language
 @cindex @code{hw} request, and hyphenation language
 @pindex troffrc
 @pindex troffrc-end
-Set the current hyphenation language to the string @var{language}.
-Hyphenation exceptions specified with the @code{hw} request and
-hyphenation patterns specified with the @code{hpf} and @code{hpfa}
-requests are both associated with the current hyphenation language.  The
-@code{hla} request is usually invoked by the @file{troffrc} or the
-@file{troffrc-end} files; @file{troffrc} sets the default language to
-@samp{us}.
+Set the hyphenation language to @var{lang}.  Hyphenation exceptions
+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).
+
+The hyphenation language is associated with the current environment
+(@pxref{Environments}).
 
 @cindex hyphenation language register (@code{.hla})
-The current hyphenation language is available as a string in the
-read-only number register @samp{.hla}.
+The hyphenation language is available as a string in the read-only
+number register @samp{.hla}.
 
 @Example
 .ds curr_language \n[.hla]
@@ -6921,7 +6973,7 @@ read-only number register @samp{.hla}.
 @endExample
 @endDefreq
 
-@DefreqList {hlm, [@Var{nnn}]}
+@DefreqList {hlm, [@Var{n}]}
 @DefregItemx {.hlm}
 @DefregListEndx {.hlc}
 @cindex explicit hyphen (@code{\%})
@@ -6929,18 +6981,18 @@ read-only number register @samp{.hla}.
 @cindex consecutive hyphenated lines (@code{hlm})
 @cindex lines, consecutive hyphenated (@code{hlm})
 @cindex hyphenated lines, consecutive (@code{hlm})
-Set the maximum number of consecutive hyphenated lines to @var{nnn}.  If
-this number is negative, there is no maximum.  The default value
-is@tie{}@minus{}1 if @var{nnn} is omitted.  This value is associated
-with the current environment (@pxref{Environments}).  Only lines output
-from a given environment count towards the maximum associated with that
-environment.  Hyphens resulting from @code{\%} are counted; explicit
-hyphens are not.
-
-The current setting of @code{hlm} is available in the @code{.hlm}
-read-only number register.  Also the number of immediately preceding
-consecutive hyphenated lines are available in the read-only number
-register @samp{.hlc}.
+Set the maximum number of consecutive hyphenated lines to @var{n}.  If
+@var{n} is negative, there is no maximum.  If omitted, @var{n}
+is@tie{}@minus{}1.  This value is associated with the current
+environment (@pxref{Environments}).  Only lines output from a given
+environment count towards the maximum associated with that environment.
+Hyphens resulting from @code{\%} are counted; explicit hyphens are not.
+
+@cindex hyphenation consecutive line limit register (@code{.hlm})
+@cindex hyphenation consecutive line count register (@code{.hlc})
+The @code{.hlm} read-only number register stores this maximum.  The
+count of immediately preceding consecutive hyphenated lines is available
+in the read-only number register @code{.hlc}.
 @endDefreq
 
 @DefreqList {hym, [@Var{length}]}
@@ -6948,41 +7000,43 @@ register @samp{.hlc}.
 @cindex hyphenation margin (@code{hym})
 @cindex margin for hyphenation (@code{hym})
 @cindex @code{ad} request, and hyphenation margin
-Set the (right) hyphenation margin to @var{length}.  If the current
-adjustment mode is not @samp{b} or @samp{n}, the line is not hyphenated
-if it is shorter than @var{length}.  Without an argument, the
-hyphenation margin is reset to its default value, which is@tie{}0.  The
-default scaling indicator for this request is @samp{m}.  The hyphenation
-margin is associated with the current environment
-(@pxref{Environments}).
+Set the (right) hyphenation margin to @var{length}.  If the adjustment
+mode is not @samp{b} or @samp{n}, the line is not hyphenated if it is
+shorter than @var{length}.  Without an argument, the hyphenation margin
+is reset to its default value, 0.  The default scaling indicator is
+@samp{m}.  The hyphenation margin is associated with the current
+environment (@pxref{Environments}).
 
 A negative argument resets the hyphenation margin to zero, emitting a
 warning of type @samp{range}.
 
 @cindex hyphenation margin register (@code{.hym})
-The current hyphenation margin is available in the @code{.hym} read-only
-number register.
+The hyphenation margin is available in the @code{.hym} read-only number
+register.
 @endDefreq
 
-@DefreqList {hys, [@Var{hyphenation_space}]}
+@DefreqList {hys, [@Var{hyphenation-space}]}
 @DefregListEndx {.hys}
 @cindex hyphenation space (@code{hys})
+@cindex hyphenation space adjustment threshold
 @cindex @code{ad} request, and hyphenation space
-Set the hyphenation space to @var{hyphenation_space}.  If the current
-adjustment mode is @samp{b} or @samp{n}, don't hyphenate the line if it
-can be justified by adding no more than @var{hyphenation_space} extra
-space to each word space.  Without argument, the hyphenation space is
-set to its default value, which is@tie{}0.  The default scaling
-indicator for this request is @samp{m}.  The hyphenation space is
-associated with the current environment (@pxref{Environments}).
-
-A negative argument resets the hyphenation space to zero, emitting a
-warning of type @samp{range}.
+Suppress hyphenation of the line in adjustment modes @samp{b} or
+@samp{n} if it can be justified by adding no more than
+@var{hyphenation-space} extra space to each word space.  Without an
+argument, the hyphenation space adjustment threshole is set to its
+default value, 0.  The default scaling indicator is @samp{m}.  The
+hyphenation space adjustment threshold is associated with the current
+environment (@pxref{Environments}).
 
-@cindex hyphenation space register (@code{.hys})
-The current hyphenation space is available in the @code{.hys} read-only
-number register.
+A negative argument resets the hyphenation space adjustment threshold to
+zero, emitting a warning of type @samp{range}.
+
+@cindex hyphenation space adjustment threshold register (@code{.hys})
+The hyphenation space adjustment threshold is available in the
+@code{.hys} read-only number register.
 @endDefreq
+@codequotebacktick off
+@codequoteundirected off
 
 
 @c =====================================================================
@@ -14344,20 +14398,29 @@ with documents written using old versions of 
@code{troff}.  Some GNU
 extensions to @code{troff} have become supported by other
 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
+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}
+request); GNU @code{troff} has no such restriction.
+
 @cindex long names
 @cindex names, long
 @cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff}
 @cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff}
-Long names may be the most obvious innovation.  @acronym{AT&T}
-@code{troff} interprets @samp{.dsabcd} as defining a string @samp{ab}
-with contents @samp{cd}.  Normally, GNU @code{troff} interprets this as
-a call of a macro named @code{dsabcd}.  @acronym{AT&T} @code{troff} also
-interprets @code{\*[} and @code{\n[} as a reference to a string or
-number register, respectively, called @samp{[}.  In GNU @code{troff},
-however, the @samp{[} is normally interpreted as delimiting a long name.
-In compatibility mode, GNU @code{troff} interprets names in the
-traditional way, which means that they are limited to one or two
-characters.
+Long names may be GNU @code{troff}'s most obvious innovation.
+@acronym{AT&T} @code{troff} interprets @samp{.dsabcd} as defining a
+string @samp{ab} with contents @samp{cd}.  Normally, GNU @code{troff}
+interprets this as a call of a macro named @code{dsabcd}.
+@acronym{AT&T} @code{troff} also interprets @code{\*[} and @code{\n[} as
+a reference to a string or number register, respectively, called
+@samp{[}.  In GNU @code{troff}, however, the @samp{[} is normally
+interpreted as delimiting a long name.  In compatibility mode, GNU
+@code{troff} interprets names in the traditional way, which means that
+they are limited to one or two characters.
 
 @DefreqList {cp, [@Var{n}]}
 @DefreqItemx {do, name}
diff --git a/man/groff.7.man b/man/groff.7.man
index 2a54682..6611620 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1828,15 +1828,17 @@ Set glyph color to
 .
 .TPx
 .REQ .hc
-Remove additional hyphenation indicator character.
+Reset the hyphenation character
+.RB to\~ \[rs]%
+(the default).
 .
 .TPx
-.REQ .hc "c"
-Set up additional hyphenation indicator character\~\c
-.IR c .
+.REQ .hc char
+Change the hyphenation character
+.RI to\~ char .
 .
 .TPx
-.REQ .hcode "c1 code1 \fR[\fPc2 code2\fR]\fP \fR\&.\|.\|.\&\fP"
+.REQ .hcode "c1 code1 \fR[\fPc2 code2\fR] .\|.\|.\fP"
 Set the hyphenation code of character
 .I c1
 to
@@ -1845,56 +1847,93 @@ that of
 .I c2
 to
 .IR code2 ,
-etc.
+and so on.
 .
 .TPx
-.REQ .hla "lang"
-Set the current hyphenation language to
+.REQ .hla lang
+Set the hyphenation language to
 .IR lang .
 .
 .TPx
-.REQ .hlm "n"
+.REQ .hlm n
 Set the maximum number of consecutive hyphenated lines to
 .IR n .
 .
 .TPx
-.REQ .hpf "file"
+.REQ .hpf pattern-file
 Read hyphenation patterns from
-.IR file .
+.IR pattern-file .
 .
 .TPx
-.REQ .hpfa "file"
+.REQ .hpfa pattern-file
 Append hyphenation patterns from
-.IR file .
+.IR pattern-file .
 .
 .TPx
-.REQ .hpfcode "a b c d \fR\&.\|.\|.\&\fP"
-Set input mapping for
-.request .hpf\c
-\&.
+.REQ .hpfcode "a b \fR[\fPc d\fR] .\|.\|.\fP"
+Define mapping values for character codes in pattern files read with the
+.request .hpf
+and
+.request .hpfa
+requests.
 .
 .TPx
-.REQ .hw "words"
-List of
-.I words
-with exceptional hyphenation.
+.REQ .hw "word \fR.\|.\|.\fP"
+Define how each
+.I  word
+is to be hyphenated,
+with each hyphen
+.RB \[lq] \- \[rq]
+indicating a hyphenation point.
 .
 .TPx
-.REQ .hy "N"
-Switch to hyphenation mode
-.IR N .
+.REQ .hy
+Set hyphenation mode to
+.B 1
+(the default).
 .
 .TPx
-.REQ .hym "n"
-Set the hyphenation margin to
-.I n
+.REQ .hy \fB0\fP
+Disable hyphenation;
+same as
+.BR .nh .
+.
+.TPx
+.REQ .hy mode
+Set hyphenation mode to
+.IR mode ;
+see section \[lq]Hyphenation\[rq] below.
+.
+.TPx
+.REQ .hym
+Set the (right) hyphenation margin to
+.B 0
+(the default).
+.
+.TPx
+.REQ .hym length
+Set the (right) hyphenation margin to
+.I length
 (default scaling indicator\~\c
 .scaleindicator m ).
 .
 .TPx
-.REQ .hys "n"
+.REQ .hys
 Set the hyphenation space to
-.IR n .
+.B 0
+(the default).
+.
+.TPx
+.REQ .hys hyphenation-space
+Suppress hyphenation of the line in adjustment modes
+.RB \[lq] b \[rq]
+or
+.RB \[lq] n \[rq]
+if it can be justified by adding no more than
+.I hyphenation-space
+extra space to each word space
+(default scaling indicator\~\c
+.scaleindicator m ).
 .
 .TPx
 .REQ .ie "cond anything"
@@ -2099,7 +2138,9 @@ No filling or adjusting of output lines.
 .
 .TPx
 .REQ .nh
-No hyphenation.
+Disable hyphenation;
+same as
+.RB \[lq] ".hy 0" \[rq].
 .
 .TPx
 .REQ .nm
@@ -2386,9 +2427,9 @@ Reset soft hyphen glyph to
 .esc (hy .
 .
 .TPx
-.REQ .shc "c"
-Set the soft hyphen glyph to\~\c
-.IR c .
+.REQ .shc c
+Set the soft hyphen glyph
+.RI to\~ c .
 .
 .TPx
 .REQ .shift "n"
@@ -2974,7 +3015,7 @@ expands to \[oq]..\[cq].
 .
 .TP
 .ESC %
-Default optional hyphenation character.
+Default hyphenation character.
 .
 .TP
 .ESC !
@@ -4024,38 +4065,29 @@ The current font height as set with
 .
 .TPx
 .REG .hla
-The current hyphenation language as set by the
-.request hla
-request.
+The hyphenation language in the current environment.
 .
 .TPx
 .REG .hlc
-The number of immediately preceding consecutive hyphenated lines.
+The count of immediately preceding consecutive hyphenated lines in the
+current environment.
 .
 .TPx
 .REG .hlm
-The maximum allowed number of consecutive hyphenated lines, as set by
-the
-.request hlm
-request.
+The maximum number of consecutive hyphenated lines allowed in the
+current environment.
 .
 .TPx
 .REG .hy
-The current hyphenation flags (as set by the
-.request hy
-request).
+The hyphenation mode in the current environment.
 .
 .TPx
 .REG .hym
-The current hyphenation margin (as set by the
-.request hym
-request).
+The hyphenation margin in the current environment.
 .
 .TPx
 .REG .hys
-The current hyphenation space (as set by the
-.request hys
-request).
+The hyphenation space adjustment threshold in the current environment.
 .
 .TPx
 .REG .i
@@ -4503,35 +4535,42 @@ instead.
 .SH Hyphenation
 .\" ====================================================================
 .
-The
-.REQ .hy
-request,
-given an integer argument,
-controls when hyphenation applies.
+Several requests influence hyphenation.
 .
-The default value is
-.BR 1 ,
-which enables hyphenation almost everywhere (see below).
+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 column or page,
+and at which positions within that word hyphenation is permissible.
 .
-Macro packages often override this default.
+The default is
+.RB \[lq] 1 \[rq]
+for historical reasons,
+but macro packages often override this default.
 .
 .
 .TP
+.B 0
+disables hyphenation.
+.
+.TP
 .B 1
-disables hyphenation only after the first and before the last
-character of a word.
+enables hyphenation except after the first and before the last character
+of a word.
 .
 .TP
 .B 2
-disables hyphenation only of the last word on a page or column.
+disables hyphenation of the last word on a page or column.
 .
 .TP
 .B 4
-disables hyphenation only before the last two characters of a word.
+disables hyphenation before the last two characters of a word.
 .
 .TP
 .B 8
-disables hyphenation only after the first two characters of a word.
+disables hyphenation after the first two characters of a word.
 .
 .TP
 .B 16
@@ -4542,12 +4581,63 @@ enables hyphenation before the last character of a word.
 enables hyphenation after the first character of a word.
 .
 .P
-The values are additive.
+Note that any restrictions imposed by the hyphenation mode are
+.I not
+respected for words whose hyphenations have been explicitly
+specified with the hyphenation character
+.RB (\[lq] \[rs]% \[rq]
+by default)
+or the
+.B .hw
+request.
 .
+.P
+The nonzero values above are additive.
+.
+For example,
+value\~12 causes
+.I groff
+to hyphenate neither the last two nor the first two characters of a
+word.
+.
+Note that value\~13 would do exactly the same;
+in other words,
+value\~1 need not be added if the value is larger than\~1.
+.
+.P
 Some values cannot be used together because they contradict;
 for instance,
-4 and\~16;
-8 and\~32.
+values 4 and\~16,
+and values 8 and\~32.
+.
+.
+.P
+The places within a word that are eligible for hyphenation are
+determined by language-specific data
+.RB ( .hla ,
+.BR .hpf ,
+and
+.BR .hpfa )
+and lettercase relationships
+.RB ( .hcode
+and
+.BR .hpfcode ).
+.
+Furthermore,
+hyphenation of a word might be suppressed because too many previous
+lines have been hyphenated
+.RB ( .hlm ),
+the line has not reached a certain minimum length
+.RB ( .hym ),
+or the line can be adjusted with up to a certain amount of additional
+inter-word space instead
+.RB ( .hys ).
+.
+See
+.IR groff_diff (@MAN7EXT@)
+or the
+.I groff
+Texinfo manual for further details.
 .
 .
 .\" ====================================================================
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index fa7bec0..d138a5f 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -809,11 +809,12 @@ intervening space.
 .
 .TP
 .B \[rs]:
-This causes the insertion of a zero-width break point.
+Insert a zero-width break point.
 .
-It is equal to
+This resembles
 .B \[rs]%
-within a word but without insertion of a soft hyphen glyph.
+within a word but does not output the soft hyphen glyph prior to the
+break.
 .
 .TP
 .BI \[rs]? anything \[rs]?
@@ -1935,53 +1936,135 @@ If
 is missing,
 switch to the previous glyph color.
 .
+.
 .TP
-.BI .hcode\~ "c1 code1 c2 code2 \*[ellipsis]"
+.BI .hcode\~ "c1 code1"\c
+.RI \~[ "c2 code2" "] \*[ellipsis]"
 Set the hyphenation code of character
 .I c1
 to
-.I code1
-and that of
+.IR code1 ,
+that of
 .I c2
 to
 .IR code2 ,
 and so on.
-A hyphenation code must be a single input character (not a special
-character) other than a digit or a space.
 .
-Initially each lower-case letter \%a\[en]z has a hyphenation code, which
-is itself, and each upper-case letter \%A\[en]Z has a hyphenation code
-which is the lower-case version of itself.
+A hyphenation code must be a single input character
+(not a special character)
+other than a digit or a space.
+.
+The request is ignored if it has no parameters.
+.
+.
+.IP
+For hyphenation to work,
+hyphenation codes must be set up.
+.
+At start-up,
+.I groff
+assigns hyphenation codes only to the letters \[lq]a\[en]z\[rq]
+(mapped to themselves)
+and to the letters \[lq]A\[en]Z\[rq]
+(mapped to \[lq]a\[en]z\[rq]);
+all other characters have undefined hyphenation codes.
+.
+Normally,
+hyphenation patterns contain only lowercase letters which should be
+applied regardless of case.
+.
+In other words,
+they assume that the words \[lq]FOO\[rq] and \[lq]Foo\[rq] should be
+hyphenated exactly as \[lq]foo\[rq] is.
+.
+The
+.B .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
+.B .hcode
+requests are necessary to assign hyphenation codes to the letters
+\[lq]\[:A]\[:a]\[:O]\[:o]\[:U]\[:u]\[ss]\[rq]
+(needed for German):
+.
+.
+.RS
+.IP
+.EX
+\&.hcode \[:a] \[:a]  \[:A] \[:a]
+\&.hcode \[:o] \[:o]  \[:O] \[:o]
+\&.hcode \[:u] \[:u]  \[:U] \[:u]
+\&.hcode \[ss] \[ss]
+.EE
+.RE
+.
+.
+.IP
+Without those assignments,
+.I groff
+treats German words like \[lq]Kinderg\[:a]rten\[rq]
+(the plural form of \[lq]kindergarten\[rq])
+as two substrings \[lq]kinderg\[rq] and \[lq]rten\[rq]) because the
+hyphenation code of the umlaut\~a is zero by default.
+.
+There is a German hyphenation pattern that covers \[lq]kinder\[rq],
+so
+.I groff
+finds the hyphenation \[lq]kin-der\[rq].
+.
+The other two hyphenation points
+(\[lq]kin-der-gär-ten\[rq])
+are missed.
 .
-See also the
-.B hpf
-request.
 .
 .TP
 .BI .hla\~ lang
-Set the current hyphenation language to
+Set the hyphenation language to
 .IR lang .
+.
 Hyphenation exceptions specified with the
-.B hw
-request and hyphenation patterns specified with the
-.B hpf
-request are both associated with the current hyphenation language.
+.B .hw
+request and hyphenation patterns and exceptions specified with the
+.B .hpf
+and
+.B .hpfa
+requests are associated with the hyphenation language.
 .
 The
-.B hla
+.B .hla
 request is usually invoked by the
-.B troffrc
-file to set up a default language.
+.I troffrc
+or
+.I troffrc\-end
+files;
+.I troffrc
+sets the default language to \[lq]us\[rq]
+(U.S. English).
+.
+.
+.IP
+The hyphenation language is associated with the current environment.
+.
 .
 .TP
-.BI .hlm\~ n
-Set the maximum number of consecutive hyphenated lines to\~\c
-.IR n .
+.BR .hlm\~ [\c
+.IR n ]
+Set the maximum number of consecutive hyphenated lines
+.RI to\~ n .
+.
 If
 .I n
-is negative, there is no maximum.
+is negative,
+there is no maximum.
 .
-The default value is\~\-1.
+If omitted,
+.I n
+is\~\-1.
 .
 This value is associated with the current environment.
 .
@@ -1992,176 +2075,252 @@ Hyphens resulting from
 .B \[rs]%
 are counted; explicit hyphens are not.
 .
+.
 .TP
-.BI .hpf\~ file
+.BI .hpf\~ pattern-file
 Read hyphenation patterns from
-.IR file ;
-this is searched for in the same way that
+.IR pattern-file .
+.
+This file sought in the same way as
 .IB name .tmac
+(or
+.BI tmac. name\c
+)
 is searched for when the
 .BI \-m name
 option is specified.
 .
-It should have the same format as (simple) \*[tx] patterns files.
+.IP
+The
+.I pattern-file
+should have the same format as (simple) \*[tx] pattern files.
 .
-More specifically, the following scanning rules are implemented.
+More specifically,
+the following scanning rules are implemented.
 .
 .RS
 .IP \[bu]
-A percent sign starts a comment (up to the end of the line) even if
-preceded by a backslash.
+A percent sign starts a comment
+(up to the end of the line)
+even if preceded by a backslash.
+.
 .
 .IP \[bu]
-No support for \[oq]digraphs\[cq] like
+No support for \[lq]digraphs\[rq] like
 .BR \[rs]$ .
 .
+.
 .IP \[bu]
-.BI ^^ xx
-.RI ( x
-is 0\[en]9 or a\[en]f) and
-.BI ^^ x
-(character code of\~\c
+.RB \[lq] \[ha]\[ha]\c
+.IR xx \[rq]
+(where each
 .I x
-in the range 0\[en]127) are recognized; other use of\~\c
-.B ^
-causes an error.
+is 0\[en]9 or a\[en]f) and
+.BI \[ha]\[ha] c
+.RI (character\~ c
+in the code point range 0\[en]127 decimal)
+are recognized;
+other uses
+.RB of\~ \[ha]
+cause an error.
+.
 .
 .IP \[bu]
 No macro expansion.
 .
+.
 .IP \[bu]
 .B hpf
 checks for the expression
 .BR \[rs]patterns{ \*[ellipsis] }
-(possibly with whitespace before and after the braces).
+(possibly with whitespace before or after the braces).
 .
 Everything between the braces is taken as hyphenation patterns.
 .
 Consequently,
-.BR { \~\c
-and\~\c
-.B }
+.RB \[lq] { \[rq]
+and
+.RB \[lq] } \[rq]
 are not allowed in patterns.
 .
+.
 .IP \[bu]
 Similarly,
 .BR \[rs]hyphenation{ \*[ellipsis] }
 gives a list of hyphenation exceptions.
 .
+.
 .IP \[bu]
 .B \[rs]endinput
 is recognized also.
 .
+.
 .IP \[bu]
-For backwards compatibility, if
+For backwards compatibility,
+if
 .B \[rs]patterns
-is missing, the whole file is treated as a list of hyphenation patterns
-(only recognizing the
-.BR % \~\c
-character as the start of a comment).
+is missing,
+the whole file is treated as a list of hyphenation patterns
+(except that the
+.RB \[lq] % \[rq]
+character is recognized as the start of a comment).
 .RE
 .
+.
 .IP
 Use the
-.B hpfcode
-request to map the encoding used in hyphenation patterns files to
-.BR groff 's
+.B .hpfcode
+request
+(see below)
+to map the encoding used in hyphenation pattern files to
+.IR groff 's
 input encoding.
 .
-By default, everything maps to itself except letters \[oq]A\[cq] to
-\[oq]Z\[cq] which map to \[oq]a\[cq] to \[oq]z\[cq].
 .
 .IP
-The set of hyphenation patterns is associated with the current language
-set by the
-.B hla
+The set of hyphenation patterns is associated with the hyphenation
+language set by the
+.B .hla
 request.
 .
 The
-.B hpf
+.B .hpf
 request is usually invoked by the
-.B troffrc
-file; a second call replaces the old patterns with the new ones.
+.I troffrc
+or
+.I troffrc\-end
+file;
+by default,
+.I troffrc
+loads hyphenation patterns and exceptions for U.S. English from the
+files
+.I hyphen.us
+and
+.IR hyphenex.us ,
+respectively.
+.
+.
+.IP
+A second call to
+.B .hpf
+(for the same language)
+replaces the old patterns with the new ones.
+.
+.
+.IP
+Invoking
+.B .hpf
+causes an error if there is no hyphenation language.
+.
+.
+.IP
+If no
+.B .hpf
+request is specified
+(either in the document,
+in a
+.I troffrc
+or
+.I troffrc\-end
+file,
+or in a macro package),
+.I groff
+won't automatically hyphenate at all.
+.
 .
 .TP
-.BI .hpfa\~ file
-The same as
-.B hpf
-except that the hyphenation patterns from
-.I file
-are appended to the patterns already loaded in the current language.
+.BI .hpfa\~ pattern-file
+As
+.BR .hpf ,
+except that the hyphenation patterns and exceptions from
+.I pattern-file
+are appended to the patterns already applied to the hyphenation language
+of the environment.
+.
 .
 .TP
-.BI .hpfcode\~ "a b c d \*[ellipsis]"
-After reading a hyphenation patterns file with the
-.B hpf
+.BI .hpfcode\~ "a b"\c
+.RI \~[ "c d" "] \*[ellipsis]"
+Define mapping values for character codes in pattern files;
+after reading a pattern file with the
+.B .hpf
 or
-.B hpfa
-request, convert all characters with character code\~\c
-.I a
-in the recently read patterns to character code\~\c
-.IR b ,
-character code\~\c
-.I c
-to\~\c
-.IR d ,
-etc.
+.B .hpfa
+request,
+convert all characters with character
+.RI code\~ a
+in the recently read patterns to character
+.RI code\~ b ,
+.RI code\~ c
+.RI to\~ d ,
+and so on,
+before replacing or appending to the active list of patterns.
+.
+Each argument must be an integer in the range 0 to\~255.
+.
+Character codes that would otherwise be invalid in
+.I groff
+can be used.
 .
-Initially, all character codes map to themselves.
+By default,
+every code maps to itself except letters \[lq]A\[rq] to \[lq]Z\[rq],
+which map to \[lq]a\[rq] to \[lq]z\[rq].
 .
-The arguments of
-.B hpfcode
-must be integers in the range 0 to\~255.
-.
-Note that it is even possible to use character codes which are invalid
-in
-.B groff
-otherwise.
 .
 .TP
-.BI .hym\~ n
-Set the
-.I hyphenation margin
-to\~\c
-.IR n :
-when the current adjustment mode is not\~\c
-.BR b ,
-the line is not hyphenated if the line is no more than
-.I n
-short.
+.BR .hym\~ [\c
+.IR length ]
+Set the (right) hyphenation margin
+.RI to\~ length .
 .
-The default hyphenation margin is\~0.
+If the adjustment mode is not
+.RB \[lq] b \[rq]
+or
+.RB \[lq] n \[rq],
+the line is not hyphenated if it is shorter than
+.IR length .
+.
+Without an argument,
+the default hyphenation margin is reset to its default value,
+0.
+.
+The default scaling indicator
+.RB is\~\[lq] m \[rq].
 .
-The default scaling indicator for this request is\~\c
-.BR m .
 The hyphenation margin is associated with the current environment.
 .
-The current hyphenation margin is available in the
-.B \[rs]n[.hym]
-register.
+.
+.IP
+A negative argument resets the hyphenation margin to zero,
+emitting a warning of type \[lq]range\[rq].
+.
 .
 .TP
-.BI .hys\~ n
-Set the
-.I hyphenation space
-to\~\c
-.IR n :
-When the current adjustment mode is\~\c
-.B b
-don't hyphenate the line if the line can be justified by adding no
-more than
-.I n
+.BR .hys\~ [\c
+.IR hyphenation-space ]
+Suppress hyphenation of the line in adjustment modes
+.RB \[lq] b \[rq]
+or
+.RB \[lq] n \[rq],
+if it can be justified by adding no more than
+.I hyphenation-space
 extra space to each word space.
 .
-The default hyphenation space is\~0.
+Without an argument,
+the hyphenation space adjustment threshold is set to its default value,
+0.
 .
-The default scaling indicator for this request is\~\c
-.BR m .
-The hyphenation space is associated with the current environment.
+The default scaling indicator
+.RB is\~\[lq] m \[rq].
+.
+The hyphenation space adjustment threshold is associated with the
+current environment.
+.
+.
+.IP
+A negative argument resets the hyphenation space adjustment threshold to
+zero, emitting a warning of type \[lq]range\[rq].
 .
-The current hyphenation space is available in the
-.B \[rs]n[.hys]
-register.
 .
 .TP
 .BI .itc\~ n\~macro
@@ -2472,25 +2631,33 @@ is searched after the list of fonts declared with the
 request but before the mounted special fonts.
 .
 .TP
-.BI .shc\~ c
-Set the soft hyphen character to\~\c
-.IR c .
+.BI .shc\~ glyph
+Set the soft hyphen character
+.RI to\~ glyph .
+.
 If
-.I c
-is omitted, the soft hyphen character is set to the default
+.I glyph
+is omitted,
+the soft hyphen character is set to the default,
 .BR \[rs][hy] .
-The soft hyphen character is the glyph which is inserted when
-a word is hyphenated at a line break.
 .
-If the soft hyphen character does not exist in the font of the
-glyph immediately preceding a potential break point, then the line
-is not broken at that point.
+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,
+then the line is not broken at that point.
+.
+Neither definitions
+(specified with the
+.B .char
+request)
+nor translations
+(specified with the
+.B .tr
+request)
+are considered when determining the soft hyphen character.
 .
-Neither definitions (specified with the
-.B char
-request) nor translations (specified with the
-.B tr
-request) are considered when finding the soft hyphen character.
 .
 .TP
 .BI .shift\~ n
@@ -3040,11 +3207,13 @@ request without any arguments, just as for numbered 
environments.
 There is no limit on the number of named environments; they are
 created the first time that they are referenced.
 .
+.
 .TP
 .BI .hy\~ n
-New additive values 16 and\~32 are available; the former enables
-hyphenation before the last character, the latter enables hyphenation
-after the first character.
+New values 16 and\~32 are available;
+the former enables hyphenation before the last character in a word,
+and the latter enables hyphenation after the first character in a word.
+.
 .
 .TP
 .BI .ss\~ "word-space-size sentence-space-size"
@@ -3282,40 +3451,38 @@ troff.
 The current height of the font as set with
 .BR \[rs]H .
 .
+.
 .TP
 .B \[rs]n[.hla]
-The current hyphenation language as set by the
-.B hla
-request.
+The hyphenation language in the current environment.
+.
 .
 .TP
 .B \[rs]n[.hlc]
-The number of immediately preceding consecutive hyphenated lines.
+The count of immediately preceding consecutive hyphenated lines in the
+current environment.
+.
 .
 .TP
 .B \[rs]n[.hlm]
-The maximum allowed number of consecutive hyphenated lines, as set by
-the
-.B hlm
-request.
+The maximum number of consecutive hyphenated lines allowed in the
+current environment.
+.
 .
 .TP
 .B \[rs]n[.hy]
-The current hyphenation flags (as set by the
-.B hy
-request).
+The hyphenation mode in the current environment.
+.
 .
 .TP
 .B \[rs]n[.hym]
-The current hyphenation margin (as set by the
-.B hym
-request).
+The hyphenation margin in the current environment.
+.
 .
 .TP
 .B \[rs]n[.hys]
-The current hyphenation space (as set by the
-.B hys
-request).
+The hyphenation space adjustment threshold in the current environment.
+.
 .
 .TP
 .B \[rs]n[.in]
@@ -4138,7 +4305,32 @@ have become supported by other implementations.
 .
 .
 .P
-Long names may be the most obvious innovation.
+.I groff
+does not always hyphenate words as
+.RI AT&T\~ troff
+does.
+.
+The AT&T implementation uses a set of hard-coded rules specific to U.S.
+English,
+while
+.I groff
+uses language-specific hyphenation pattern files derived from \*[tx].
+.
+Furthermore,
+in old versions of
+.I troff
+there was a limited amount of space to store hyphenation exceptions
+(arguments to the
+.B .hw
+request);
+.I groff
+has no such restriction.
+.
+.
+.P
+Long names may be
+.IR groff 's
+most obvious innovation.
 .
 .RI AT&T\~ troff
 interprets