[groff] 03/03: Update documentation of .ss request.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 866bc203326528237f08f7debe9061ba8f430e1e
Author: G. Branden Robinson <address@hidden>
AuthorDate: Fri May 8 08:03:30 2020 +1000

    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.
    
    * man/groff_diff.7.man: Recast in parallel with the foregoing.
    
    * man/groff.7.man: Use new terminology and describe \n[.ss] and \n[.sss]
      in meaningful terms, not by reference to arguments to the .ss request
      (which wasn't even accurate, because these registers have default
      values).
    
    Fixes https://savannah.gnu.org/bugs/index.php?54101.
---
 ChangeLog            |  23 ++++++++++
 doc/groff.texi       |  87 ++++++++++++++++++-----------------
 man/groff.7.man      |  28 ++++++------
 man/groff_diff.7.man | 125 +++++++++++++++++++++++++++++++++++++--------------
 4 files changed, 174 insertions(+), 89 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 8998e7f..f0a77bd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,26 @@
+2020-05-08  G. Branden Robinson <address@hidden>
+
+       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.
+
+       * man/groff_diff.7.man: Recast in parallel with the foregoing.
+
+       * man/groff.7.man: Use new terminology and describe \n[.ss] and
+       \n[.sss] in meaningful terms, not by reference to arguments
+       to the .ss request (which wasn't even accurate, because these
+       registers have default values).
+
+       Fixes https://savannah.gnu.org/bugs/index.php?54101.
+
 2020-05-06  G. Branden Robinson <address@hidden>
 
        preconv: Support Emacs local variable lists at ends of files.
diff --git a/doc/groff.texi b/doc/groff.texi
index 4694b33..53e116f 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -6413,7 +6413,7 @@ This is an uninteresting sentence.
 @endExample
 @endDefreq
 
-@DefreqList {ss, word_space_size [@Var{sentence_space_size}]}
+@DefreqList {ss, word-space-size [@Var{sentence-space-size}]}
 @DefregItemx {.ss}
 @DefregListEndx {.sss}
 @cindex word space size register (@code{.ss})
@@ -6422,66 +6422,63 @@ 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})
-Change the size of a space between words.  It takes its units as one
-twelfth of the space width parameter for the current font.  Initially
-both the @var{word_space_size} and @var{sentence_space_size}
-are@tie{}12.  In fill mode, the values specify the minimum distance.
+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.
 
-@cindex fill mode
-@cindex mode, fill
 If two arguments are given to the @code{ss} request, the second argument
-sets the sentence space size.  If the second argument is not given,
-sentence space size is set to @var{word_space_size}.  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.  If a
-second argument is never given to the @code{ss} request, the behaviour
-of Unix @code{troff} is the same as that exhibited by GNU @code{troff}.
-In GNU @code{troff}, as in Unix @code{troff}, a sentence should always
-be followed by either a newline or two spaces.
+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.
 
 The read-only number registers @code{.ss} and @code{.sss} hold the
-values of the parameters set by the first and second arguments of the
-@code{ss} request.
-
-The word space and sentence space values are associated with the current
-environment (@pxref{Environments}).
+values of minimal inter-word space and additional inter-sentence space,
+respectively.  These parameters are associated with the current
+environment (@pxref{Environments}), and rounded down to the nearest
+multiple of@tie{}12 on terminal output devices.
 
-Contrary to @acronym{AT&T} @code{troff}, this request is @emph{not}
-ignored if a TTY output device is used; the given values are then
-rounded down to a multiple of@tie{}12 (@pxref{Implementation
-Differences}).
-
-The request is ignored if there is no parameter.
+@cindex fill mode
+@cindex mode, fill
+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.
+
+If a second argument is never given to the @code{ss} request, GNU
+@code{troff} separates sentences as @acronym{AT&T} @code{troff} does.
+In GNU @code{troff}, as in @acronym{AT&T} @code{troff}, a sentence
+should always be followed by either a newline or two spaces.
 
 @cindex discardable horizontal space
 @cindex space, discardable, horizontal
 @cindex horizontal discardable space
