gbranden pushed a commit to branch master
in repository groff.

commit 34e8d85af54c826218f08a9b43c17b95361d7267
Author: G. Branden Robinson <[email protected]>
AuthorDate: Mon Nov 2 20:34:02 2026 -0600

    src/roff/troff/{div,input}.cpp: Annotate.
    
    Post more notices of a hazardous mine field.
---
 src/roff/troff/div.cpp   | 15 ++++++++++++++-
 src/roff/troff/input.cpp |  1 +
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/src/roff/troff/div.cpp b/src/roff/troff/div.cpp
index eb0b02e84..3ec7d13a4 100644
--- a/src/roff/troff/div.cpp
+++ b/src/roff/troff/div.cpp
@@ -879,6 +879,13 @@ outputting of the line forced out by the break till after 
we have read
 the argument to the request.  If the break did cause a trap to be
 sprung, then we don't actually do the space. */
 
+// JJC made the foregoing observation in 1991 (or earlier).  The same
+// reasoning applies to `ne`, `sv`, and `os` because they can (but might
+// not) spring a trap.  If you screw this up, you can get a baffling
+// "spurious end trap token detected" error.  It's okay to `skip_line()`
+// when the request handler bails out without doing anything; otherwise
+// it must do the token dance.  --GBR
+
 static void space_request() // .sp
 {
   postpone_traps();
@@ -917,6 +924,8 @@ void blank_line()
 /* need_space might spring a trap and so we must be careful that the
 BEGIN_TRAP token is not skipped over. */
 
+// See the comments prior to the `sp` request handler above. --GBR
+
 static void need_vertical_space_request() // .ne
 {
   vunits n;
@@ -948,6 +957,8 @@ static void set_page_number_request() // .pn
   skip_line();
 }
 
+// See the comments prior to the `sp` request handler above. --GBR
+
 vunits saved_space;
 
 static void save_vertical_space_request() // .sv
@@ -965,9 +976,11 @@ static void save_vertical_space_request() // .sv
     curdiv->space(x, true /* forcing */);
   else
     saved_space = x;
-  skip_line();
+  skip_line(); // XXX: This might be erroneous. --GBR
 }
 
+// See the comments prior to the `sp` request handler above. --GBR
+
 static void output_saved_vertical_space_request() // .os
 {
   while (!tok.is_terminator())
diff --git a/src/roff/troff/input.cpp b/src/roff/troff/input.cpp
index 1b42f0476..d399867f4 100644
--- a/src/roff/troff/input.cpp
+++ b/src/roff/troff/input.cpp
@@ -3934,6 +3934,7 @@ void process_input_stack()
     case token::TOKEN_END_TRAP:
       {
        if (trap_accepting_control_character_stack.empty())
+         // See comment prior to `sp` request handler in div.cpp.
          error("spurious end trap token detected!");
        else {
          can_accept_control_character

_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit

Reply via email to