[tex-k] Bug: Incorrect TANGLE error message while catching some "@z"s

[Doug McKenna]

When computer error messages are misleading, they waste the user's precious time.  I recognize that when it comes to accurate computer language error reporting, the problem is deep and likely insoluable.  Except when it's not, in which case a misleading error message is a bug because it causes unnecessary harm.

TANGLE issues such an incorrect error message for an unterminated Pascal comment in the @y... at z portion of a change file.

As the initial change mechanism is forwarding changed lines to the TANGLE token parser, and the parser senses a '{' in a Pascal code area, it then starts to collect a Pascal comment terminated by a balanced '}'.  The comment usually ends on the same line, but it doesn't have to be.  Because a Pascal comment can continue on multiple lines, if the comment is being introduced in a ".ch" file in the @y... at z portion and the comment's terminating '}' is missing, TANGLE's comment collecting routine |skip_comment| will eventually encounter the line with the @z on it, or a new section command.

|skip_comment| tests for these conditions, both being indicative (though not necessarily, as the test example below shows) of a runaway Pascal comment.

See line 2609 of "tangle.web" or Section 142 in the typeset version.  When TANGLE senses a @z *anywhere* on a line while collecting a Pascal comment, it complains, but with an incorrect, unnecessarily misleading explanation.

For instance, after I appended what I thought was a legal Pascal comment {@y at x@z} to the end of line 2608 in tangle.web, where these commented WEB commands should have no effect because they don't start a line, TANGLE balks with:

=======================
This is TANGLE, Version 4.5 (TeX Live 2019)
*1*11*19*29*37*50*65*70*77*94*112*123
! Section ended in mid-comment. (l.2608)
  begin c:=buffer[loc];{@y at x@
                             z} 
! Extra }. (l.2608)
  begin c:=buffer[loc];{@y at x@z}
                                *143*156*163*171*179*182*188*189
Writing the output file.....500...
Done.
(Pardon me, but I think I spotted something wrong.)
=======================

The bug is that regardless of whether the comment is legal or not, the *section* plainly did not end in mid-comment.  And the comment should be perfectly legal because TANGLE's change mechanism cares about @x, @y, or @z WEB commands only when the command is at the start of a line (per lines 2371 to 2378 in tangle.web).

To correct this error-reporting error, I would change the following code in "tangle.web", starting on the next line 2609:

  if (c<>" ")and(c<>tab_mark)and(c<>"*")and(c<>"z")and(c<>"Z") then incr(loc)
  else  begin err_print('! Section ended in mid-comment');
@.Section ended in mid-comment@>
    decr(loc); return;
    end

to something like:

  if (c==" ")or(c==tab_mark)or(c=="*") then begin
     err_print('! Section ended in mid-comment');
@.Section ended in mid-comment@>
     decr(loc); return;
     end
  else if (loc==2)and((c=="z")or(c=="Z")) then begin
     err_print('! End of change in mid-comment');
@.End of change in mid-comment@>
     decr(loc); return;
     end
  else
     incr(loc)

ctangle.w only tests for the section end/beginning in its equivalent skip_comment() routine for a runaway comment.  It doesn't have the same @z test, for whatever reasons that I haven't investigated.


FWIW,

Doug McKenna