Re: documentation of hyphenation

[G. Branden Robinson]

Hi Doug!

At 2020-06-13T15:42:00-0400, Doug McIlroy wrote:
> groff(7) doesn't tell what the hyphenation modes are.

It does, but you have to know to scroll down to the "Hyphenation"
section of the page.  I've just now committed a fix for this and several
other issues.

> It directs you to info for the "gory details".
> But info doesn't tell everything either. It omits .hy 0·
> 
> Mode bits 2, 4, and 8 turn off certain hyphenations.
> A literal reading of info would have .hy 0 turn them on.

Yes.  The existing language was mathematically imprecise.  I've heavily
revised the entire "Manipulating Hyphenation" node of the groff Texinfo
manual and updated groff_diff(7) and groff(7) as appropriate.

> Since groff(7) is otherwise so complete, I'd love to see
> it fixed. That can be done succinctly, and more accurately
> than info, as follows
> 
> .hy     same as .hy 1
> .hy 0   turn hyphenation off

The moral equivalent of these are in place now (and excerpted below).

> .hy N   turn hyphenation on, modified by some bits of N:
>         2 don't hyphenate across page boundaries
>         4 don't hyphenate first two letters of a word
>         8 don't hyphenate last two letters of a word

This change I found harder to justify given that groff also supports
hyphenation values of 16 and 32, and what else one needs to keep in mind
about the subject (in groff, in contrast to AT&T troff).

Here's the result.

...
       .hy       Set hyphenation mode to 1 (the default).
       .hy 0     Disable hyphenation; same as .nh.
       .hy mode  Set hyphenation mode to mode; see section “Hyphenation”
                 below.
...

Hyphenation
       Several requests influence hyphenation.  Because conventions vary, a
       variety of hyphenation modes are available to the .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 default is “1” for
       historical reasons, but macro packages often override this default.

       0      disables hyphenation.

       1      enables hyphenation except after the first and before the last
              character of a word.

       2      disables hyphenation of the last word on a page or column.

       4      disables hyphenation before the last two characters of a word.

       8      disables hyphenation after the first two characters of a word.

       16     enables hyphenation before the last character of a word.

       32     enables hyphenation after the first character of a word.

       Note that any restrictions imposed by the hyphenation mode are not
       respected for words whose hyphenations have been explicitly specified
       with the hyphenation character (“\%” by default) or the .hw request.

       The nonzero values above are additive.  For example, value 12 causes
       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.

       Some values cannot be used together because they contradict; for
       instance, values 4 and 16, and values 8 and 32.

       The places within a word that are eligible for hyphenation are
       determined by language‐specific data (.hla, .hpf, and .hpfa) and
       lettercase relationships (.hcode and .hpfcode).  Furthermore,
       hyphenation of a word might be suppressed because too many previous
       lines have been hyphenated (.hlm), the line has not reached a certain
       minimum length (.hym), or the line can be adjusted with up to a certain
       amount of additional inter‐word space instead (.hys).  See
       groff_diff(7) or the groff Texinfo manual for further details.

No, that is certainly not succinct, but I think most users will find it
impossible to keep the semantics of the hyphenation values in the brain
except by brutal rote memorization anyway.  Further, groff has expanded
the set of tunable hyphenation parameters so greatly that it seemed
irresponsible to keep ignoring them in a section devoted to the subject.

Feedback is welcome, of course.

Regards,
Branden

signature.asc
Description: PGP signature