[groff] 07/08: [docs]: Revise .ss request documentation (again).

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7321d3c85e82d6a413f7e0ce2bd5509569a5801b
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Mar 24 17:20:56 2021 +1100

    [docs]: Revise .ss request documentation (again).
    
    * doc/groff.texi (Manipulating Filling and Adjustment):
    * man/groff_diff.7.man (Language/Extended requests): Fix incorrect claim
      that additional inter-sentence space is applied only in fill mode.
      Drop word "parameter" from description of unit used in .ss request
      arguments; it is a needlessly specific reference to the font file
      format.  Tighten wording.
    
    * man/groff.7.man (Control Characters): Fix incorrect claim that
      end-of-sentence detection is attempted only in fill mode.  Note that
      .ss request also affects inter-word spacing.
    
    * man/groff_diff.7.man (Language/Extended requests):
      - Drop example.
      - Move discussion of AT&T vs. GNU troff difference in .ss handling
        from here...
      (Implementation Differences): ...to here.
    
    Thanks to Dave Kemper for his continued scrutiny!
    
    Fixes errors introduced by me in 2bd31bb3f (2020-02-13), 866bc2033
    (2020-05-08), and 3704a6b25 (2020-05-09).
---
 ChangeLog            | 21 +++++++++++++
 doc/groff.texi       | 31 ++++++++++---------
 man/groff.7.man      | 16 +++++-----
 man/groff_diff.7.man | 85 +++++++++++-----------------------------------------
 4 files changed, 62 insertions(+), 91 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index dc6d53e..c992925 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,24 @@
+2021-03-24  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * doc/groff.texi (Manipulating Filling and Adjustment):
+       * man/groff_diff.7.man (Language/Extended requests): Fix
+       incorrect claim that additional inter-sentence space is applied
+       only in fill mode.  Drop word "parameter" from description of
+       unit used in .ss request arguments; it is a needlessly specific
+       reference to the font file format.  Tighten wording.
+
+       * man/groff.7.man (Control Characters): Fix incorrect claim that
+       end-of-sentence detection is attempted only in fill mode.  Note
+       that .ss request also affects inter-word spacing.
+
+       * man/groff_diff.7.man (Language/Extended requests):
+         - Drop example.
+         - Move discussion of AT&T vs. GNU troff difference in .ss
+           handling from here...
+         (Implementation Differences): ...to here.
+
+       Thanks to Dave Kemper for his continued scrutiny!
+
 2021-03-20  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * doc/groff.texi (ms Cover Page Macros):
diff --git a/doc/groff.texi b/doc/groff.texi
index 722aeaa..7071416 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -7160,10 +7160,10 @@ right-justified is associated with the current 
environment
 Set the sizes of spaces between words and
 sentences.@footnote{@xref{Filling} and @ref{Sentences} for the
 definitions of word and sentence boundaries, respectively.}  Their units
-are twelfths of the space width parameter of the current font.
-Initially both the @var{word-space-size} and
-@var{additional-sentence-space-size} are@tie{}12.  Negative values are
-not permitted.  The request is ignored if there are no arguments.
+are twelfths of the space width of the current font.  Initially both the
+@var{word-space-size} and @var{additional-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
@@ -7175,9 +7175,8 @@ automatically adjusted, it may increase.
 @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{additional-sentence-space-size} is set
-to @var{word-space-size}.
+separating sentences on the same output line.  If omitted, this amount
+is set to @var{word-space-size}.
 
 The read-only registers @code{.ss} and @code{.sss} hold the values of
 minimal inter-word space and additional inter-sentence space,
@@ -7187,15 +7186,15 @@ multiple of@tie{}12 on terminal output devices.
 
 @cindex fill mode, and inter-sentence space
 @cindex mode, fill, and inter-sentence space
-Additional inter-sentence spacing is used only in fill mode, and only if
-the output line is not full when the end of a sentence occurs in the
-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.  Further input spaces after the
-second, if present, are adjusted as normal.
+Additional inter-sentence spacing is used only if the output line is not
+full when the end of a sentence occurs in the 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.  Further input spaces after the second, if
+present, are adjusted as normal.
 
 @cindex discardable horizontal space
 @cindex space, discardable, horizontal
diff --git a/man/groff.7.man b/man/groff.7.man
index 1f5d9b6..ded4c3b 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -693,22 +693,24 @@ Space characters separate arguments in requests, macros, 
and strings.
 .
 In text, they separate words.
 .
-When filling is enabled (the default),
+When filling is enabled
+(the default),
 a line may be broken at a space.
 .
-Further, in fill mode, multiple adjacent space characters cause
+Multiple adjacent space characters cause
 .I groff
-to attempt end-of-sentence detection on the preceding word (and trailing
-punctuation).
+to attempt end-of-sentence detection on the preceding word
+(and trailing punctuation).
 .
-The amount of space between sentences in fill mode is controlled by the
+The amount of space between words and sentences is controlled by the
 .request .ss
 request.
 .
 When adjustment is enabled,
-a space's width may be expanded to justify the line.
+inter-word spaces may be expanded to justify the line.
 .
-To get a space of definite width, use the escape sequences
+To get a space of definite width,
+use the escape sequences
 .squoted_char "\[rs]\ "
 (this is the escape character followed by a space),
 .esc 0 ,
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index f50d3c8..8d548dc 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -3416,81 +3416,18 @@ and the latter enables hyphenation after the first 
character in a word.
 .BI .ss\~ "word-space-size additional-sentence-space-size"
 A second argument to the
 .B .ss
-request determines the additional inter-sentence spacing used in fill
-mode.
+request sets the amount of additional space separating sentences on the
+same output line.
 .
 If omitted,
-this value is the same as the minimal inter-word spacing
-(the first argument).
+this amount is set to
+.IR word-space-size .
 .
-Both are in units of twelfths of the space-width parameter of the
-current font
+The arguments' units are twelfths of the space width of the current font
 (see
 .IR groff_font (@MAN5EXT@))
 and default to \~12.
 .
-Unlike
-.RI AT&T\~ troff ,
-.I groff
-does not ignore the
-.B .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\~12.
-.
-.
-.IP
-Additional inter-sentence spacing is used only in fill mode,
-and only if the output line is not full when the end of a sentence
-occurs in the 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.
-.
-.
-.IP
-A related application of the
-.B .ss
-request is to insert discardable horizontal space;
-i.e.,
-space that is discarded at a line break.
-For example,
-some footnote styles collect the notes into a single paragraph with
-large spaces between each.
-.
-.RS
-.RS \" Extra indent to get us inboard of the indented paragraph.
-.EX
-\&.ie n .ll 50n
-\&.el   .ll 2.75i
-\&.ss 12 48
-1. J. Fict. Ch. Soc. 6 (2020), 3\[rs][en]14.
-2. Better known for other work.
-.EE
-.RE
-.RE
-.
-.
-.IP
-The result has obvious inter-sentence spacing.
-.RS
-.RS \" Extra indent to get us inboard of the indented paragraph.
-.\" This is an output example, so use a real en-dash.
-.EX
-1. J. Fict. Ch. Soc. 6 (2020), 3\[en]14.     2. Better
-known for other work.
-.EE
-.RE
-.RE
-.
 .
 .TP
 .BR .ta\~ [[\c
@@ -4928,6 +4865,18 @@ ignores any arguments and reports the sizes in bytes.
 .
 .
 .P
+Unlike
+.RI AT&T\~ troff ,
+.I groff
+does not ignore the
+.B .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\~12.
+.
+.
+.P
 In
 .IR groff ,
 there is a fundamental difference between unformatted input