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

[G. Branden Robinson]

Follow-up Comment #1, bug #60665 (project groff):

[comment #0 original submission:]
> 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.

Yes, it was sort of scribbled down in haste while I was trying to get back to
something else (I forget what, but a nearby commit probably holds the
answer).
 
> * 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.

Yes--this is deliberate.  There's nothing in the `distribute_spaces()`
function that is cognizant of "nroff mode".

Inspecting src/roff/troff/env.cpp, we have the following.


2086 static void distribute_space(node *n, int nspaces, hunits desired_space,
2087                              int force_reverse = 0)
2088 {
2089   static int reverse = 0;
2090   if (force_reverse || reverse)
2091     n = node_list_reverse(n);
2092   if (!force_reverse && nspaces > 0 && spread_limit >= 0
2093       && desired_space.to_units() > 0) {
2094     hunits em = curenv->get_size();
2095     double Ems = (double)desired_space.to_units() / nspaces
2096                  / (em.is_zero() ? hresolution : em.to_units());
2097     if (Ems > spread_limit)
2098       output_warning(WARN_BREAK, "spreading %1m per space", Ems);
2099   }
2100   for (node *tem = n; tem; tem = tem->next)
2101     tem->spread_space(&nspaces, &desired_space);
2102   if (force_reverse || reverse)
2103     (void)node_list_reverse(n);
2104   if (!force_reverse)
2105     reverse = !reverse;
2106   assert(desired_space.is_zero() && nspaces == 0);
2107 }


I believe it is either line 2095 or line 2102 that is doing the work here, and
I think one of them is quantizing the amount of space that can be distributed.
 The quantization is very fine for troff devices, and pretty coarse for nroff
ones.

I haven't gone to the trouble of trying to contrive a case where groff runs
out of space to distribute in troff mode, but I suspect based upon the above
that it can.  Maybe not, though.  Maybe troff devices always have a horizontal
resolution greater than one-twelfth of an em, and that is the smallest amount
of distributable inter-word space we can manipulate with the .ss request.

Making a new, fake troff device with a contrived low resolution is
conceivable, although more effort than I feel inclined to spend right now. 
Could be a fun exercise if my plate didn't feel so full...
 
> * 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.)

Yes, I'd like to make things scrutable here.  In practice, I think you're
right--uneven space distribution consequent to adjustment is something that's
only going to be visible in the nroff context.  I want to say that without
lying to people about what's happening, though.

> * 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.)

Ahhhhh.  Many thanks.  Ralph Corderoy's explanation stuck in my head more
strongly than Doug's (maybe because he got to me first).    My copy of
_Software Tools_ was even fortunate enough to make it with me to Australia so
I can double-check this, and possibly provide a literature citation to
something more respectable than a mailing list. :P

> * The second sentence has subject/verb disagreement.

Urp.  Will fix that in the near term.

> 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.

Yeah, this is a bit of a challenge from a pedagogical perspective.

I'll consult _Software Tools_ and gnaw on this.  I do very much want the point
addressed _somewhere_ in our Texinfo manual--since I stubbed my toe on the
"spooky action at a distance" issue, I suspect others have, and will.  To that
end, moving the meat of the issue to the general discussion of adjustment
seems wise, leaving only the arbitrary parity difference between AT&T and
groff for the node presently under discussion.

    _______________________________________________________

Reply to this item at:

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

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