[Axiom-developer] Re: Literate Clojure - a good lead ...

[Tim Daly]

Antony Blakey wrote:
> On 21/07/2010, at 10:29 PM, Tim Daly wrote:
>
>   
> > The PLT Scheme mechanism mentioned above is a good idea
> > but it has a niche quality to it.
> >
> > Latex is an industry standard publication language. Many
> > books and technical papers, especially in mathematics,
> > use it. Some conferences require it. All publishers support
> > it and it is widely used.
> >     
>
> Going from the PLT form to Latex is possible. Why use Latex when you can use 
> Clojure?

The essence of literate programming is writing for humans.
My main example is "Lisp In Small Pieces" which is a full lisp with
a compiler written as a readable book. So the primary focus is the
text, not the code. "Clojure in Small Pieces" would be fantastic.

It is always possible to go from a "program documentation" language
to latex since latex is just a document markup language. The problem is
the mindset that this is "program documentation" rather than a book
for humans to read, cover to cover. Wouldn't it be nice to read a book
that, oh-by-the-way, has the actual source code not only explained but
motivated?

I've been doing literate programming in Axiom for about 10 years now.
I've looked at a couple dozen possible tools and techniques ranging from
"use good variable names makes the code self-documenting" to
"embed the code in a special purpose tool". Programmers tend to like
things that "work from the code and comments" so they don't have to
write actual prose (e.g. javadoc, doxygen, etc). However, writing for
humans requires a completely different mindset, at least in my experience.

> The essence of the PLT model is the language integration that allows symbol 
> resolution by reusing the language mechanism for the documentation.
>   
"Language integration" is a false goal. It is technically possible to
call functions in any language from latex but unnecessary in general.
It is technically possible to generate latex from any language.

Symbol resolution is also rarely an issue in literate programs.
Your prose is intended to explain "why" a code chunks exists,
not "how" a code chunk works. If you explain the problem you
are trying to solve and the issues of various approaches you considered
then I can usually understand the solution.

Axiom has all of the function and variable definitions and uses
cross-referenced in the index. Making these references hyperlink
in the generated pdf is trivial. Again, the problem is not a question
of technology as in the PLT Scheme approach but one of mindset.

Choosing the right approach matters. It is technically possible to
write clojure code in Microsoft word but utterly painful since MSWord
does not have a programming focus. It is possible to write a book in
PLT Scheme but painful for the same reason.

If your intention is to write a literate program, which as Knuth defined it,
to be a piece of literature, use a tool designed for literature.

I want to see a chapter in a "Clojure in Small Pieces" that explains WHY
Rich chose his data structures, why immutability is important, then why
he chose to use 32-bit wide trees, THEN show me the code. In essence
I want what Rich does not currently write, which is the agony of choice,
the ecstasy of insight, and the tragedy of implementation details. Make
me weep at the beauty of the chosen solution. Literature!

Thus I advocate the primacy of latex over that of the implementation
language magic.

Tim Daly


P.S. The clojure team needs a job opening for "Senior Editor" :-)