bugGNU roff - Bugs: bug #60665, groff.texi, groff_diff.7.man:...

 
 

bug #60665: groff.texi, groff_diff.7.man: clarify nroff adjustment algorithm differences

Submitter:  Dave <barx>
Submitted:  Tue 25 May 2021 03:02:15 AM UTC
   
 
Category:  Core Severity:  2 - Minor
Item Group:  Documentation Status:  None
Privacy:  Public Assigned to:  None
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Mon 22 May 2023 12:40:46 AM UTC, comment #5: 

I said in comment #1:

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


This isn't quite right.  In DWB 3.3 and groff, the units of the `ss` request are twelfths of the `spacewidth` parameter of the font, not twelfths of an em.  This is not a minor distinction, since as Dave recently pointed out, the `spacewidth` generally ranges from 1/4th to 1/3rd of an em.

G. Branden Robinson <gbranden>
Group administrator
Mon 31 May 2021 09:48:43 AM UTC, comment #4: 

comment #1:

> There's nothing in the `distribute_spaces()` function that is
> cognizant of "nroff mode".


Bug #60707 now investigates changing this, which as a side effect should simplify the documentation conundrum.

Dave <barx>
Group Member
Wed 26 May 2021 12:14:03 AM UTC, comment #3: 

And I missed earlier that the same text appears in man/groff_diff.7.man as well, so updating Summary line to include this.

Dave <barx>
Group Member
Tue 25 May 2021 11:12:08 PM UTC, comment #2: 

comment #1:

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


That's slightly off in the details (.ss's units are 1/12 of the font's space width, which itself is typically 1/4 em in modern fonts, giving .ss a 1/48 em granularity) but basically sound reasoning (1/48 em still dwarfs the basic unit in PostScript and PDF; I'm admittedly unfamiliar with other output devices, though).

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


Fair enough, but I don't think omitting implementation details and talking only about visible results is a lie; on the contrary, it's the purpose of end-user documentation, whose readers don't generally care how the code works (else they'd be reading that rather than a manual).  This kind of detail seems more appropriate for developer documentation, if such a thing existed, or code comments, if such things existed.

> Urp.  Will fix that in the near term.


I see commit c431cbc0 has done this.

Dave <barx>
Group Member
Tue 25 May 2021 05:04:16 AM UTC, comment #1: 

original submission:

> The "Implementation Differences" section of the Texinfo manual contains this text (added about a month ago in commit 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.

G. Branden Robinson <gbranden>
Group administrator
Tue 25 May 2021 03:02:15 AM UTC, original submission:  

The "Implementation Differences" section of the Texinfo manual contains this text (added about a month ago in commit 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.

Dave <barx>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by barx (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follows 1 latest change.

    Date Changed by Updated Field Previous Value => Replaced by
    2021-05-26 barx Summarydoc/groff.texi: clarify nroff adjustment algorithm differences groff.texi, groff_diff.7.man: clarify nroff adjustment algorithm differences

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code