[groff] 01/03: Support 2-digit \sNN only in compatibility mode.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 0b9aaca060117edfc65af8264fa791ed7e851633
Author: G. Branden Robinson <address@hidden>
AuthorDate: Sat Apr 4 05:14:09 2020 +1100

    Support 2-digit \sNN only in compatibility mode.
    
    * src/roff/troff/input.cpp (read_size): Move special-case interpretation
      of the '\sN' form of point-size escapes when 'N' is 1, 2, or 3 to
      compatibility mode (groff -C) only, and throw error diagnostic with
      suggestion for remedy if encountered.
    
      Traditionally, '\s36A' is interpreted as "set point size to 36, then
      emit 'A'".  However, only values in the range 10-39 are handled
      specially; '\s40A' is interpreted as a four-point "0A".  This is
      unlike anything else in *roff grammar; see \*, \$, \f, \F, \g, \k, \m,
      \M, \n, \V, and \Y.
    
      To anticipate objections: Why not throw only a warning?  Because there
      isn't a warning category for supported but ambiguous syntax (this
      behavior of AT&T troff dates to 1976 but apparently was not documented
      until 1992).  Why not throw the error outside of compatibility mode
      too?  Because outside of compatibility mode we (now) have an
      unambiguous parse.
    
      Background: The Graphic Systems C/A/T phototypesetter (the original
      device target for AT&T troff) only supported a few discrete point
      sizes in the range 6..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 (§2.3), and more recently, McIlroy referred to it
      as a "living fossil".
    
      See: https://lists.gnu.org/archive/html/groff/2020-03/msg00054.html
           https://lists.gnu.org/archive/html/groff/2020-04/msg00002.html
           https://lists.gnu.org/archive/html/groff/2020-04/msg00015.html
      and follow-ups for discussion.
    
    * NEWS: Advise users of behavior change and offer guidance.
    
    * doc/groff.texi:
    * man/groff.7.man: Document the restriction of special handling of
      point-size arguments to '\s' to compatibility mode.
    
    * src/roff/groff/groff.am:
    * src/roff/groff/tests/use_point_size_escape_with_single_digit_arg.sh:
      Add regression test.
---
 ChangeLog                                          | 45 ++++++++++++++++++++++
 NEWS                                               | 30 ++++++++++++++-
 doc/groff.texi                                     |  8 +++-
 man/groff.7.man                                    | 15 +++++---
 src/roff/groff/groff.am                            |  3 +-
 .../use_point_size_escape_with_single_digit_arg.sh | 36 +++++++++++++++++
 src/roff/troff/input.cpp                           |  5 ++-
 7 files changed, 131 insertions(+), 11 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index ab971e9..029882e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,50 @@
 2020-04-04  G. Branden Robinson <address@hidden>
 
+       * src/roff/troff/input.cpp (read_size): Move special-case
+       interpretation of the '\sN' form of point-size escapes when 'N'
+       is 1, 2, or 3 to compatibility mode (groff -C) only, and throw
+       error diagnostic with suggestion for remedy if encountered.
+
+       Traditionally, '\s36A' is interpreted as "set point size to 36,
+       then emit 'A'".  However, only values in the range 10-39 are
+       handled specially; '\s40A' is interpreted as a four-point "0A".
+       This is unlike anything else in *roff grammar; see \*, \$, \f,
+       \F, \g, \k, \m, \M, \n, \V, and \Y.
+
+       To anticipate objections: Why not throw only a warning?  Because
+       there isn't a warning category for supported but ambiguous
+       syntax (this behavior of AT&T troff dates to 1976 but apparently
+       was not documented until 1992).  Why not throw the error outside
+       of compatibility mode too?  Because outside of compatibility
+       mode we (now) have an unambiguous parse.
+
+       Background: The Graphic Systems C/A/T phototypesetter (the
+       original device target for AT&T troff) only supported a few
+       discrete point sizes in the range 6..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
+       {§2.3}, and more recently, McIlroy referred to it as a "living
+       fossil".
+
+       See:
+         https://lists.gnu.org/archive/html/groff/2020-03/msg00054.html
+         https://lists.gnu.org/archive/html/groff/2020-04/msg00002.html
+         https://lists.gnu.org/archive/html/groff/2020-04/msg00015.html
+       and follow-ups for discussion.
+
+       * NEWS: Advise users of behavior change and offer guidance.
+
+       * doc/groff.texi:
+       * man/groff.7.man: Document the restriction of special handling
+       of point-size arguments to '\s' to compatibility mode.
+
+       * src/roff/groff/groff.am:
+       * src/roff/groff/tests/\
+       use_point_size_escape_with_single_digit_arg.sh: Add regression
+       test.
+
+2020-04-04  G. Branden Robinson <address@hidden>
+
        Improve point-size escape diagnostics.
 
        * src/roff/troff/input.cpp (read_size): Disclose context
diff --git a/NEWS b/NEWS
index ceec719..5461678 100644
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,4 @@
-    Copyright (C) 1992-2019 Free Software Foundation, Inc.
+    Copyright (C) 1992-2020 Free Software Foundation, Inc.
 
     Copying and distribution of this file, with or without modification,
     are permitted in any medium without royalty provided the copyright
@@ -13,6 +13,34 @@ VERSION 1.22.5
 Troff
 -----
 
