Discussion:
[bug #54101] documentation for .ss either incorrect or incomplete
(too old to reply)
Dave
2018-06-13 14:52:43 UTC
Permalink
Follow-up Comment #1, bug #54101 (project groff):

The other possibility is that the documentation is correct, and groff's
noncompliance with it is a bug.

Modern typography does not add additional space between sentences. To emulate
that, documents cannot use the default .ss setting; they must explicitly
invoke this request and pass 0 as its second parameter. Groff should (and
seems to) treat this 0 as fixed rather than stretchable.

In traditional typography, I don't know whether the extra sentence space was
of fixed width, or adjusted proportionately with the word space. But when
using a nonzero SENTENCE_SPACE_SIZE, groff should probably follow historical
practice in this regard.

_______________________________________________________

Reply to this item at:

<http://savannah.gnu.org/bugs/?54101>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
G. Branden Robinson
2018-06-16 17:05:12 UTC
Permalink
Follow-up Comment #2, bug #54101 (project groff):

Hi Dave,

Do you find the following discussion, from groff_diff(7), more helpful?

".ss m n

When two arguments are given to the ss request, the second argument gives the
sentence space size. If the second argument is not given, the sentence space
size is the same as the word space size. Like the word space size, the
sentence space is in units of one twelfth of the spacewidth parameter for the
current font. Initially both the word space size and the sentence space size
are 12. Contrary to UNIX troff, GNU troff handles this request in nroff mode
also; a given value is then rounded down to the nearest multiple of 12. The
sentence space size is used in two circumstances. If the end of a sentence
occurs at the end of a line in fill mode, then both an inter‐word space and
a sentence space are added; if two spaces follow the end of a sentence in the
middle of a line, then the second space is a sentence space. Note that the
behaviour of UNIX troff is exactly that exhibited by GNU troff if a second
argument is never given to the ss request. In GNU troff, as in UNIX troff,
you should always follow a sentence with either a newline or two spaces."

_______________________________________________________

Reply to this item at:

<http://savannah.gnu.org/bugs/?54101>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
Dave
2018-06-16 18:34:28 UTC
Permalink
Follow-up Comment #3, bug #54101 (project groff):

Hi, thanks for the followup.

I'm not sure what you're asking. The discrepancy between what the info file
says and what groff actually does exists no matter what any other piece of
groff documentation has to say. This discrepancy is what this bug report is
documenting.

The groff_diff(7) passage you cite doesn't address stretching of spaces in
fill mode at all, so I'm afraid I'm not following the connection you're trying
to make.

_______________________________________________________

Reply to this item at:

<http://savannah.gnu.org/bugs/?54101>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
G. Branden Robinson
2018-06-16 23:50:27 UTC
Permalink
Update of bug #54101 (project groff):

Item Group: Documentation => Incorrect behaviour
Status: None => Confirmed

_______________________________________________________

Follow-up Comment #4:

Distressingly, I can't get the second argument to .ss to have any effect at
all.

See attachments.

(file #44379, file #44380, file #44381)
_______________________________________________________

Additional Item Attachment:

File name: 54101.trf Size:0 KB
File name: 54101.png Size:3 KB
File name: 54101.ps Size:6 KB


_______________________________________________________

Reply to this item at:

<http://savannah.gnu.org/bugs/?54101>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
Dave
2018-06-18 11:12:36 UTC
Permalink
Follow-up Comment #5, bug #54101 (project groff):

The second .ss argument has an effect: the ps file you attached definitely
shows a difference between its various values. This file also further
illustrates (probably better than my original example) the problem reported in
this bug report: because SENTENCE_SPACE_SIZE spaces are not stretchable, the
massive stretching of the WORD_SPACE_SIZE spaces dwarfs the fixed-width
SENTENCE_SPACE_SIZE spaces to the point that they're nearly imperceptible.
But if you zoom in, you can tell that the words on different lines are not
aligned.

This more strongly makes me think, as I began to ponder in comment #1, that
the proper fix is to alter the software to match the documentation rather than
vice versa. It makes little typographic sense to have extra sentence spacing
when this amount of space cannot be adjusted for filling.

But again, this decision should probably be made according to historical
typesetting practice, and I'm not familiar with the details of how additional
sentence space was historically implemented.

_______________________________________________________

Reply to this item at:

<http://savannah.gnu.org/bugs/?54101>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
G. Branden Robinson
2020-05-07 02:08:50 UTC
Permalink
Follow-up Comment #6, bug #54101 (project groff):

This issue came up again about a year later.

https://lists.gnu.org/archive/html/groff/2019-07/msg00005.html

_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
G. Branden Robinson
2020-05-07 02:09:07 UTC
Permalink
Update of bug #54101 (project groff):

Status: Confirmed => In Progress
Assigned to: None => gbranden


_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
G. Branden Robinson
2020-05-07 02:20:01 UTC
Permalink
Follow-up Comment #7, bug #54101 (project groff):

Dave, I think you're incorrect about inter-sentence spaces being "fixed", not
adjusted. Please try the following with `groff -Tutf8` (or `nroff`, whatever
:P ).

>From what I can tell, not only does the inter-sentence space get adjusted,
it's adjusted _before_ inter-word spaces are.

At least for grotty, where things are blissfully easy to measure.


.pl 1v
.\".ll 70n \" both inter-word and inter-sentence spaces adjusted
.\".ll 65n \" only inter-sentence spaces adjusted
.ll 60n \" neither adjusted
.ss 12 48
.tm
12345678901234567890123456789012345678901234567890123456789012345678901234567890
1.\& J.\& Fict.\& Ch.\& Soc.\& 6 (2020), 3\[en]14.
2.\& Better known for other work.


Play around with the commented `.ll` lines to see the results.

I'm not going to close this as invalid because I think you're absolutely right
that the documentation is inadequate on this point. The issue has come up at
least once a year on the groff mailing lists, which is a high frequency for
our volume of traffic. I'm got a revamp in progress.

_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
G. Branden Robinson
2020-05-07 02:40:38 UTC
Permalink
Follow-up Comment #8, bug #54101 (project groff):


[comment #7 comment #7:]
> Dave, I think you're incorrect about inter-sentence spaces being "fixed",
not adjusted. Please try the following with `groff -Tutf8` (or `nroff`,
whatever :P ).
>
> From what I can tell, not only does the inter-sentence space get adjusted,
it's adjusted _before_ inter-word spaces are.

Wait, no, I'm wrong. You're right. Hmm. I wonder how hard this would be to
fix.

_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
G. Branden Robinson
2020-05-07 22:14:42 UTC
Permalink
Update of bug #54101 (project groff):

Status: In Progress => Fixed
Open/Closed: Open => Closed
Planned Release: None => 1.22.5

_______________________________________________________

Follow-up Comment #9:

Fixed, as in documentation rewritten, in
866bc203326528237f08f7debe9061ba8f430e1e.

I did look into what it would take to get adjustment to be weighted more
strongly for the additional inter-sentence space than for ordinary inter-word
space, and it is not trivially easy, at least not with my current level of
understanding of src/roff/troff.

By the time extra space needs to be distributed, _all_ interword spacing on
the line has been converted to generic "space nodes" which don't know whether
they're between words or between sentences.

A vague picture in my mind began to form of how I might overcome that (add a
flag to the space_node class, or subclass it), but at the same time I realized
I don't actually know if it is typographically _sound_ to distribute extra
space the way I was planning.

I guess I should bring this to the discussion list.

Let me know if the new documentation is (or is not) an improvement.

Thanks for the report!

_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
Dave
2020-05-08 09:21:37 UTC
Permalink
Follow-up Comment #10, bug #54101 (project groff):

[comment #9 comment #9:]
> Fixed, as in documentation rewritten, in
866bc203326528237f08f7debe9061ba8f430e1e.

This commit contains some great improvements to the entire .ss section of the
manual. But it doesn't fix the specific problem cited in this bug report.

The core problem is that when adjusting, groff stretches word spaces and not
sentence spaces, yet the documentation states (or at least strongly implies)
groff may stretch both.

The original problematic sentence (as documented in comment #0) was "In fill
mode, the values specify the minimum distance." The values in question are
the two parameters to .ss, only one of which (in current groff) is actually a
minimum distance; the other is a fixed distance. The cited commit recasts
this sentence as "When adjusting, the values specify minimum distances."
While overall a better wording, it retains the inaccuracy of the original.

_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
G. Branden Robinson
2020-05-08 09:27:42 UTC
Permalink
Follow-up Comment #11, bug #54101 (project groff):


[comment #10 comment #10:]

> The core problem is that when adjusting, groff stretches word spaces and not
sentence spaces, yet the documentation states (or at least strongly implies)
groff may stretch both.
>
> The original problematic sentence (as documented in comment #0) was "In fill
mode, the values specify the minimum distance." The values in question are
the two parameters to .ss, only one of which (in current groff) is actually a
minimum distance; the other is a fixed distance. The cited commit recasts
this sentence as "When adjusting, the values specify minimum distances."
While overall a better wording, it retains the inaccuracy of the original.

Thanks. I'll zero in on this point and take another look. I got pretty
distracted digging into the internals of env.cpp and node.cpp.

_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
G. Branden Robinson
2020-05-08 22:08:31 UTC
Permalink
Update of bug #54101 (project groff):

Status: Fixed => In Progress
Open/Closed: Closed => Open
Planned Release: 1.22.5 => None


_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
G. Branden Robinson
2020-05-08 23:14:22 UTC
Permalink
Follow-up Comment #12, bug #54101 (project groff):

Okay, for the time being I've satisfied myself that you're right.

Here's a sample document that people can play with for their own experiments.


.pl 1v
.ll \V[LL]n
.ss \V[SS1] \V[SS2]
One two.
Three.
.brp
.warn 0
restore\ parity
.brp
.warn
One two. Three.
.brp


So, for instance, here's what I see.


$ for LL in $(seq 16 20); do LL=$LL SS1=12 SS2=12 ./build/test-groff -Tutf8
./EXPERIMENTS/ss-minimal.groff; done
One two. Three.
restore parity
One two. Three.

One two. Three.
restore parity
One two. Three.

One two. Three.
restore parity
One two. Three.

One two. Three.
restore parity
One two. Three.

One two. Three.
restore parity
One two. Three.



Note that in each pair of "One two. Three", groff has detected a sentence
ending in the first, but not the second.

Here's how I interpret it.

In the first pair (LL=15), the line length is precisely enough for the input
line with two spaces between the sentences; no adjust is required. In the
second of the pair, that means a space is left over. groff adjusts from the
left and places additional space at the first word break it sees.

In the second pair, LL=16, both items in the pair require adjustment. The
first gets one space, and the second gets two, the latter of which happens in
the space between sentences, so the output is identical.

The pattern repeats as the line length increases.

This interpretation is also consistent with my understanding of the code.
There is a function called distribute_spaces() in src/roff/troff/env.cpp,
which handles adjustment. By the time processing reaches that point, groff is
working over a list of nodes. There are several types of these, but the
important one here belongs to the class 'space_node'.

If we instrument this function, we see that the additional inter-sentence
space has already been coalesced into the interword space:


diff --git a/src/roff/troff/env.cpp b/src/roff/troff/env.cpp
index c11d2dfc..26324b6c 100644
--- a/src/roff/troff/env.cpp
+++ b/src/roff/troff/env.cpp
@@ -2086,6 +2086,8 @@ static void distribute_space(node *n, int nspaces,
hunits desired_space,
if (Ems > spread_limit)
output_warning(WARN_BREAK, "spreading %1m per space", Ems);
}
+ error("GBR: distributing %1 units of space across %2 nodes",
+ desired_space.to_units(), nspaces);
for (node *tem = n; tem; tem = tem->next)
tem->spread_space(&nspaces, &desired_space);
if (force_reverse || reverse)


Here's the noise this produces.


troff: backtrace: file './EXPERIMENTS/ss-minimal.groff':6
troff: ./EXPERIMENTS/ss-minimal.groff:6: error: GBR: distributing 0 units of
space across 2 nodes
troff: backtrace: file './EXPERIMENTS/ss-minimal.groff':9
troff: ./EXPERIMENTS/ss-minimal.groff:9: error: GBR: distributing 0 units of
space across 0 nodes
troff: backtrace: file './EXPERIMENTS/ss-minimal.groff':12
troff: ./EXPERIMENTS/ss-minimal.groff:12: error: GBR: distributing 24 units of
space across 2 nodes
One two. Three.
restore parity
One two. Three.

troff: backtrace: file './EXPERIMENTS/ss-minimal.groff':6
troff: ./EXPERIMENTS/ss-minimal.groff:6: error: GBR: distributing 24 units of
space across 2 nodes
troff: backtrace: file './EXPERIMENTS/ss-minimal.groff':9
troff: ./EXPERIMENTS/ss-minimal.groff:9: error: GBR: distributing 0 units of
space across 0 nodes
troff: backtrace: file './EXPERIMENTS/ss-minimal.groff':12
troff: ./EXPERIMENTS/ss-minimal.groff:12: error: GBR: distributing 48 units of
space across 2 nodes
One two. Three.
restore parity
One two. Three.
[...and so forth...]


The question I have is, should extra space be distributed in keeping with the
relative proportion of additional intersentence space to interword space?

That's more of a typography question than a code question. One of us can take
it to the list, I reckon.

In the meantime, as you noted, clarifying the documentation to tell the truth
should resolve this ticket. :)

_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
G. Branden Robinson
2020-05-09 01:09:02 UTC
Permalink
Update of bug #54101 (project groff):

Status: In Progress => Fixed
Open/Closed: Open => Closed
Planned Release: None => 1.22.5

_______________________________________________________

Follow-up Comment #13:

Fixed in commit 866bc203326528237f08f7debe9061ba8f430e1e.

This time for sure!

_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
Dave
2020-05-09 01:13:30 UTC
Permalink
Follow-up Comment #14, bug #54101 (project groff):

[comment #12 comment #12:]
> The question I have is, should extra space be distributed in
> keeping with the relative proportion of additional
> intersentence space to interword space?
>
> That's more of a typography question than a code question.
> One of us can take it to the list, I reckon.

Indeed, the answer isn't clear. According to this ranting but well-documented
blog post
<http://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324>,
professional typography stopped using extra sentence spacing between the 1920s
and the 1950s, breaking with two centuries of nearly universal typographic
practice. Ideally, groff would adjust sentence spaces in line with that
historical practice, but finding someone familiar with such details may
require casting the net wider than the groff email list.

This blog post states, "the aesthetics of how to handle the various width
spaces... had complex rules that can be found in many of the manuals cited
above," a vagueness that makes sense given that the question of adjusting is
beyond its scope. But it does quote a passage from the 1906 Chicago Manual of
Style with some Byzantine (and, to my modern eyes, not entirely
comprehensible) rules for adjusting a line, wherein space is added or removed
depending on the shapes of the adjacent characters, among other
considerations. This is probably not only inadvisable in modern groff (it
concerns a typesetting paradigm where other marks of punctuation also got
something other than a standard word space after them), but not even possible,
as I don't think groff has any awareness of letter shapes (else why would user
intervention be required to avoid a collision between an italic f and a roman
end parenthesis?).

But it seems to me that groff's current system is not ideal. Your example
from comment #4 probably illustrates this best, showing that with large
adjustments, spaces between words and those between sentences become nigh
indistinguishable, surely not the desired outcome when the user has asked for
sentence spaces to be two to four times the width of word spaces.

_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
G. Branden Robinson
2020-05-09 01:14:04 UTC
Permalink
Follow-up Comment #15, bug #54101 (project groff):

Naturally I'd goof the commit ID when making a reference to Rocky and
Bullwinkle.


commit 3704a6b25e2886fae1491df08a6d6a25f6d4f7ad
Author: G. Branden Robinson <***@gmail.com>
Date: Sat May 9 09:44:47 2020 +1000

Further improve .ss documentation.

More strongly distinguish the minimality (adjustability) of inter-word
space and fixedness (non-adjustability) of inter-sentence space. This
was the main point of the problem report, Savannah #54101.

* doc/groff.texi:
+ Note that negative values are not permitted in either argument to
.ss. (Right now the prohibition is enforced by assertion failure
and core dump; see Savannah #58337.)
+ Add index nodes to help readers find discussion of details of
spacing between words and sentences.
+ Improve grammar.

* man/groff.7.man: Make descriptions of \n[.ss] and \n[.sss] more
self-contained.

* man/groff_diff.7.man: Sync with applicable change to groff.texi.

Thanks to Dave Kemper for his feedback.


_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
Dave
2020-05-10 13:28:11 UTC
Permalink
Follow-up Comment #16, bug #54101 (project groff):

[comment #15 comment #15:]
> commit 3704a6b25e2886fae1491df08a6d6a25f6d4f7ad

This just about nails it. One slight clarification could be made:

This commit adds the sentence, "The first argument, the inter-word space size,
is a minimum; if adjusted..." The intended reading here is "if [the text is]
adjusted...," but given the context of the preceding clause, a reader could
reasonably interpret this as "if [the first argument is] adjusted..."

Possible fix 1: replace "if adjusted, it may increase" with "groff may use a
wider space in adjusted text," to make it abundantly clear we're talking about
adjustments groff does automatically.

Possible fix 2: remove the sentence altogether, since the concept is explained
a couple paragraphs later, in: "Additional inter-sentence space is not
adjusted, but the inter-word space that always precedes it may be." The only
thing this explanation is missing is an explicit statement that the given
word-space size is a minimum; that is, that adjustment is always done by
expanding space, never contracting it (however much bug #40963 may wish
otherwise). Changing this sentence's "adjusted" to "expanded" or "widened"
should cover this, though.

The issue discussed in comment #14 probably warrants a new bug report.

_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
Dave
2020-05-27 04:52:24 UTC
Permalink
Follow-up Comment #17, bug #54101 (project groff):

[comment #16 comment #16:]
> The issue discussed in comment #14 probably warrants a new bug report.

That new report is bug #58450.

As for the issue raised in comment #16: it appears savannah doesn't allow a
bug's original author to reopen a bug report. With this report closed, it's
no longer showing up on anyone's radar, but I hate to open a new bug report
for such a minor thing. Would someone be willing to reopen this one until
it's addressed?

_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
G. Branden Robinson
2020-05-27 06:46:15 UTC
Permalink
Update of bug #54101 (project groff):

Item Group: Incorrect behaviour => Documentation
Status: Fixed => In Progress
Open/Closed: Closed => Open

_______________________________________________________

Follow-up Comment #18:

Reopening per Dave's request and the remaining issue in comment #16.

_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
G. Branden Robinson
2020-06-01 13:34:33 UTC
Permalink
Update of bug #54101 (project groff):

Status: In Progress => Need Info

_______________________________________________________

Follow-up Comment #19:

Hi Dave,

Let me know if 1b35343a5c7ddc3f972c086aab6a1794f16d9446 does the trick.

_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
Dave
2020-06-01 18:27:12 UTC
Permalink
Follow-up Comment #20, bug #54101 (project groff):

Yes, thank you -- I think we can put this one to bed!

_______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
G. Branden Robinson
2020-06-04 15:21:52 UTC
Permalink
Update of bug #54101 (project groff):

Status: Need Info => Fixed
Open/Closed: Open => Closed

_______________________________________________________

Follow-up Comment #21:

Thanks, Dave. I did back out the parenthetical cross-reference in
bfbc45358ed4b7b41be2dba98a640f1b86661d86, because that was the node the
material was already in.

But "automatically" remains, and I think that was the remaining issue
requiring clarification.

_______________________________________________________

Reply to this item at:

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

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