[groff] 03/05: Resync documentation of \sNN compatbility change.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit f319e5d77a2d29281cf30909b8fc3a14b6e37871
Author: G. Branden Robinson <address@hidden>
AuthorDate: Thu Apr 16 19:05:30 2020 +1000

    Resync documentation of \sNN compatbility change.
    
    * doc/groff.texi:
    * man/groff_diff.7.man: Syncronize these documents with each other with
      respect to the recent \sNN change.  I hadn't realized until now how
      closely the respective portions of the groff_diff(7) man page and the
      Texinfo manual mirror each other.  Follow the parallelism.
---
 doc/groff.texi       | 20 +++++++++---
 man/groff_diff.7.man | 86 ++++++++++++++++++++++++++++------------------------
 2 files changed, 62 insertions(+), 44 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 46bab26..129d0d0 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -10025,10 +10025,6 @@ and the text begins.  Any of the following forms are 
valid:
 Set the point size to @var{n}@tie{}points.  @var{n}@tie{}must be a
 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
-should be migrated to another @code{\s} form.
-
 @item \s+@var{n}
 @itemx \s-@var{n}
 Increase or decrease the point size by @var{n}@tie{}points.
@@ -14418,6 +14414,22 @@ registers, fonts or environments; @acronym{AT&T} 
@code{troff} does.  The
 @code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
 avoiding use of these escape sequences in names.
 
+@cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff}
+Normally, the syntax form @code{\s}@var{n} accepts only a single
+character (a digit) for @var{n}, consistently with other forms that
+originated in @acronym{AT&T} @code{troff}, like @code{\*}, @code{\$},
+@code{\f}, @code{\g}, @code{\k}, @code{\n}, and @code{\z}.
+
+In compatibility mode only, a non-zero@tie{}@var{n} must be in the range
+4--39.  Legacy documents relying upon this quirk of parsing@footnote{The
+Graphic Systems C/A/T phototypesetter (the original device target for
+@acronym{AT&T} @code{troff}) supported only a few discrete point sizes
+in the range 6--36, so Ossanna contrived a special case in the parser to
+do what the user must have meant.  Kernighan warned of this in the 1992
+revision of CSTR@tie{}#54 (�2.3), and more recently, McIlroy referred to
+it as a ``living fossil''.} should be migrated to another @code{\s}
+form.
+
 @cindex fractional point sizes
 @cindex fractional type sizes
 @cindex point sizes, fractional
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 5e36685..c9b49c0 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -3839,6 +3839,52 @@ The
 escape sequence can be helpful in avoiding these escape sequences in
 names.
 .
+.
+.P
+Normally,
+the syntax form
+.BI \[rs]s n
+accepts only a single character
+(a digit)
+for
+.IR n ,
+consistently with other forms that originated in
+.RI AT&T\~ troff ,
+like
+.BR \[rs]* ,
+.BR \[rs]$ ,
+.BR \[rs]f ,
+.BR \[rs]g ,
+.BR \[rs]k ,
+.BR \[rs]n ,
+and
+.BR \[rs]z .
+.
+.
+.P
+In compatibility mode only,
+a
+.RI non-zero\~ n
+must be in the range 4\[en]39.
+.
+Legacy documents relying upon this quirk of parsing should be migrated
+to another
+.B \[rs]s
+form.
+.
+[Background:
+The Graphic Systems C/A/T phototypesetter
+(the original device target for
+.RI AT&T\~ troff )
+supported only a few discrete point sizes in the range 6\[en]36,
+so Ossanna contrived a special case in the parser to do what the user
+must have meant.
+.
+Kernighan warned of this in the 1992 revision of CSTR\~#54 (\[sc]2.3),
+and more recently,
+McIlroy referred to it as a \[lq]living fossil\[rq].]
+.
+.
 .P
 Fractional point sizes cause one noteworthy incompatibility.
 .
@@ -3857,46 +3903,6 @@ request ignores scale indicators and so
 sets the point size to 10\~points, whereas in groff native mode the
 point size is set to 10\~scaled points.
 .
-.P
-The escape
-.BI \[rs]s n
-sets the point size to
-.I n
-scaled points;
-.I n
-must be exactly one digit and
-is a numeric expression with a default scale indicator
-.RB of\~ z\c
-\&.
-.
-AT&T
-.I troff
-would read an additional digit,
-as will
-.I groff
-in compatibility mode,
-if
-.I n
-is 1, 2, or 3,
-because the Graphic Systems C/A/T phototypesetter
-(its original device target)
-only supported a few discrete point sizes in the range 6\[en]36,
-so Ossanna special-cased the parser to do what the user must have meant.
-.
-Kernighan warned of this in the 1992 revision of CSTR\~#54 (\[sc]2.3),
-and more recently,
-McIlroy referred to it as a \[lq]living fossil\[rq].
-.
-.I groff
-will emit an error message in compatibility mode when this ambiguous
-syntax is encountered.
-.
-Use the portable
-.BI \[rs]s( nn
-form for two-digit point sizes,
-or the new forms of
-.B \[rs]s
-documented above.
 .
 .P
 In