[groff] 04/37: [troff]: Revise some diagnostic messages.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 83657bdfac631895aa3a180447b2d051f75f5966
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Mar 7 11:00:55 2022 +1100

    [troff]: Revise some diagnostic messages.
    
    * src/roff/troff/input.cpp (get_char_for_escape_name): Recast diagnostic
      messages to more accurately refer to escape "sequence" rather than
      "name".  "Name" is a confusing term here, given that it also applies
      to a group of objects sharing a name space (natch): requests, macros,
      strings, and diversions.  Further, the "escape name" cited by these
      diagnostics is not the escape function selector; that is, the
      character after the escape character which determines how the escape
      sequence is to be interpreted.  These diagnostics are only thrown
      after that function is known, however, when parsing of an escape
      sequence parameter is attempted.
    
      (input_char_description): Drop leading articles ("a") from
      descriptions, to economize in diagnostic messages this function helps
      produce.
    
    * src/roff/troff/input.cpp (read_size):
    * src/roff/troff/number.cpp (start_number, parse_term): Recast messages
      to more consistently use the form "expected X, got Y" where feasible.
    
    * src/roff/troff/number.cpp (start_number): Say "numeric expression
      missing" instead of "missing number"; we don't require a terminal
      symbol in the expression grammar here.
---
 ChangeLog                 | 30 ++++++++++++++++++++++++++++++
 src/roff/troff/input.cpp  | 33 +++++++++++++++++----------------
 src/roff/troff/number.cpp | 14 ++++++++------
 3 files changed, 55 insertions(+), 22 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 2d75b3bc..da95c994 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,33 @@
+2022-03-07  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * src/roff/troff/input.cpp (get_char_for_escape_name): Recast
+       diagnostic messages to more accurately refer to escape
+       "sequence" rather than "name".  "Name" is a confusing term here,
+       given that it also applies to a group of objects sharing a name
+       space (natch): requests, macros, strings, and diversions.
+       Further, the "escape name" cited by these diagnostics is not the
+       escape function selector; that is, the character after the
+       escape character which determines how the escape sequence is to
+       be interpreted.  These diagnostics are only thrown after that
+       function is known, however, when parsing of an escape sequence
+       parameter is attempted.
+       (input_char_description): Drop leading articles ("a") from
+       input character descriptions, to economize in diagnostic
+       messages this function helps produce.
+       (non_empty_name_warning): Use zero copula for economy.
+
+       * src/roff/troff/input.cpp (empty_name_warning, read_size,
+       token::get_char, check_missing_character):
+       * src/roff/troff/number.cpp (start_number, parse_term): Recast
+       messages to more consistently use the form "expected X, got Y"
+       where feasible.
+
+       * src/roff/troff/number.cpp (start_number): Say "numeric
+       expression missing" instead of "missing number"; we don't
+       require a terminal symbol in the expression grammar here.  Also
+       use `tok.description()` where we can, and remove assumption that
+       the escape character is the default.
+
 2022-03-06  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/an.tmac (AT, UC, HP): Add deprecation warnings.  For the
diff --git a/src/roff/troff/input.cpp b/src/roff/troff/input.cpp
index ddd8a476..eeb159de 100644
--- a/src/roff/troff/input.cpp
+++ b/src/roff/troff/input.cpp
@@ -822,7 +822,7 @@ static char get_char_for_escape_name(int allow_space = 0)
   int c = get_copy(0, false /* is defining */, true /* handle \E */);
   switch (c) {
   case EOF:
-    copy_mode_error("end of input in escape name");
+    copy_mode_error("end of input in escape sequence");
     return '\0';
   default:
     if (!invalid_input_char(c))
@@ -839,7 +839,7 @@ static char get_char_for_escape_name(int allow_space = 0)
   case '\t':
   case '\001':
   case '\b':
-    copy_mode_error("%1 is not allowed in an escape name",
+    copy_mode_error("%1 not allowed in escape sequence parameter",
                    input_char_description(c));
     return '\0';
   }
@@ -2477,9 +2477,10 @@ static void empty_name_warning(bool required)
       warning(WARN_MISSING, "missing name");
   }
   else if (required)
-    error("name expected (got %1)", tok.description());
+    error("expected name, got %1", tok.description());
   else
