Re: [Axiom-developer] Books versus "Tunneling"

[daly]

Lawrence,

I copied portions of your email to the mailing list along with my
reply. I hope you don't mind.

>I just watched your talk "Literate Programming in the Large" on YouTube.
>I've been investigating literate programming for a bit now, and I've come
>up with a term for non-literate programming: I call it "tunneling." Imagine
>you're a programmer doing your regular programming thing, writing code all
>the live-long day -- and not doing it in any sort of literate way. I say
>that's the same as some mole or miner digging a tunnel. Either the tunnel
>collapses right behind the mindless digger diggings -- or the software is
>actually used and the tunnel doesn't collapse right away, i.e., there's
>traffic in the tunnel. For example, Windows XP is a big, wide tunnel . . .
>that is now beginning to rapidly collapse. Soon enough there will maybe be
>a depression in the ground. "XP was down there." So yes, eventually all
>non-literate software is just so much tunneling that eventually collapses.
>You might argue that "open source" software is not such a tunnel. Maybe.
>But who reads code besides a very rare few? And like you said in your talk,
>code is notoriously difficult to fathom, especially if some "153" crops up.

Actually, you're the second quote on Axiom's documentation page. See
http://axiom-developer.org/axiom-website/documentation.html




>A well-written book, on the other hand, is at the very least a dialogue
>with yourself. Consider what I've done in the past: SQL database. I
>typically would crank around with SQL snippets until I got the database
>where I wanted it, or some output/report generated. But all the steps I had
>taken were lost! Better it would have been if I had been typing an "SQL
>blog" with the SQL code embedded in the text where I describe my process.
>"Dear diary. . ."

I don't know if a diary is the best analogy. The best book I've seen
so far is Pharr and Humphreys' "Physically Based Rendering". It contains
all the source code, properly explains the theory, and is exceptionally
well cross-referenced and indexed. The BOOK won an academy award. If 
you haven't seen it, buy it. Believe me, you'll be amazed.

I have to say, they have really "raised the bar" of what I expect a
good literate program to be. They explain the theory, show the math,
and have numerous diagrams. Axiom has a new standard of excellence.

If Axiom were documented as well as the Pharr/Humphreys book I am
certain that it would be used to teach computational mathematics at
both undergraduate and graduate levels. I can even see a sub-department
of "computational mathematics". There is, of course, the minor detail
of actually documenting the system :-)

Greg Humphreys, one of the authors, and Paul C. Agnostopoulos, the
author of zzTek, which is the tool used, have both given me the
tooling they used to create the book. I hope to use at least some of
it in Axiom. Paul formats books professionally (windfall.com).






>I so much agree with you about literate programming. I don't get much
>buy-in; many think I'm just a crackpot. Alas, but I think it's the real
>wave of the future. A book is meant to be read. Coding is just tunneling.
>Think of all the ga-zillions of lines of code that is buried in all those
>tunnels!

Yeah. There is a saying in physics. "New theories are accepted once the
previous generation dies". John Kitchin at CMU is teaching the new
generation to write literate programs. Once everyone over 30 dies we
can flush all the non-literate, abandoned piles of code in github,
sourceforge, savannah, etc. and get on with the business of
communication.

At least that's my theory and I'm sticking to it :-)





>Two questions: Have you ever seen the outline style Buckminster Fuller used
>in "Synergetics?" Each outline point makes fairly self-contained statement.
>Here's the table of contents:

No, I haven't seen that book. I'll put it on the queue. Thanks.





>And, have you seen Emacs org-mode? It has a built-in literate capability.

I sat in on Kitchin's class where he is teaching students using literate
programming. He is using org-mode. 

It was really interesting in that NOBODY was taking notes. Not a single
pen or piece of paper anywhere. No typing on their laptops. John taught
from his emacs buffer, displayed on an overhead. Everything he taught
was in the buffer. He could execute code, update tables, show graphs.
He could edit changes into the document based on student questions.

At the end of class, all students had the latest set of notes and
all of the executable code already on their laptops. He is working to
spread this kind of teaching across all of the compsci, math, chemE,
and other departments. Frankly, I think it changes the game but I'm
already a convert.



>Also, I'm using Ubuntu and I see there is an "axiom" and an "open-axiom" in
>the package manager. Which do I want? Or should I just grab it from the
>site?

Axiom is this project. Executables are available at 
http://axiom-developer.org/axiom-website/download.html

If you want to compile and/or develop Axiom system code there are
instructions of which packages to apt-get.

Tim Daly