Hi, [EMAIL PROTECTED] writes:
>... > As a result of this experience it became clear to me that you need a > deep change of philosophy about documentation and coding in general. > Much more of the human aspects of the problem need to be captured and > preserved if code is to live and be useful 30 years from now. > > Knuth attacked this problem years ago with his Web project. The basic > ideas were that you "write for humans", not "code for machines". To do > that you construct a "literate program", that is, a file that contains > both documentation and data. I'm a big fan of literate programming. > Axiom has been completely rewritten as literate programs. There are no > lisp, C, Makefile, spad, aldor, include, etc. files. Everything is now > a document and the Makefiles automatically extract the programs. > > My experience with this has been good so far and I've finally made > the transition of writing for humans rather than machines. I can see > the huge difference it makes when I open a "program" from last year > and can easily understand and modify it. I would like to hear your opinion regarding the debugging process of literate programs. On one hand, we have the interactive nature of the development process that we can adopt in Common Lisp. On the other hand, we have the typical "batch" development process of literate programs (that must be processed by tangle and weave). My problem is the combination of both processes. 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? Best regards, António Leitão. _______________________________________________ Gardeners mailing list [email protected] http://www.lispniks.com/mailman/listinfo/gardeners
