--- Stuart Sierra <[EMAIL PROTECTED]> 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 _______________________________________________ Gardeners mailing list [email protected] http://www.lispniks.com/mailman/listinfo/gardeners
