[bug #60665] doc/groff.texi: clarify nroff adjustment algorithm differences

[Dave]

URL:
  <https://savannah.gnu.org/bugs/?60665>

                 Summary: doc/groff.texi: clarify nroff adjustment algorithm
differences
                 Project: GNU troff
            Submitted by: barx
            Submitted on: Mon 24 May 2021 10:02:15 PM CDT
                Category: Core
                Severity: 2 - Minor
              Item Group: Documentation
                  Status: None
                 Privacy: Public
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any
         Planned Release: None

    _______________________________________________________

Details:

The "Implementation Differences" section of the Texinfo manual contains this
text (added about a month ago in commit e1a9b263
<http://git.savannah.gnu.org/cgit/groff.git/commit/?id=e1a9b263>):


When adjusting to both margins, @acronym{AT&T} @code{troff} at first
adjusts spaces starting from the right; GNU @code{troff} begins from
the left.  Both implementations adjusts spaces from opposite ends on
alternating output lines in this adjustment mode to prevent ``rivers''
in the text.


This is a small but valid difference between roffs, so I'm glad it's
documented.  But I think the wording could be stronger in a few ways.

* It appears to be talking about the adjustment mechanism used for terminal
(nroff) output, but nothing in the text says this; in fact, the text
explicitly refers to "troff," giving the opposite impression.
* The phrase "adjusting spaces" is a little misleading in an nroff context, as
it implies that the width of the space is changed.  But nroff adjustment is
done by adding discrete numbers of fixed-width spaces.  (This actually makes
me question my conclusion in the previous point, and wonder if the passage
_is_ talking about troff in some inscrutable way.  But that still doesn't make
sense: in typeset output, every space on an adjusted output line (absent some
user intervention to the contrary) will be given equal width, so there's no
meaningful direction in the result.)
* This scheme may have the result of reducing rivers, but it won't prevent
them, and I'm not sure that's even its primary purpose.  It seems to be more a
matter of balancing the type density of the page, insofar as this can be done
with the limitations of fixed-width fonts.  (Doug McIlroy, who invented the
technique, made comments on the email list a couple years ago
(http://lists.gnu.org/archive/html/groff/2018-06/msg00044.html) that seem to
bear this out.)
* The second sentence has subject/verb disagreement.

The first two points above are most easily addressed by changing "troff" to
"nroff," and "adjust(s) spaces" to "add(s) spaces."  Potentially a sentence
could also be inserted at the top explaining the difference between adjusting
in troff and nroff, but I'm undecided on whether this is helpful, or whether
this is the appropriate place to explain that.  It might be more suited for
the "Adjustment" section of the manual, which presently only talks about
troff-style adjusting.

The third point may be tricky because you don't want to get bogged down in a
whole explanation of "color" in typography, but the manual doesn't seem to
have another section to point to that explain this (as far as I can tell, it
uses the word "color" only in the Roy G Biv sense).  Perhps Doug's term,
"density," gets the point across well enough without further explanation.




    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?60665>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/