> 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.
