[groff] 02/02: Lower new unplanted trap error to 'mac' warning.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 4e23c800e68ebf13d345491483639b97107816d6
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Dec 9 12:46:49 2020 +1100

    Lower new unplanted trap error to 'mac' warning.
    
    * src/roff/troff/div.cpp (top_level_diversion::change_trap): Change
      error upon invalid attempt to move an unplanted trap into a warning of
      type 'mac'.
    
    This somewhat stretches the documented semantics of the 'mac' warning
    type, so recast them to accommodate the new instance.
    
    * doc/groff.texi (Warnings):
    * src/roff/troff/troff.1.man (Warnings): Recast description of 'mac'
      warning type to include the above scenario.
    
      Recast to mention boxes as well as traditional diversions.  Refer to
      macros, strings, diversions, and boxes collectively as "objects"
      instead of "macros", avoiding synecdoche.  Use complete sentences.
    
    Thanks to Bjarni Ingi Gislason for reporting the diagnostic arising in
    real life, and to Peter Schaffter for the discussion and recommendation.
    Some bike sheds get painted quickly!
    
    Fixes <https://savannah.gnu.org/bugs/?59573>.
---
 ChangeLog                  | 18 ++++++++++++++++++
 doc/groff.texi             | 11 +++++++----
 src/roff/troff/div.cpp     |  3 ++-
 src/roff/troff/troff.1.man | 24 ++++++++++++++++++++----
 4 files changed, 47 insertions(+), 9 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index db1b2fd..bc8262c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,21 @@
+2020-12-09  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       Lower new unplanted trap error to 'mac' warning.
+
+       * src/roff/troff/div.cpp (top_level_diversion::change_trap):
+       Change error upon invalid attempt to move an unplanted trap into
+       a warning of type 'mac'.
+
+       * doc/groff.texi (Warnings):
+       * src/roff/troff/troff.1.man (Warnings): Recast description of
+       'mac' warning type to include the above scenario.
+
+       Thanks to Bjarni Ingi Gislason for reporting the diagnostic
+       arising in real life, and to Peter Schaffter for the discussion
+       and recommendation.  Some bike sheds get painted quickly!
+
+       Fixes <https://savannah.gnu.org/bugs/?59573>.
+
 2020-12-05  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/groff_mdoc.7.man: Tweak mandatory macro explanations.
diff --git a/doc/groff.texi b/doc/groff.texi
index 2ac6c64..60f7e61 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -15153,10 +15153,13 @@ current diversion.
 @cindex @code{da} request, and warnings
 @cindex @code{box}, @code{boxa} requests, and warnings
 @cindex @code{\*}, and warnings
-Use of undefined strings, macros and diversions.  When an undefined
-string, macro, or diversion is used, that string is automatically
-defined as empty.  So, in most cases, at most one warning is given for
-each name.
+An undefined string, macro, diversion, or box was used.  When such an
+object is dereferenced, an empty object of that name is automatically
+created.  So, in most cases, at most one warning is given for each name.
+
+This warning is also emitted upon an attempt to move an unplanted trap
+(@pxref{Page Location Traps}).  In such cases, the unplanted macro is
+@emph{not} dereferenced, so it is not created if it does not exist.
 
 @item reg
 @itemx 1024
diff --git a/src/roff/troff/div.cpp b/src/roff/troff/div.cpp
index 014d865..63e2754 100644
--- a/src/roff/troff/div.cpp
+++ b/src/roff/troff/div.cpp
@@ -531,7 +531,8 @@ void top_level_diversion::change_trap(symbol nam, vunits 
pos)
       p->position = pos;
       return;
     }
-  error("cannot move unplanted trap macro '%1'", nam.contents());
+  warning(WARN_MAC, "cannot move unplanted trap macro '%1'",
+         nam.contents());
 }
 
 void top_level_diversion::print_traps()
diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man
index 4596756..eb3b92a 100644
--- a/src/roff/troff/troff.1.man
+++ b/src/roff/troff/troff.1.man
@@ -520,12 +520,28 @@ Invalid input characters.
 .
 .TP
 .BR mac "\t512"
-Use of undefined strings, macros and diversions.
+An undefined string,
+macro,
+diversion,
+or box was used.
 .
-When an undefined string, macro or diversion is used, that string is
-automatically defined as empty.
+When such an object is dereferenced,
+an empty object of that name is automatically created.
+.
+So,
+in most cases,
+at most one warning is given for each name.
+.
+.
+.IP
+This warning is also emitted upon an attempt to move an unplanted trap.
+.
+In such cases,
+the unplanted macro is
+.I not
+dereferenced,
+so it is not created if it does not exist.
 .
-So, in most cases, at most one warning will be given for each name.
 .
 .TP
 .BR missing "\t8192"