[groff] 05/16: [troff]: Revise diagnostics.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 30333bb2fa7e09716676e914d8f9e525af837dd5
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Jan 8 05:00:39 2024 -0600

    [troff]: Revise diagnostics.
    
    * src/roff/troff/div.cpp (top_level_diversion::output)
      (top_level_diversion::transparent_output)
      (top_level_diversion::copy_file): Recast diagnostic messages to be
      distinguishable and provide more information about what the problem
      is.  Make the proffered advice agnostic with respect to choice of
      control character and request renaming.
---
 ChangeLog              | 11 +++++++++++
 src/roff/troff/div.cpp | 13 ++++++++++---
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index af8863151..b8195d6e9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2024-01-08  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [troff]: Revise diagnostics.
+
+       * src/roff/troff/div.cpp (top_level_diversion::output)
+       (top_level_diversion::transparent_output)
+       (top_level_diversion::copy_file): Recast diagnostic messages to
+       be distinguishable and provide more information about what the
+       problem is.  Make the proffered advice agnostic with respect to
+       choice of control character and request renaming.
+
 2024-01-08  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [troff]: Trivially refactor.
diff --git a/src/roff/troff/div.cpp b/src/roff/troff/div.cpp
index 0cbae5c8e..6d313ab5d 100644
--- a/src/roff/troff/div.cpp
+++ b/src/roff/troff/div.cpp
@@ -398,7 +398,8 @@ void top_level_diversion::output(node *nd, int retain_size,
   vunits next_trap_pos;
   trap *next_trap = find_next_trap(&next_trap_pos);
   if (before_first_page && begin_page())
-    fatal("sorry, I didn't manage to begin the first page in time: use an 
explicit .br request");
+    fatal("attempting output of top-level diversion before first page"
+         " has started; invoke break or flush request earlier");
   vertical_size v(vs, post_vs);
   for (node *tem = nd; tem != 0; tem = tem->next)
     tem->set_vertical_size(&v);
@@ -444,7 +445,9 @@ void top_level_diversion::transparent_output(unsigned char 
c)
 {
   if (before_first_page && begin_page())
     // This can only happen with the .output request.
-    fatal("sorry, I didn't manage to begin the first page in time: use an 
explicit .br request");
+    fatal("attempting transparent output of top-level diversion before"
+         " first page has started; invoke break or flush request"
+         " earlier");
   const char *s = asciify(c);
   while (*s)
     the_output->transparent_char(*s++);
@@ -452,6 +455,8 @@ void top_level_diversion::transparent_output(unsigned char 
c)
 
 void top_level_diversion::transparent_output(node * /*n*/)
 {
+  // TODO: Restore this diagnostic when Savannah #65371 is fixed;
+  // perhaps suggest use of \[uXXXX] notation.
   if (getenv("GROFF_ENABLE_TRANSPARENCY_WARNINGS") != 0 /* nullptr */)
     error("can't transparently output node at top level");
 }
@@ -459,7 +464,9 @@ void top_level_diversion::transparent_output(node * /*n*/)
 void top_level_diversion::copy_file(const char *filename)
 {
   if (before_first_page && begin_page())
-    fatal("sorry, I didn't manage to begin the first page in time: use an 
explicit .br request");
+    fatal("attempting transparent copy of file to top-level diversion"
+         " before first page has started; invoke break or flush"
+         " request earlier");
   the_output->copy_file(page_offset, vertical_position, filename);
 }