[groff] 01/03: Correct and clarify point size documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 8483ea959777c9c8d0407f336cbe6ae69e1a0a6c
Author: G. Branden Robinson <address@hidden>
AuthorDate: Wed Apr 8 07:28:04 2020 +1000

    Correct and clarify point size documentation.
    
    The Texinfo manual has long documented the request '.ps 0' as restoring
    the previous point size (just as '\s0' or '.ps' with no argument does),
    but this is incorrect, since groff 1.02 or earlier (June 1991), the
    request has not actually worked this way.  Instead, '.ps 0' sets the
    point size to 1 basic unit (thought output drivers may clamp this to a
    higher value).  This behavior is consistent with Hierloom troff and,
    per Ingo Schwarze, Plan 9 troff.  (It is, however, not consistent with
    neatroff.)
    
    * doc/groff.texi (Changing Type Sizes):
      + Stop claiming that '.ps 0' works like '\s0'.
      + Note that the resulting (computed) point size, not the argument, is
        clamped.
      + Note that it is non-positive, not negative, point sizes that are
        clamped to 1u.
      + Add (forward) cross-reference to section where \n[.ps] is defined
        since it is mentioned here.
      + Move explanation of special handling of zero argument to \s escape
        description.
    
    * man/groff.7.man: Explain .ps N independently of \s.  Note clamping
      behavior.
---
 doc/groff.texi  | 14 +++++++-------
 man/groff.7.man |  6 +++++-
 2 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index be84531..0478baf 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -10020,18 +10020,18 @@ typesetters, as @dfn{leading} (this is pronounced 
`ledding').
 @cindex point sizes, changing (@code{ps}, @code{\s})
 Use the @code{ps} request or the @code{\s} escape to change (increase,
 decrease) the type size (in points).  Specify @var{size} as either an
-absolute point size, or as a relative change from the current size.  The
-size@tie{}0 (for both @code{.ps} and @code{\s}), or no argument (for
-@code{.ps} only), goes back to the previous size.
+absolute point size, or as a relative change from the current size.
+@code{.ps} with no argument restores the previous size.
 
-Default scaling indicator of @code{size} is @samp{z}.  If @code{size} is
-negative, it is set to 1@dmn{u}.
+The default scaling indicator of @code{size} is @samp{z}.  If the
+resulting size is non-positive, it is set to 1@dmn{u}.
 
 @cindex type size registers (@code{.s}, @code{.ps})
 @cindex point size registers (@code{.s}, @code{.ps})
 The read-only number register @code{.s} returns the point size in points
 as a decimal fraction.  This is a string.  To get the point size in
-scaled points, use the @code{.ps} register instead.
+scaled points, use the @code{.ps} register instead (@pxref{Fractional
+Type Sizes}).
 
 @code{.s} is associated with the current environment
 (@pxref{Environments}).
@@ -10052,7 +10052,7 @@ and the text begins.  Any of the following forms are 
valid:
 @table @code
 @item \s@var{n}
 Set the point size to @var{n}@tie{}points.  @var{n}@tie{}must be a
-single digit.
+single digit.  If @var{n}@tie{}is 0, restore the previous size.
 
 In compatibility mode only, a non-zero @var{n}@tie{}must be in the range
 4 to@tie{}39.  Legacy documents relying upon this quirk of parsing
diff --git a/man/groff.7.man b/man/groff.7.man
index 6de8480..2167a3b 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2219,7 +2219,11 @@ Return to previous point size.
 .TPx
 .
 .REQ .ps "\[+-]N"
-Point size; same as
+Set/increase/decrease the point size to/by
+.I N
+scaled points
+(a non-positive resulting point size is set to 1\~u.);
+also see
 .esc[] s \[+-]N .
 .
 .TPx