[groff] 01/02: Further improve .ss documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 3704a6b25e2886fae1491df08a6d6a25f6d4f7ad
Author: G. Branden Robinson <address@hidden>
AuthorDate: 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.
---
 ChangeLog            | 19 +++++++++++--------
 doc/groff.texi       | 33 ++++++++++++++++++++++-----------
 man/groff.7.man      | 11 ++++-------
 man/groff_diff.7.man |  3 +++
 4 files changed, 40 insertions(+), 26 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 93827d8..6d7cdf8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -3,14 +3,17 @@
        Update documentation of .ss request.
 
        * doc/groff.texi: Rewrite documentation of .ss request and
-       \n[.ss] and \n[.sss] escapes.  Use new terminology, "minimal
-       inter-word spacing" and "additional inter-sentence spacing" for
-       clarity.  Clarify that additional inter-sentence spacing is only
-       used when the output line is not full when the end of a sentence
-       occurs.  Move discussion of differences from AT&T troff to
-       section "Implementation Differences".  Update example to more
-       closely resemble a real-world case, use second argument to .ss
-       request, and eliminate hackish use of .nop request.
+       \n[.ss] and \n[.sss] escapes.  Note that negative values are not
+       permitted in either argument to .ss.  Use new terminology,
+       "minimal inter-word spacing" and "additional inter-sentence
+       spacing" for clarity.  Clarify that additional inter-sentence
+       spacing is only used when the output line is not full when the
+       end of a sentence occurs.  Add index nodes to help readers find
+       discussion of details of spacing between words and sentences.
+       Move discussion of differences from AT&T troff to section
+       "Implementation Differences".  Update example to more closely
+       resemble a real-world case, use second argument to .ss request,
+       and eliminate hackish use of .nop request.
 
        * man/groff_diff.7.man: Recast in parallel with the foregoing.
 
diff --git a/doc/groff.texi b/doc/groff.texi
index 53e116f..c67c374 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -6422,16 +6422,25 @@ This is an uninteresting sentence.
 @cindex sentence space size register (@code{.sss})
 @cindex size of sentence space register (@code{.sss})
 @cindex space between sentences register (@code{.sss})
-Set the minimal size of a space between words.  Its units are twelfths
-of the space width parameter of the current font.  Initially both the
-@var{word-space-size} and @var{sentence-space-size} are@tie{}12.  When
-adjusting, the values specify minimum distances.
-
-If two arguments are given to the @code{ss} request, the second argument
-sets the amount of additional space separating sentences on the same
-output line in fill mode.  If the second argument is omitted,
-@var{sentence-space-size} is set to @var{word-space-size}.  The request
-is ignored if there are no arguments.
+Set the sizes of spaces between words and sentences.  Their units are
+twelfths of the space width parameter of the current font.  Initially
+both the @var{word-space-size} and @var{sentence-space-size}
+are@tie{}12.  Negative values are not permitted.  The request is ignored
+if there are no arguments.
+
+@cindex inter-word spacing, minimal
+@cindex minimal inter-word spacing
+@cindex space, between words
+The first argument, the inter-word space size, is a minimum; if
+adjusted, it may increase.
+
+@cindex inter-sentence spacing, additional
+@cindex additional inter-sentence spacing
+@cindex space, between sentences
+The optional second argument sets the amount of additional space
+separating sentences on the same output line in fill mode.  If the
+second argument is omitted, @var{sentence-space-size} is set to
+@var{word-space-size}.
 
 The read-only number registers @code{.ss} and @code{.sss} hold the
 values of minimal inter-word space and additional inter-sentence space,
@@ -6447,6 +6456,8 @@ input.  If a sentence ends at the end of an input line, 
then both an
 inter-word space and an inter-sentence space are added to the output; if
 two spaces follow the end of a sentence in the middle of an input line,
 then the second space becomes an inter-sentence space in the output.
+Additional inter-sentence space is not adjusted, but the inter-word
+space that always precedes it may be.
 
 If a second argument is never given to the @code{ss} request, GNU
 @code{troff} separates sentences as @acronym{AT&T} @code{troff} does.
@@ -14490,7 +14501,7 @@ bytes and ignores an argument to report only the sum of 
the sizes.
 Unlike @acronym{AT&T} @code{troff}, GNU @code{troff} does not ignore the
 @code{ss} request if the output is a terminal device; instead, the
 values of minimal inter-word and additional inter-sentence spacing are
-rounded down to the nearest multiple of@tie{}12.
+each rounded down to the nearest multiple of@tie{}12.
 
 @cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff}
 @cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff}
diff --git a/man/groff.7.man b/man/groff.7.man
index 69d5699..9bf7bfe 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -4190,16 +4190,13 @@ The last requested point size in points as a decimal 
fraction
 .
 .TPx
 .REG .ss
-The size of minimal inter-word spacing set by the first argument of the
-.request .ss
-request.
+Size of minimal inter-word spacing in twelfths of the space width of the
+current font.
 .
 .TPx
 .REG .sss
-The size of additional inter-sentence spacing set by the second argument
-of the
-.request .ss
-request.
+Size of additional inter-sentence spacing in twelfths of the space width
+of the current font.
 .
 .TPx
 .REG .sty
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index abeeb3d..4f198c1 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -2666,6 +2666,9 @@ if two spaces follow the end of a sentence in the middle 
of an input
 line,
 then the second space becomes an inter-sentence space in the output.
 .
+Additional inter-sentence space is not adjusted,
+but the inter-word space that always precedes it may be.
+.
 .IP
 If a second argument is never given to the
 .B .ss