[groff] 06/07: [troff]: Adjust diagnostic message text.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 64512940a2b00cc0888e0d9fa1f2720ef0417b35
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jun 22 16:08:19 2022 -0500

    [troff]: Adjust diagnostic message text.
    
    [troff]: Adjust diagnostic message text to clarify and better match
    terminology used in documentation.
    
    * src/roff/troff/input.cpp (set_escape_char, do_overstrike, do_bracket,
      do_name_test, do_width, do_special):
    * src/roff/troff/node.cpp (suppress_node::tprint): Migrate from "escape"
      to "escape sequence".
    
    * src/roff/troff/node.cpp (make_composite_node, make_glyph_node):
      Clarify what went wrong.
    
    * src/roff/troff/input.cpp (token::get_char, check_missing_character):
      Migrate from "normal character" to "ordinary character" (see
      groff_char(7)).
    
    Also add comment near possibly unreachable code.
---
 ChangeLog                | 17 +++++++++++++++++
 src/roff/troff/input.cpp | 32 +++++++++++++++++++-------------
 src/roff/troff/node.cpp  | 27 ++++++++++++++-------------
 3 files changed, 50 insertions(+), 26 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 72b9be48..3735f66e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,20 @@
+2022-06-22  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [troff]: Adjust diagnostic message text to clarify and better
+       match terminology used in documentation.
+
+       * src/roff/troff/input.cpp (set_escape_char, do_overstrike,
+       do_bracket, do_name_test, do_width, do_special):
+       * src/roff/troff/node.cpp (suppress_node::tprint): Migrate from
+       "escape" to "escape sequence".
+
+       * src/roff/troff/node.cpp (make_composite_node,
+       make_glyph_node): Clarify what went wrong.
+
+       * src/roff/troff/input.cpp (token::get_char,
+       check_missing_character): Migrate from "normal character" to
+       "ordinary character" (see groff_char(7)).
+
 2022-06-22  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [troff]: Rename a function for clarity.
