Tim, I'm with you 100% on the mind-blowing greatness of literate programming, but I do have to correct you on org-babel. It is actually a very nicely done LP development system. You write your content as you would a book or article, using sections and subsections, paragraphs, ordered and unordered lists, tables, embedded images, links, and so on. Code is placed within specially delimited blocks that specify the source language (thus triggering the appropriate emacs mode for syntax highlighting) as well as special rules for code and output export. Obviously, code blocks can (and should be) out of order in the Org document so as to enable clear exposition. When you are ready to test out the finished product, org-babel provides built in tangle and weave commands.
I used your homebrew solution on axiom-developer.org a few years ago when I was first getting my feet wet with literate programming. However, org-babel provides several unique advantage IMHO over make+tangle.lisp+latex: 1. Org markup is much simpler and more visually recognizable than LaTeX although anything you can do with LaTeX, you can do in Org mode. This is because you can export an Org file to LaTeX and Org markup syntax allows for inline LaTeX code blocks if you want to do anything that is not already supported by the standard markup. 2. Org mode can export my Literate Program to many, many different formats with a simple keystroke. These include (but are not limited to) HTML, LaTeX, ASCII, and LibreOffice ODF. Thus my woven program can be distributed as a PDF file, Word Document, or webpage. 3. Org mode supports multiple programming languages within a single file. This allows me to chain together in the same document (and thus in the same exposition) a shell script written in Bash, a Python script for generating a graph, and a Clojure program for running a webserver. When I trigger the tangle procedure, each language's code is written out to its own file(s) and run through the correct interpreter or compiler. Amazingly, code blocks in different languages can even be annotated such that they pass values between one another like functions in a Lisp environment. 4. Org supports Live Code Evaluation. By simply placing my cursor (the point in Emacs jargon) within any code block in my Literate Program and pressing C-c C-c, Emacs will trigger an external shell for that language, recursively expand any code block references included within the selected code block (i.e., a local tangling procedure), send the expanded code to the external shell (be it an interpreter or compiler), evalutate the result, and pretty print this result into my LP file in an annotated RESULT block directly after the code block that I evaluated. If I tweak the code and reevaluate it, the RESULT block's contents are updated in place. This provides an in-document multi-language REPL-like experience. Note, of course, that the contents of these RESULT blocks may then be optionally woven into my formatted output, which is particularly useful in explaining the behavior of code with examples or in automatically generating tables or figures for illustrative purposes. There are many more features that Org mode supports that would take...well, the entire Org mode manual to explain. However, these LP features are really quite useful, and I do genuinely think more people interested in LP should give them a try. For more information, please check out the Babel section of the Org Mode manual: http://orgmode.org/worg/org-contrib/babel/intro.html I also HIGHLY recommend the 2012 journal article published on Org Mode's Babel features in the Journal of Statistical Software: *A Multi-Language Computing Environment for Literate Programming and Reproducible Research* by Eric Schulte, Dan Davison, Thomas Dye, Carsten Dominik http://www.jstatsoft.org/v46/i03 As you like to say, Tim... Get Literate! ~Gary On Wednesday, August 7, 2013 8:36:51 PM UTC-4, da...@axiom-developer.org wrote: > > > Recently, I discovered the "story" literate programming tool for > Clojure, > > which I prefer to marginalia: > > https://github.com/jedahu/story > > > > ... (snip) ... > > > > I had never heard of "story", but ran across a mention of it while > looking > > through the issues on marginalia's github site, so I decided to give it > a > > try. It's similar to marginalia, in that it's not true literate > > programming -- it doesn't let you freely order your comments and code > > irrespective of how they appear in the final files, but is a tool for > > extracting long comments written in markdown in order to weave some sort > of > > narrative explanation of why the code is written the way it is. > > The ability to freely order comments and code is actually vital to the > idea of literate programming. The key idea is writing to communicate > ideas to another person. This almost certainly involves reordering > and restructuring code. The machinery needed to support literate > programming is trivial. See > http://axiom-developer.org/axiom-website/litprog.html > > > ... (snip) ... > > > * Tim Daly posted a tool that lets him essentially write Clojure inside > a > > TeX document. Seems to require a very different workflow to use > > effectively. > > Actually it isn't really a change in workflow but a change in mindset. > Literate programming is not documentation, they are different ideas. > > > Right now, I care more about the literate programming side of things, > but > > I'm always interested in learning anything about good documentation > tools > > If you want the full-on Sturm und Drang see my talk at the WriteTheDocs > conference in April (Literate Programming in the Large): > http://www.youtube.com/watch?v=Av0PQDVTP4A > > I gave a similar talk at the Clojure conference a couple years ago. > > > and practices for Clojure. > > For Clojure specific efforts see > http://daly.axiom-developer.org/clojure.pdf (PDF) > http://daly.axiom-developer.org/clojure.pamphlet (source) > > Download the source, follow the one-time instructions which are > clip out and compile the "tangle" C program > clip out the Makefile > > When you type 'make' it will recreate Clojure's Java directory > structure, compile Clojure, run all the test cases, rebuild the PDF, > and put you in the REPL. > > Your workflow is now: > > edit the source (clojure.pamphlet) > loop-forever: > type make > fiddle with the REPL, clip the slime result into the source > write a couple sentences > > You'll soon discover that writing code and writing explanations are > co-equal activities, making the effort to write in a literate style > so much easier and natural. Oh, and you get a pretty book at the end. > Some PDF readers will update when changed so you can watch the book > change as you work. I keep mine running so I can see the final book > after each time I run make. > > Markdown, story, org-babel, javadoc, doxygen, and all of the other > "kinda-sorta-maybe-literatey" efforts miss the point as they try > to elevate "documentation" into what looks like a literate style > but fail to really address the point. > > Really understanding lisp is an "epiphany moment" where you change > from asking "Why would anyone write like this?" to "Why doesn't > everyone write like this?". Literate programming is the same kind > of epiphany event. It takes time but the results are worth it. > > I'll see you on the other side. > > Tim Daly > > > -- -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
