[pdftex] Re: TeX and friends and literate programming (was Re: [pdftex]
pdftex compression -- proposed addition to manual)
mark at astrid.upland.ca.us
Mon Sep 10 22:59:24 CEST 2001
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
>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
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
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,
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 ---
text/plain (text body -- kept)
More information about the pdftex