[Axiom-developer] literate programming

[root]

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