[tex-k] Module name typesetting bug in either tangle.web or weave.web

[Doug McKenna]

Karl -

Okay, I now understand that |...| is not the same as typewriter font in a WEB file.  But, I think my objection still stands.

The webman.pdf file Shreevatasa pointed to, in several places (p.5, par.2, or p.9, sec.4(b)) says that what's between two vertical bars is "Pascal text" in constradistinction to TeX text.  In other words, whatever is between | and | is a quote of some kind intended to be distinguished from its surrounding typesetting in some standardized way.  Typically, it's a non-reserved Pascal variable name, presented by weave's typeset output in (math?) italics in the typeset version of the algorithm.

But weave doesn't create a typeset version of Pascal code, it converts portions to mathematical symbols, per the interests of its author and intended audience.  For instance, weave replaces the Pascal keywords "and" and "or" with their logical math symbols ∧ and ∨ in conditional expressions.  Weave creates a typeset algorithm that is partially Pascal, and partially math/comp sci. formalism.  And weave replaces the WEB token '==' with an equivalence sign in the places where the desire is to denote a mathematical operator (append the following code to this module name) in the WEB language.  That symbol replacement also accomplishes the same purposes as other subsitutions: to mathematize the presentation of an algorithm first codified in ASCII WEB text.

The problem is that in the case where within a module name there is a quoted *and* ||ed pair of characters, e.g., `|==|', and it's referring to part of a byte parsing algorithm for a computer language (WEB), those two characters are input to the parser being documented, not the algorithm itself.  They are data, not code.

Is not the entire point of documenting a program to teach a human what the code is doing with its input data to create some output?  In documentation, one should refer to the input data by what it is and looks like (the user's mental model, which is text in the language called WEB), not what it will look like later on when typeset by one particular program.

weave calls a single tokenizing routine, get_next, which in turn appears to blindly convert all instances of '==' into an internal equivalence sign token (see section 97).  That is correct nearly all of the time, *except* in the self-referential case when '==' is being quoted in the WEB code to indicate to a human that it is actually referring to two sequential ASCII bytes in the input, and not an equivalence sign, which never occurs in the input data.

I am wondering whether changing it to `|=@&=|' would be a correct fix, without claiming it's an overkill bug with weave.  But I'm not very familiar with where the WEB token joiner command |@&| is legal to use, or even if legal, whether it would do the trick.

Anyway, I understand it's a molehill not a mountain, and that inertia beats a pair :-), but it still strikes me as incorrect.  So, I would like to know from any cogniscenti what my wrong-tree-barking is.


Doug McKenna


----- Original Message -----
From: "Karl Berry" <karl at freefriends.org>
To: "doug" <doug at mathemaesthetics.com>, "tex-k" <tex-k at tug.org>
Sent: Thursday, March 26, 2020 4:48:25 PM
Subject: Re: [tex-k] Module name typesetting bug in either tangle.web or weave.web

Does Pascal have a single-char equivalence operator ''œôù¡'?

As you say, of course not, but that's not the point. As Shreevatasa
says:

  when the module name contains |(#) ==| then the way it has been
  typeset by WEAVE matches that documentation, because that is how the
  equivalent Pascal code would be typeset by WEAVE.

That is, what's inside |...| in .web is not verbatim typewriter, but "as
weave would do it". So it's operating as intended, as far as I can see also.

I guess you're arguing that Knuth should use literal text when writing
about WEB command sequences in module names, etc., within tangle and
weave themselves. (Again, as Shreevatsa said, something like "\.{(\#)
==}".) I don't disagree. However, I am extremely doubtful that he would
be interested in changing it at this late date. But I could ask my
cohorts in vetting reports what they think, if you want. --thanks, karl.