i'm having a side-debate, not on this list, with someone about the use of tex and noweb as opposed to another tool, like javadoc. i think it's worth repeating my portion of the discussion here as it goes to the 30 year horizon issue and my basic motivation to rewrite axiom in pamphlets.
for the purposes of understanding this note (since i can't share the original without permission) just consider this as a reply to the question "why not use javadoc" (insert your favorite pseudo-markup language) ================================================================== well, it's "ok", i guess. the key flaw, in my opinion, is that it still makes the act of programming the main task whereas literate programming is a complete change of mindset making the creation of the document (as opposed to the documentation) the primary task. this approach has the same flaw as javadoc. the comments are placed in structured places and nicely formatted. unfortunately they are just that, "comments on the program". it's hard to explain the difference if you don't see it. in literate programming you're writing for people. in this kind of documentation you're writing for the machine and commenting about it to people. of course, if your target audience is another programmer like myself then it's probably adequate. at the technical level i'd have to ask why you'd want to settle for a simple hack when you can have the full power of tex available. it's like settling for basic when you can have lisp. if you're just going to document a program one time then "basic-like" ability is fine. if you're going to change your viewpoint to become a literate programmer then "basic-like" capabilities are extremely limiting. t _______________________________________________ Axiom-developer mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/axiom-developer