diff --git a/src/roff/troff/input.cpp b/src/roff/troff/input.cpp
index b605113a..ee6c0771 100644
--- a/src/roff/troff/input.cpp
+++ b/src/roff/troff/input.cpp
@@ -165,7 +165,7 @@ void set_escape_char()
 {
   if (has_arg()) {
     if (tok.ch() == 0) {
-      error("bad escape character");
+      error("invalid escape character");
       escape_char = '\\';
     }
     else
@@ -1440,8 +1440,8 @@ node *do_overstrike()
   for (;;) {
     tok.next();
     if (tok.is_newline() || tok.is_eof()) {
-      warning(WARN_DELIM, "missing closing delimiter in"
-             " overstrike escape (got %1)", tok.description());
+      warning(WARN_DELIM, "missing closing delimiter in overstrike"
+            " escape sequence (got %1)", tok.description());
       input_stack::push(make_temp_iterator("\n"));
       break;
     }
@@ -1478,7 +1478,8 @@ static node *do_bracket()
     tok.next();
     if (tok.is_eof() || tok.is_newline()) {
       warning(WARN_DELIM, "missing closing delimiter in"
-             " bracket-building escape (got %1)", tok.description());
+             " bracket-building escape sequence (got %1)",
+             tok.description());
       // XXX: Most other places we miss a closing delimiter, we push a
       // temp iterator for the EOF case too.  What's special about \b?
       // Exceptions: \w, \X are like this too.
@@ -1509,8 +1510,9 @@ static int do_name_test()
   for (;;) {
     tok.next();
     if (tok.is_newline() || tok.is_eof()) {
-      warning(WARN_DELIM, "missing closing delimiter in"
-             " name test escape (got %1)", tok.description());
+      warning(WARN_DELIM, "missing closing delimiter in identifier"
+             " validation escape sequence (got %1)",
+             tok.description());
       input_stack::push(make_temp_iterator("\n"));
       break;
     }
@@ -5263,7 +5265,7 @@ static void do_width()
     tok.next();
     if (tok.is_eof() || tok.is_newline()) {
       warning(WARN_DELIM, "missing closing delimiter in"
-             " width escape (got %1)", tok.description());
+             " width computation escape sequence (got %1)", tok.description());
       // XXX: Most other places we miss a closing delimiter, we push a
       // temp iterator for the EOF case too.  What's special about \w?
       // Exception: \b, \X are like this too.
@@ -5477,8 +5479,8 @@ node *do_special()
        tok != start || input_stack::get_level() != start_level;
        tok.next()) {
     if (tok.is_eof() || tok.is_newline()) {
-      warning(WARN_DELIM, "missing closing delimiter in"
-             " device special escape (got %1)", tok.description());
+      warning(WARN_DELIM, "missing closing delimiter in device control"
+             " escape sequence (got %1)", tok.description());
       // XXX: Most other places we miss a closing delimiter, we push a
       // temp iterator for the EOF case too.  What's special about \X?
       // Exceptions: \b, \w are like this too.
@@ -7227,15 +7229,19 @@ charinfo *token::get_char(bool required)
     if (escape_char != 0)
       return charset_table[escape_char];
     else {
-      error("'\\e' used while no current escape character");
+      // XXX: Is this possible?  token::add_to_zero_width_node_list()
+      // and token::process() don't add this token type if the escape
+      // character is null.  If not, this should be an assert().  Also
+      // see escape_off().
+      error("'\\e' used while escape sequences disabled");
       return 0;
     }
   }
   if (required) {
     if (type == TOKEN_EOF || type == TOKEN_NEWLINE)
-      warning(WARN_MISSING, "missing normal or special character");
+      warning(WARN_MISSING, "missing ordinary or special character");
     else
-      error("expected normal or special character, got %1",
+      error("expected ordinary or special character, got %1",
            description());
   }
   return 0;
@@ -7257,7 +7263,7 @@ void check_missing_character()
 {
   if (!tok.is_newline() && !tok.is_eof() && !tok.is_right_brace()
       && !tok.is_tab())
-    error("expected normal or special character, got %1; treated as"
+    error("expected ordinary or special character, got %1; treated as"
          " missing", tok.description());
 }
 
diff --git a/src/roff/troff/node.cpp b/src/roff/troff/node.cpp
index 37786705..b348c949 100644
--- a/src/roff/troff/node.cpp
+++ b/src/roff/troff/node.cpp
@@ -725,7 +725,7 @@ class real_output_file : public output_file {
   int piped;
 #endif
   int printing;                // decision via optional page list
-  int output_on;       // \O[0] or \O[1] escape calls
+  int output_on;       // \O[0] or \O[1] escape sequences
   virtual void really_transparent_char(unsigned char) = 0;
   virtual void really_print_line(hunits x, vunits y, node *n,
                                 vunits before, vunits after, hunits width) = 0;
@@ -4135,8 +4135,8 @@ void suppress_node::tprint(troff_output_file *out)
        // Ensure the new string fits with room for a terminal '\0'.
        const size_t len = strlen(new_name);
        if (len > (namebuflen - 1))
-         error("constructed file name in suppressed output escape is"
-               " too long (>= %1 bytes); skipping image",
+         error("constructed file name in suppressed output escape"
+               " sequence is too long (>= %1 bytes); skipping image",
                (int)namebuflen);
        else
          strncpy(name, new_name, (namebuflen - 1));
@@ -4145,8 +4145,8 @@ void suppress_node::tprint(troff_output_file *out)
       }
       else {
        if (image_filename_len > (namebuflen - 1))
-         error("file name in suppressed output escape is too long"
-               " (>= %1 bytes); skipping image", (int)namebuflen);
+         error("file name in suppressed output escape sequence is too"
+               " long (>= %1 bytes); skipping image", (int)namebuflen);
        else
          strcpy(name, image_filename);
       }
@@ -4893,7 +4893,7 @@ node *make_composite_node(charinfo *s, environment *env)
 {
   int fontno = env_definite_font(env);
   if (fontno < 0) {
-    error("no current font");
+    error("cannot format composite glyph: no current font");
     return 0;
   }
   assert(fontno < font_table_size && font_table[fontno] != 0);
@@ -4912,7 +4912,7 @@ node *make_glyph_node(charinfo *s, environment *env, int 
no_error_message = 0)
 {
   int fontno = env_definite_font(env);
   if (fontno < 0) {
-    error("no current font");
+    error("cannot format glyph: no current font");
     return 0;
   }
   assert(fontno < font_table_size && font_table[fontno] != 0);
@@ -4924,8 +4924,8 @@ node *make_glyph_node(charinfo *s, environment *env, int 
no_error_message = 0)
       return make_composite_node(s, env);
     if (s->numbered()) {
       if (!no_error_message)
-       warning(WARN_CHAR, "can't find numbered character %1",
-               s->get_number());
+       warning(WARN_CHAR, "character code %1 not defined in current"
+               " font", s->get_number());
       return 0;
     }
     special_font_list *sf = font_table[fontno]->sf;
@@ -4971,15 +4971,16 @@ node *make_glyph_node(charinfo *s, environment *env, 
int no_error_message = 0)
        unsigned char input_code = s->get_ascii_code();
        if (input_code != 0) {
          if (csgraph(input_code))
-           warning(WARN_CHAR, "can't find character '%1'", input_code);
+           warning(WARN_CHAR, "character '%1' not defined",
+                   input_code);
          else
-           warning(WARN_CHAR, "can't find character with input code %1",
-                   int(input_code));
+           warning(WARN_CHAR, "character with input code %1 not"
+                   " defined", int(input_code));
        }
        else if (s->nm.contents()) {
          const char *nm = s->nm.contents();
          const char *backslash = (nm[1] == 0) ? "\\" : "";
-         warning(WARN_CHAR, "can't find special character '%1%2'",
+         warning(WARN_CHAR, "special character '%1%2' not defined",
                  backslash, nm);
        }
       }