[Gardeners] Literate Programming

[C Y]

--- Stuart Sierra <mail at stuartsierra.com> wrote:

> I've been using Noweb and LaTeX to document my Perl in Lisp
> project.  I'm sorry to say that, despite being a big fan of
> Literate Programming as a concept, I found my first attempt
> to use it very frustrating.  Here are the problems I ran
> into:
> 
> 1. LaTeX does not have standard markup specific to software
>    documentation, such as examples or argument lists.  I had
>    to define new LaTeX commands to get what I wanted.

Hmm.  Would you be interesting in releasing the commands you created as
a LaTeX package?  I know what you mean about the standard LaTeX markup
sometimes being a bit limited - creating packages is the standard
response.
 
> 2. LaTeX is hard to read in source form.  I had to switch to
>    the rendered PDF just to see what I had written.

You mean the markup obscured your text?  Wow.

> 3. Noweb/LaTeX is sub-optimal for generating HTML, which is
>    the primary format in which I read documentation these
>    days.  Noweb's built-in l2h filter is limited, and
>    LaTeX2HTML is a disaster.

I think there are one or two other LaTeX to html tools available, but I
have little experience with them.  What were the problems you
encountered with the current tools?

> 4. Building the code and documentation from the literate
>    source is a complicated, multi-step process.  My Makefile
>    is getting longer than the code itself.

IIRC, the standard routine to build code would be:

notangle all pamphlet files to get raw source code
noweb all pamphlet files to get LaTeX
build all source code as normal code
latex all .tex files as normal LaTeX

I agree it's a bit more complicated than just building code, but surely
the first two steps can be done at the beginning with a few commands?

> I agree completely that Literate Programming is the way to
> go.  I'd just like the process to be easier.  LaTeX's math
> typesetting capabilities make it the clear choice for
> something like Axiom.  I'd be very interested to learn how
> the Axiom developers deal with Noweb/LaTeX on a day-to-day
> basis.

Well, my stuff is simple enough that I just run notangle and noweb by
hand.  I think an advanced Emacs mode might help with a lot of this,
but it could be a while before we have a really good one.

Cheers,
CY

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com