[groff] 03/04: Tidy up hyphenation documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 2dcd2611012bf4072268a2f8e7495ae17ac2c17b
Author: G. Branden Robinson <address@hidden>
Date:   Tue Nov 20 20:52:39 2018 -0500

    Tidy up hyphenation documentation.
    
    * doc/groff.texi:
      + An independent clause after a colon still does not get sentence
        capitalization.
      + Fix subject/verb agreement.
      + Many pairs of hyphenation flags are incompatible; generalize the
        language so the examples are not interpreted as exhaustive.
    
    * tmac/groff_man.7.man:
      + Document default hyphenation flag of 4 rather than 6 when continuous
        rendering is enabled.
      + "Possible values" -> "Permissible values".
      + Add cross reference to HYPHENATION section of groff(7), and...
      + Move general discussion of hyphenation flag meanings to...
    
    * man/groff.7.man: ...here.
      + Create new "HYPHENATION" section to house the discussion.
      + Document the flags in tagged paragraphs.
      + Wordsmith the language for clarity (I hope).
    
    Signed-off-by: G. Branden Robinson <address@hidden>
---
 doc/groff.texi       | 10 +++++-----
 man/groff.7.man      | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 tmac/groff_man.7.man | 21 +++++++--------------
 3 files changed, 63 insertions(+), 19 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 662ede0..5e56536 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -7027,9 +7027,9 @@ Enable hyphenation.  The request has an optional numeric 
argument,
 
 @table @code
 @item 1
-The default argument if @var{mode} is omitted: Hyphenation is enabled,
-and the first and the last character of a word is not hyphenated.  This
-is also the start-up value of @code{gtroff}.
+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}.
 
 @item 2
 Do not hyphenate the last word on a page or column.
@@ -7053,8 +7053,8 @@ the first two characters of a word.  Note that 
address@hidden would do
 exactly the same; in other words, address@hidden need not be added if the
 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
+Some values cannot be used together because they contradict; for
+instance, values 4 address@hidden, and values 8 address@hidden
 
 The number of characters at the beginning of a word after which the
 first hyphenation point should be inserted is determined by the patterns
diff --git a/man/groff.7.man b/man/groff.7.man
index c56a448..577cdf4 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -4344,6 +4344,57 @@ instead.
 .
 .
 .\" ====================================================================
+.SH HYPHENATION
+.\" ====================================================================
+.
+The
+.REQ .hy
+request,
+given an integer argument,
+controls when hyphenation applies.
+.
+The default value is
+.BR 1 ,
+which enables hyphenation almost everywhere (see below).
+.
+Macro packages often override this default.
+.
+.
+.TP
+.B 1
+disables hyphenation only 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.
+.
+.TP
+.B 4
+disables hyphenation only before the last two characters of a word.
+.
+.TP
+.B 8
+disables hyphenation only after the first two characters of a word.
+.
+.TP
+.B 16
+enables hyphenation before the last character of a word.
+.
+.TP
+.B 32
+enables hyphenation after the first character of a word.
+.
+.P
+The values are additive.
+.
+Some values cannot be used together because they contradict;
+for instance,
+4 and\~16;
+8 and\~32.
+.
+.
+.\" ====================================================================
 .SH UNDERLINING
 .\" ====================================================================
 .
diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man
index d7cb3c8..64997b3 100644
--- a/tmac/groff_man.7.man
+++ b/tmac/groff_man.7.man
@@ -2226,22 +2226,15 @@ The default is \-0.5i.
 .BI \-rHY= flags
 Set hyphenation flags.
 .
-Possible values of
+Permissible values of
 .I flags
-are 1\~to not hyphenate the first and last character of a word,
-2\~to not hyphenate the last word on a page,
-4\~to not hyphenate the last two characters of a word,
-8\~to not hyphenate the first two characters of a word,
-16\~to enable hyphenation before the last character of a word,
-and
-32\~to enable hyphenation after the first character of a word.
-.
-These values are additive;
-the default is\~6.
+are documented in section \(lqHYPHENATION\(rq of
+.IR groff (7).
 .
-Values 4 and\~16 can't be used together since they contradict each
-other;
-the same holds for values 8 and\~32.
+The default is\~4 if continuous rendering is enabled
+.RB ( \-rcR=1
+above),
+and\~6 otherwise.
 .
 .
 .TP