[groff] 05/08: doc/groff.texi: Make style edits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 57f802587f5b7d05b9c14305e67db56d9c061826
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Sep 25 18:25:50 2020 +1000

    doc/groff.texi: Make style edits.
    
    doc/groff.texi (Manipulating Hyphenation):
    * Recast introduction to motivate discussion a bit differently.
    * Make it more clear that words will be broken at explicit hyphens if
      necessary in fill mode; the hyphenation mode and hyphenation character
      can't prevent this.
    * Reduce usage of "note that" cliché per constructive criticism from
      Dave Kemper; the device is ubiquitous in our documentation and I have
      absorbed it, but it can often be a crutch.
    * Try to clarify the caveat about \%'s interaction with \X and \Y.
    * Say "file name" instead of "filename", a computerism.
    * Explain the representation format of the hyphenation mode, which
      underscores what a poor user-experience choice it was.
    * Say "page location trap" instead of "page position trap".  There is a
      bit of slop in our lexicon around "{vertical,page} {position,location}
      trap".
    * Recast language around bad hyphenation example; it was irritating me.
    * Say "character counts" instead of "values" regarding left and right
      minimums for TeX hyphenation patterns; these having _nothing_ to do
      with the "values" (powers of two) just discussed at great length.
    * Describe .hpfcode request as no longer used by groff's own macro
      files, because it isn't.  It appears to have been superseded by
      .hcode.
    
      Should we deprecate .hpfcode?
---
 doc/groff.texi | 103 +++++++++++++++++++++++++++++++--------------------------
 1 file changed, 57 insertions(+), 46 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 480853a..eeec0e9 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -6608,10 +6608,11 @@ Before tackling automatic hyphenation, let us consider 
how it can be
 done manually.
 
 Explicitly hyphenated words 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.
+breaking after each of their hyphens when GNU @code{troff} fills lines.
+Relatively few words in a language offer such obvious break points,
+however, and automatic hyphenation is not perfect, particularly for
+unusual words like domain-specific jargon.  We may wish to explicitly
+instruct GNU @code{troff} how to hyphenate words if the need arises.
 
 @cindex hyphenation exceptions
 @Defreq {hw, word @dots{}}
@@ -6663,20 +6664,21 @@ places without hyphens.
 @cindex hyphenation, disabling (@code{\%})
 To tell GNU @code{troff} how to hyphenate words as they occur in input,
 use the @code{\%} escape, also known as the @dfn{hyphenation character}.
-Preceding a word with this character prevents it from being hyphenated;
-each instance within a word indicates to GNU @code{troff} that the word
-may be hyphenated at that point.  Note that this mechanism only affects
-that occurrence of the word; to change the hyphenation of a word for the
-entire document, use the @code{hw} request.
+Preceding a word with this escape prevents it from being automatically
+hyphenated; each instance within a word indicates to GNU @code{troff}
+that the word may be hyphenated at that point.  This mechanism affects
+only that occurrence of the word; to change the hyphenation of a word
+for the remainder of the document, use the @code{hw} request.
 
 @cindex @code{\X}, followed by @code{\%}
 @cindex @code{\Y}, followed by @code{\%}
 @cindex @code{\%}, following @code{\X} or @code{\Y}
-Note that the escapes @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.  @xref{Postprocessor Access}.
+GNU @code{troff} regards the escapes @code{\X} and @code{\Y} as starting
+a word; that is, the @code{\%} escape in, say,
+@w{@samp{\X'...'\%foobar}} or @w{@samp{\Y'...'\%foobar}} no longer
+prevents hyphenation of @samp{foobar} but inserts a hyphenation point
+just prior to it; most likely this isn't what you want.
+@xref{Postprocessor Access}.
 
 @cindex non-printing break points (@code{\:})
 @cindex breaking without hyphens (@code{\:})
@@ -6686,12 +6688,12 @@ isn't what you want to do.  @xref{Postprocessor Access}.
 @cindex breaking URLs (@code{\:})
 The @code{\:} escape inserts a non-printing break point; that is, the
 word can break there, but the soft hyphen glyph is not written to the
