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

[Ed L Cashin]

"M. Wroth" <mark at astrid.upland.ca.us> writes:

> 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).
> [...]

...
> 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?

In short, I am suggesting that structured code is more descriptive of
the problem, solution, and implementation than English (or any
conversational language) will ever be and that pdftex would be more
flexible, maintainable, and simple if LP were avoided.  

LP mixes code and conversational language in a highly-technical way
that few people have the skill to pull off as program-writer or to
appreciate as program-reader.

-- 
--Ed Cashin                   PGP public key:
  ecashin at terry.uga.edu       http://www.terry.uga.edu/~ecashin/pgp/