root <[EMAIL PROTECTED]> writes:: > (full disclosure: I'm the Axiom Lead Developer and an old > lisper) > > If we choose a "standard" markup language I'd strongly > vote for literate programming using Latex. > [...] > The noweb tool (http://www.eecs.harvard.edu/~nr/noweb) by > Norman Ramsey gives us the ability to combine a high > quality documentation tool (latex) and a high quality > programming language (lisp) with a high quality wiki > implementation (latexwik).
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. 2. LaTeX is hard to read in source form. I had to switch to the rendered PDF just to see what I had written. 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. 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. Lately I've been looking at reStructuredText_ (reST), a markup developed for Python docstrings. I like how easy it is to read the source (this email is valid reST), and how it has a lot of predefined constructs (code blocks, option lists, warnings) for documenting software. It can even generate LaTeX output. I've considered trying to extend reST for Literate Programming. 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. -Stuart .. _reStructuredText: http://docutils.sourceforge.net/rst.html _______________________________________________ Gardeners mailing list [email protected] http://www.lispniks.com/mailman/listinfo/gardeners
