Note: this is historical info. FriCAS sources are just Spad files and Axiom changed its format.

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

https://www.cs.tufts.edu/~nr/noweb/

Single page summary

pdf from https://www.cs.tufts.edu/~nr/noweb/onepage.ps

Some examples

https://www.cs.tufts.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.