[pdftex] Re: TeX and friends and literate programming (was Re: [pdftex] pdftex compression -- proposed addition to manual)

[M. Wroth]

At 04:16 PM 9/7/01 -0400, Ed L Cashin wrote:
>"M. Wroth" <mark at astrid.upland.ca.us> writes:
> > One of the *reasons* I'm a believer in literate programming is that
> > it both gives good facilities for and strongly encourages good
> > commenting.  Very few literate programs live up to Knuth's standard
> > of being enjoyable essays in their own right.  But they seem to get
> > better comments than illiterate* programs.
>
>I was very excited about literate programming when I first heard about
>it, because I respect Don Knuth so much and because TeX is great
>software.
>
>However, when I learned specifics on how it works, I noticed that the
>things that it does can be done more succinctly in the code itself.

I'd be the first to admit that there are no literate programming 
documentation / coding languages that combine the factors that I'd really 
like to see in a tool.  Programming languages have advanced in this regard 
since I learned to program, and there are some nice features in various 
languages (I like the docstrings in Emacs LISP, for example).

I would also freely admit that using literate programming is no substitute 
for appropriate choices in variable names, function names and scope, and so 
on (and I think Knuth would agree, if I recall the articles he wrote on the 
subject correctly).

However, I believe that using literate programming tools in addition to 
such techniques can help the maintainability of a piece of code 
significantly. LP tools provide additional facilities for explaining what 
is being done -- they don't have to take away from the inherent readability 
of the code (although they can be abused to do so).
[...]

>While Knuth's code can create a nice book to read all the way through,
>it isn't the kind of code you can understand at a glance.

I doubt very strongly that any method will allow someone to completely 
understand a program that does what TeX does at a glance -- the overall 
logical structure of what needs to be done is too complex.

That's different than saying that individual snippets of code can or cannot 
be understood quickly and easily.  I find Knuth's code difficult to follow, 
at least at times.  But it's not at all clear that I'd find it easier to 
follow if it was "plain" source, regardless  of what other choices of 
naming and scoping were made -- he apparently did a lot of work in TeX to 
make it portable and efficient.  That tends to conflict with easy to 
understand and modify.

>   And from
>what I hear it's not too easy to modify or extend.  The reason it's
>successful is that it's so wonderfully efficient, effective, and
>bugfree.  But I'd rather see a future with readable code than literate
>programs.

I'd like to see a future where appropriate documentation, targeted at the 
intended human audience(s), is as much a part of writing code as the 
computer itself is.  I don't view that as a choice between readable code 
and literate programs -- the two aspects of writing code are complementary, 
not competitive.

But in the context of this list, what are you suggesting?  I have suggested 
that going to a literate programming tool would add capability in 
documenting the pdftex code for better maintainability, and that this would 
be a good thing. Possibly not the best thing -- but a good thing.

I debated setting up a couple of straw men for your suggestions, but 
decided that such rhetoric would be counterproductive.  What do you think 
the maintainers (and developers) of pdftex should do?

Mark B. Wroth
<mark at astrid.upland.ca.us>

--- StripMime Report -- processed MIME parts ---
multipart/alternative
  text/plain (text body -- kept)
  text/html
---