-Another useful application of the @code{ss} request is to insert
-discardable horizontal space, i.e., space that is discarded at a line
-break.  For example, paragraph-style footnotes could be separated this
-way:
+A related application of the @code{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.
 
 @Example
-.ll 4.5i
-1.\ This is the first footnote.\c
-.ss 48
-.nop
-.ss 12
-2.\ This is the second footnote.
+.ie n .ll 50n
+.el   .ll 2.75i
+.ss 12 48
+1. J. Fict. Ch. Soc. 6 (2020), 3\[en]14.
+2. Better known for other work.
 @endExample
 
 @noindent
-The result:
+The result has obvious inter-sentence spacing.
 
 @Example
-1. This is the first footnote.        2. This
-is the second footnote.
+1. J. Fict. Ch. Soc. 6 (2020), 3-14.     2. Better
+known for other work.
 @endExample
 
 @noindent
-Note that the @code{\h} escape produces unbreakable space.
+If @emph{undiscardable} space is required, use the @code{\h} escape.
 @endDefreq
 
 @DefreqList {ce, [@Var{nnn}]}
@@ -14489,6 +14486,12 @@ The @code{pm} request differs from @acronym{AT&T} 
@code{troff}:
 GNU @code{troff} reports the sizes of macros, strings, and diversions in
 bytes and ignores an argument to report only the sum of the sizes.
 
+@cindex @code{ss} request, incompatibilities with @acronym{AT&T} @code{troff}
+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.
+
 @cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff}
 @cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff}
 @cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff}
diff --git a/man/groff.7.man b/man/groff.7.man
index d7edc8b..69d5699 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2439,18 +2439,19 @@ is
 .scalednumber "3 m" .
 .
 .TPx
-.REQ .ss "N"
-Set space glyph size to
-.IR N /12
-of the space width in the current font.
+.REQ .ss N
+Set minimal inter-word spacing to
+.IR N \~12ths
+of the space width of the current font.
 .
 .TPx
 .REQ .ss "N M"
-Set space glyph size to
-.IR N /12
-and sentence space size set to
-.IR M /12
-of the space width in the current font.
+As
+.B .ss\~\c
+.IR N ,
+and set additional inter-sentence spacing to
+.IR M \~12ths
+of the space width of the current font.
 .
 .TPx
 .REQ .stringdown stringvar
@@ -4189,14 +4190,15 @@ The last requested point size in points as a decimal 
fraction
 .
 .TPx
 .REG .ss
-The value of the parameters set by the first argument of the
-.request ss
+The size of minimal inter-word spacing set by the first argument of the
+.request .ss
 request.
 .
 .TPx
 .REG .sss
-The value of the parameters set by the second argument of the
-.request ss
+The size of additional inter-sentence spacing set by the second argument
+of the
+.request .ss
 request.
 .
 .TPx
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 692fb72..abeeb3d 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -2628,38 +2628,91 @@ hyphenation before the last character, the latter 
enables hyphenation
 after the first character.
 .
 .TP
-.BI .ss\  m\ n
-When two arguments are given to the
-.B ss
-request, the second argument gives the
-.IR "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
-.B ss
-request.
+.BI .ss\~ "word-space-size sentence-space-size"
+A second argument to the
+.B .ss
+request determines the additional inter-sentence spacing used in fill
+mode.
+.
+If omitted,
+this value is the same as the minimal inter-word spacing
+(the first argument).
+.
+Both are in units of twelfths of the space-width parameter of the
+current font
+(see
+.IR groff_font (@MAN5EXT@))
+and default to \~12.
+.
+Unlike AT&T
+.IR 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.
+.
+.IP
+If a second argument is never given to the
+.B .ss
+request,
+.I groff
+separates sentences as
+.RI AT&T\~ troff
+does.
 .
-In GNU troff, as in Unix troff, you should always follow a sentence
-with either a newline or two spaces.
+In
+.IR groff ,
+as in
+.RI AT&T\~ troff ,
+you should always follow a sentence with either a newline or two spaces.
+.
+.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.
+.EX
+1. J. Fict. Ch. Soc. 6 (2020), 3-14.     2. Better
+known for other work.
+.EE
+.RE
+.RE
 .
 .TP
 .BI .ta\  "n1 n2 \*[ellipsis] nn " "T " "r1 r2 \*[ellipsis] rn"
@@ -2961,9 +3014,13 @@ This is a string-valued register.
 .B \[rs]n[.ss]
 .TQ
 .B \[rs]n[.sss]
-These give the values of the parameters set by the first and second
-arguments of the
-.B ss
+The values of minimal inter-word spacing and additional inter-sentence
+spacing,
+respectively,
+in twelfths of the space width of the current font.
+.
+Set by the
+.B .ss
 request.
 .
 .TP