-    error("name expected (got %1): treated as missing", tok.description());
+    error("expected name, got %1; treated as missing",
+         tok.description());
 }
 
 static void non_empty_name_warning()
@@ -2488,7 +2489,7 @@ static void non_empty_name_warning()
       && !tok.is_tab() && !tok.is_right_brace()
       // We don't want to give a warning for .el\{
       && !tok.is_left_brace())
-    error("%1 is not allowed in a name", tok.description());
+    error("%1 not allowed in a name", tok.description());
 }
 
 symbol get_name(bool required)
@@ -5116,7 +5117,7 @@ static bool read_size(int *x)
   }
   if (contains_invalid_digit) {
     if (c)
-      error("invalid digit in type size escape sequence: %1",
+      error("expected valid digit in type size escape sequence, got %1",
            input_char_description(c));
     else
       error("invalid digit in type size escape sequence");
@@ -6628,17 +6629,17 @@ const char *input_char_description(int c)
 {
   switch (c) {
   case '\n':
-    return "a newline character";
+    return "newline character";
   case '\b':
-    return "a backspace character";
+    return "backspace character";
   case '\001':
-    return "a leader character";
+    return "leader character";
   case '\t':
-    return "a tab character";
+    return "tab character";
   case ' ':
-    return "a space character";
+    return "space character";
   case '\0':
-    return "a node";
+    return "node";
   }
   static char buf[sizeof("magic character code ") + 1 + INT_DIGITS];
   if (invalid_input_char(c)) {
@@ -7226,7 +7227,8 @@ charinfo *token::get_char(bool required)
     if (type == TOKEN_EOF || type == TOKEN_NEWLINE)
       warning(WARN_MISSING, "missing normal or special character");
     else
-      error("normal or special character expected (got %1)", description());
+      error("expected normal or special character, got %1",
+           description());
   }
   return 0;
 }
@@ -7247,9 +7249,8 @@ void check_missing_character()
 {
   if (!tok.is_newline() && !tok.is_eof() && !tok.is_right_brace()
       && !tok.is_tab())
-    error("normal or special character expected (got %1): "
-         "treated as missing",
-         tok.description());
+    error("expected normal or special character, got %1; treated as"
+         " missing", tok.description());
 }
 
 // this is for \Z
diff --git a/src/roff/troff/number.cpp b/src/roff/troff/number.cpp
index aec446d0..31f2d74e 100644
--- a/src/roff/troff/number.cpp
+++ b/src/roff/troff/number.cpp
@@ -217,15 +217,17 @@ static int start_number()
   while (tok.is_space())
     tok.next();
   if (tok.is_newline()) {
-    warning(WARN_MISSING, "missing number");
+    warning(WARN_MISSING, "numeric expression missing");
     return 0;
   }
   if (tok.is_tab()) {
-    warning(WARN_TAB, "tab character where number expected");
+    warning(WARN_TAB, "expected numeric expression, got %1",
+           tok.description());
     return 0;
   }
   if (tok.is_right_brace()) {
-    warning(WARN_RIGHT_BRACE, "'\\}' where number expected");
+    warning(WARN_RIGHT_BRACE, "expected numeric expression, got right"
+           "brace escape sequence");
     return 0;
   }
   return 1;
@@ -460,7 +462,7 @@ static int parse_term(units *v, int scaling_indicator,
        scaling_indicator = c;
       }
       else {
-       error("expected ';' after scaling unit (got %1)",
+       error("expected ';' after scaling unit, got %1",
              tok.description());
        return 0;
       }
@@ -475,7 +477,7 @@ static int parse_term(units *v, int scaling_indicator,
     if (tok.ch() != ')') {
       if (rigid)
        return 0;
-      warning(WARN_SYNTAX, "missing ')' (got %1)", tok.description());
+      warning(WARN_SYNTAX, "experted ')', got %1", tok.description());
     }
     else
       tok.next();
@@ -528,7 +530,7 @@ static int parse_term(units *v, int scaling_indicator,
     *v = 0;
     return rigid ? 0 : 1;
   default:
-    warning(WARN_NUMBER, "numeric expression expected (got %1)",
+    warning(WARN_NUMBER, "expected numeric expression, got %1",
            tok.description());
     return 0;
   }