+o Point-size escapes of the form '\sNN', where NN is in the range 10-39, are
+  now recognized only in compatibility mode (groff -C); when encountered an
+  error diagnostic is emitted.  In normal mode, \sN is interpreted as
+  setting the point size to the single digit value N, which ends the escape.
+  This change eliminates a quirk in the language grammar that dates back to
+  1976 (AT&T troff by Ossanna) but apparently was not documented until 1992
+  when Kernighan updated CSTR #54 for AT&T ditroff.
+
+  The form '\s(NN' is accepted for two-digit point sizes in all known
+  troffs.  The form '\s[NNN]' accepts a numeric expression of variable
+  length; it has been supported by groff since version 1.02 (June 1991) at
+  the latest and is by current versions of Heirloom troff and neatroff.  The
+  form "\s'NNN'" is also widely supported.
+
+  Short version: in your documents, rewrite escapes beginning with '\s1',
+  '\s2', or '\s3' in an unambiguous and portable form.  For instance, '\s36'
+  can become any of:
+    \s(36
+    \s[36]
+    \s'36'
+  You can use
+    grep '\\s[123]'
+  to find instances in your documents.
+
+  Those who have changed the escape character with the 'ec' request (an
+  advanced usage) are expected to be able to cope; ask the development team
+  for support if you need it.
+
 o New requests 'stringdown' and 'stringup' are available.  These change
   the string named in their argument by replacing each of its bytes with its
   lowercase or uppercase version (if any), respectively.  groff special
diff --git a/doc/groff.texi b/doc/groff.texi
index 65eea20..6381248 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -10051,8 +10051,12 @@ 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 either
-0 or in the range 4 to@tie{}39.
+Set the point size to @var{n}@tie{}points.  @var{n}@tie{}must be a
+single digit.
+
+In compatibility mode only, @var{n}@tie{}must be@tie{}0 or in the range
+4 to@tie{}39.  Legacy documents relying upon this quirk of parsing
+should be migrated to the \s(@var{nn} or \s[@var{n}] forms.
 
 @item \s+@var{n}
 @itemx \s-@var{n}
diff --git a/man/groff.7.man b/man/groff.7.man
index e1d6a25..b723481 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3299,13 +3299,16 @@ The same as
 .ESC s \[+-]N
 Set/increase/decrease the point size to/by
 .I N
-scaled points;
+scaled points.
+.
+.I N
+must be a single digit;
+0 restores the previous point size.
+.
+(In compatibility mode only,
+a non-zero
 .I N
-must be either 0
-(restore previous size)
-or,
-for historical reasons,
-in the range 4\[en]39.
+must be in the range 4\[en]39.)
 .
 Otherwise,
 same as
diff --git a/src/roff/groff/groff.am b/src/roff/groff/groff.am
index c56b956..fae28aa 100644
--- a/src/roff/groff/groff.am
+++ b/src/roff/groff/groff.am
@@ -46,7 +46,8 @@ groff_TESTS = \
   src/roff/groff/tests/regression_savannah_56555.sh \
   src/roff/groff/tests/string_case_xform_errors.sh \
   src/roff/groff/tests/string_case_xform_requests.sh \
-  src/roff/groff/tests/string_case_xform_unicode_escape.sh
+  src/roff/groff/tests/string_case_xform_unicode_escape.sh \
+  src/roff/groff/tests/use_point_size_escape_with_single_digit_arg.sh
 TESTS += $(groff_TESTS)
 
 groff_XFAIL_TESTS = \
diff --git 
a/src/roff/groff/tests/use_point_size_escape_with_single_digit_arg.sh 
b/src/roff/groff/tests/use_point_size_escape_with_single_digit_arg.sh
new file mode 100755
index 0000000..4dc9073
--- /dev/null
+++ b/src/roff/groff/tests/use_point_size_escape_with_single_digit_arg.sh
@@ -0,0 +1,36 @@
+#!/bin/sh
+#
+# Copyright (C) 2020 Free Software Foundation, Inc.
+#
+# This file is part of groff.
+#
+# groff is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# groff is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+
+groff="${abs_top_builddir:-.}/test-groff"
+
+# The vertical space is so that the 36-point 'A' won't be truncated by
+# the top of the page.  That could be confusing and misleading to anyone
+# who ever has to troubleshoot this test case.
+DOC=".vs 10v
+\s36A"
+
+# Verify that the idiosyncratic behavior of \sN is supported in
+# compatibility mode...
+echo "testing \s36A in compatiblity mode (36-point 'A')" >&2
+echo "$DOC" | "$groff" -C -Z | grep -qx 's36000'
+
+# ...and not in regular mode.
+echo "testing \s36A in non-compatiblity mode (3-point '6A')" >&2
+echo "$DOC" | "$groff" -Z | grep -qx 's3000'
diff --git a/src/roff/troff/input.cpp b/src/roff/troff/input.cpp
index 6f35dad..87080ff 100644
--- a/src/roff/troff/input.cpp
+++ b/src/roff/troff/input.cpp
@@ -5076,13 +5076,16 @@ static int read_size(int *x)
   }
   else if (csdigit(c)) {
     val = c - '0';
-    if (!inc && c != '0' && c < '4') {
+    if (compatible_flag && !inc && c != '0' && c < '4') {
+      // Support legacy \sNN syntax.
       tok.next();
       c = tok.ch();
       if (!csdigit(c))
        bad_digit = 1;
       else
        val = val*10 + (c - '0');
+       error("ambiguous point-size escape; rewrite to use '\\s(%1'"
+             " or similar", val);
     }
     val *= sizescale;
   }