Re: http://www-cs-faculty. stanford.edu/∼uno/programs/tcalc.w.gz

[Doug McKenna]

Andreas wrote:

>| I can't say much about the coding quality of TeX, the program,
[snip]
>| but other Knuthian codes -- including SGB and MMIX, though both
>| written in CWEB and published in dead tree form -- leave a lot to wish
>| for in terms of "industrial strength".  ;o)

I've always thought of TeX as a glorified assembly language program, up-codified into a very simplistic structured language Pascal, and then chopped up into pieces by virtue of WEB (and the aid of its rudimentary macro system) and subsequent change files.

Knuth's focus has always been on algorithms (especially reducing time/space redundancy to a minimum), not software.  But the constraints on designing and presenting software are different from the constraints re algorithms.

I have never thought that the WEB/CWEB system is about documenting software as much as it's about converting a set of notes and pseudocode into a document that presents only *the author's* notes and pseudocode in a (to my eye chaotically) typeset form attuned to mathematical computer science publishing needs.  It's good for DEK and maybe a few others (and of course it excludes all who don't know TeX).  Woven files have never been easy for me to understand, and to some extent it's due to the typographic choices as much as anything else.

It is a theorem that when it comes to documenting code (just like editing lots of other writing), the author is always the best and worst person to do so.  Regardless, the increasingly faint drumbeat of people saying that weaving a (C)WEB file and typesetting it with TeX creates "the best" way to document a program has never been supported by any actual study of what the best way to document a program might be, as far as I know.  That is something that I'm super-interested in right now, given that I've taken it upon myself to re-implement from scratch some of these same programs.

With all the eTeX changes applied, TeX the program has 322 global variables added into its @<Globals@> module, in a completely unorganized way.  That's enough to fry the brain of any software maintainer, and it seriously hinders being able to use a visual debugger on the running program.  Worse, the (C)WEB style of programming fosters expositionally treating most local variables in scraps of code into essentially more global variables.  It is one of the greatest impediments to understanding code written in (C)WEB.

As someone who has spent a huge amount of time on creating my own semi-literate, LaTeX-based documentation system for my own C code, I am forced to say that there (still) is no perfect solution.

Doug McKenna
Mathemaesthetics, Inc.