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 _______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org https://lists.nongnu.org/mailman/listinfo/axiom-developer