-output if it does.  Note that breaks are word boundaries, so if a break
-is inserted, the remainder of the (input) word is subject to hyphenation
-as normal.
+output if it does.  Breaks are word boundaries, so if a break is
+inserted, the remainder of the (input) word is subject to hyphenation as
+normal.
 
 You can use @code{\:} and @code{\%} in combination to control breaking
-of a filename or URL.
+of a file name or URL.
 
 @Example
 @dots{} check \%/var/log/\:\%httpd/\:\%access_log @dots{}
@@ -6757,7 +6759,15 @@ 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.
+expense of a more intuitive arrangement.  The mechanism for control of
+hyphenation modes is a set of numbers that can be added up to encode the
+behavior sought.@footnote{The mode is a vector of booleans encoded as an
+integer.  To a programmer, this fact is easily deduced from the
+exclusive use of powers of two for the configuration parameters; they
+are computationally easy to ``mask off'' and compare to zero.  To almost
+everyone else, the arrangement seems recondite and unfriendly.}  The
+entries in the table below are termed @dfn{values}, and the sum
+corresponding to the desired flags is the @dfn{mode}.
 
 @table @code
 @item 0
@@ -6775,14 +6785,14 @@ restrictions relative to that basis.
 
 @table @code
 @item 2
-disables hyphenation of the last word on a page.@footnote{Technically,
-this value prevents hyphenation if the next page position trap is closer
-than the next line of text would be.  GNU @code{troff} automatically
-inserts an implicit page position trap at the end of each page to cause
-a page transition.  This value can be used in traps planted by users or
-macro packages to prevent hyphenation of the last word in a column in
+disables hyphenation of the last word on a page.@footnote{This value
+prevents hyphenation if the next page location trap is closer than the
+next text baseline would be.  GNU @code{troff} automatically inserts an
+implicit page position trap at the end of each page to cause a page
+transition.  This value can be used in traps planted by users or macro
+packages to prevent hyphenation of the last word in a column in
 multi-column page layouts or before floating figures or tables.
-@xref{Traps}.}
+@xref{Page Location Traps}.}
 
 @item 4
 disables hyphenation before the last two characters of a word.
@@ -6797,10 +6807,10 @@ enables hyphenation before the last character of a word.
 enables hyphenation after the first character of a word.
 @end table
 
-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.
+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.
 
 The nonzero values in the previous table are additive.  For example,
 value@tie{}12 causes GNU @code{troff} to hyphenate neither the last two
@@ -6820,7 +6830,7 @@ 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, you can supply the following input to @samp{echo $(nroff)}.
 
 @Example
 .ll 1
@@ -6829,7 +6839,7 @@ splitting
 @endExample
 
 @noindent
-yields
+You will get
 
 @Example
 s- plit- t- in- g
@@ -6843,9 +6853,9 @@ and three characters at the end; this means that 
value@tie{}4 of
 restriction, but values@tie{}16 and@tie{}32 should be avoided, as should
 mode@tie{}1 (the default!).  Modes@tie{}4 and@tie{}6 are typical.
 
-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
+A table of left and right minimum character counts 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.
 
@@ -6874,8 +6884,8 @@ The hyphenation mode can be found in the read-only number 
register
 
 @Defreq {nh, }
 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.
+above).  The hyphenation mode of the last call to @code{hy} is not
+remembered.
 @endDefreq
 
 @DefreqList {hpf, pattern-file}
@@ -6929,15 +6939,16 @@ file is treated as a list of hyphenation patterns 
(except that the
 The @code{hpfa} request appends a file of patterns to the current list.
 
 The @code{hpfcode} request defines mapping values for character codes in
-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.  Character codes that would otherwise be
-invalid in GNU @code{troff} can be used.  By default, every code maps to
-itself except those for letters `A' to `Z', which map to those for `a'
-to `z'.
+pattern files.  It is an older mechanism no longer used by GNU
+@code{troff}'s own macro files; for its successor, see @code{hcode}
+below.  @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.
+Character codes that would otherwise be invalid in GNU @code{troff} can
+be used.  By default, every code maps to itself except those for letters
+`A' to `Z', which map to those for `a' to `z'.
 
 @pindex troffrc
 @pindex troffrc-end