Antonio, > For example, while debugging a Common Lisp literate program, it has > been somewhat difficult to me to be able to jump from the Common Lisp > debugger to the original source (which is in web format) or to quickly > modify that a single source fragment, compile it and test it without > going through the "make" process. I know that this "quick patch" > style is more or less the opposite of what literate programming > promotes but it is effective in many cases and it would be good to be > able to somehow reconcile the two processes. > > I have "solved" my problem by preserving the sources in .lisp files, > writing the text in LaTeX and wrapping the text with the common lisp > comment marks #|- -|#. This allows the sources to be treated as > normal Common Lisp files (so I don't need tangle) and it's only when I > need to regenerate the documentation that I use a "home grown" weave > to produce pure LaTeX files. > > What's your opinion with this issue?
you're using what i call the "javadoc-style" of coding. you write for the machine and then generate documentation for people. the hard part about the transition to literate programming is not the technology but the mindset. changing to the mindset of writing a document which, oh-by-the-way, also includes code, changes the whole way of programming. (sounds like a zen-book title :-) ) one method of working involves a complete rebuild/test/document every 10 lines or so of code. for every few lines of code updated the test cases (which are also part of the documentation) and completely rebuild the whole document. it's very expensive in machine-time but working on a fast processor we don't care. the turnaround time for completely rebuilding the code, testing it, and updating the documentation is just a few dozen seconds at worst. if you feel the need to debug using the intermediate lisp files i'd suggest making smaller and more frequent source changes (i'm down to 10 lines or so). that way you can guess what just broke. using this method you should no longer feel the need to look at the generated lisp code. since the lisp code IS generated as a side-effect of the build process the lisp file exists. you could just start lisp and load this file. there really isn't any magic about literate programming. as to the "homegrown weave" look at noweb. Norman Ramsey has done a nice job with this tool. it's language independent and very robust. it is common to include not only lisp code in the document but also the Makefile and any other shell scripts (all with documentation about their use). if you use a standard tool then anyone can reproduce your program directly from the documentation. for an example pamphlet file look at http://daly.axiom-developer.org/TimothyDaly_files/cmutalk/pages/dhmatrix.spad.pamphlet for the generated code output see http://daly.axiom-developer.org/TimothyDaly_files/cmutalk/pages/dhmatrix.spad for the documentation output see http://daly.axiom-developer.org/TimothyDaly_files/cmutalk/pages/dhmatrix.spad.pdf i just posted a long note to paolo about it on this list. send me questions if it isn't clear. t _______________________________________________ Gardeners mailing list [email protected] http://www.lispniks.com/mailman/listinfo/gardeners
