[Axiom-developer] [Literate Programming] (new)

[billpage]

Changes http://wiki.axiom-developer.org/LiterateProgramming/diff
--
The standard form for all Axiom programs and documentation is
the noweb literate programming extension of LaTeX (called
"pamphlet files" in Axiom terminology). Pamphlet files contain
both documentation and the program code itself. This format
is used for all internal Axiom coding and the entire Algebra
library. It is expected that new Algebra that is intended by
it's author to be shared with other Axiom users will also be
prepared in pamphlet format.

References and Quotes

  noweb home page --
      http://www.eecs.harvard.edu/~nr/noweb

  Single page summary -- "pdf":/public/onepage.pdf
      from http://www.eecs.harvard.edu/~nr/noweb/onepage.ps
                       
  Some examples --
      http://www.eecs.harvard.edu/~nr/noweb/examples/index.html

>From http://www.literateprogramming.com:

Donald Knuth:

"The practitioner of literate programming can be regarded as an
essayist, whose main concern is with exposition and excellence
of style. Such an author, with thesaurus in hand, chooses the
names of variables carefully and explains what each variable
means. He or she strives for a program that is comprehensible
because its concepts have been introduced in an order that is
best for human understanding, using a mixture of formal and
informal methods that reinforce each other."

Ross Williams:

"A traditional computer program consists of a text file containing
program code. Scattered in amongst the program code are comments
which describe the various parts of the code.

In literate programming the emphasis is reversed. Instead of
writing code containing documentation, the literate programmer
writes documentation containing code. No longer does the English
commentary injected into a program have to be hidden in comment
delimiters at the top of the file, or under procedure headings,
or at the end of lines. Instead, it is wrenched into the daylight
and made the main focus. The "program" then becomes primarily a
document directed at humans, with the code being herded between
"code delimiters" from where it can be extracted and shuffled
out sideways to the language system by literate programming
tools."

Historical sketch

  http://www.vivtek.com/litprog.html

The term literate programming, and the original literate
programming system (WEB) which implemented the concept, were
both the creation of Donald Knuth, one of the most literate
programmers the world has ever known. Knuth, of course, is
the author of "The Art of Computer Programming", the TeX
typesetting system, and other works of the programming art.
It was Knuth's intention to provide a system of programming
by which the programmer could typeset his or her work in book
or article form, so that each choice of implementation, each
algorithm, was clearly explained and justified. The resulting
work of art would then stand as the quintessential definition
of a solution for the problem it addressed.

Knuth used and developed this system while writing TeX and
Metafont, and the resulting two books of code/documentation
remain the most readable and usable collections of code I have
ever seen. TeX, of course, is the standard of typesetting software
in the academic world (usually in its LaTeX incarnation, which
runs as a macro package on basic TeX), and has been for nearly
twenty years. Twenty years for a software package! Only Unix
has comparable staying power.

Literate programming, however, is not a mainstream technique.
Those who use literate programming tools often wonder why not.
There have been no studies done of which I am aware, but the
basic shortcoming of literate programming is that it is difficult
to write a literate program quickly. Yes, once it is written,
it is impeccably documented, easily debugged (in those cases
where it isn't already provably correct), simply maintained
by the original author and others, and in general simply has
a far higher quality in every respect than an "illiterate"
program. But it takes longer to see results.

--
forwarded from http://wiki.axiom-developer.org/address@hidden