I started the post primarily to see if anyone else was using story, and if anyone knew the status of that application, and this has turned more into a discussion about literate programming. That's okay though. I'm very interested in literate programming, and am always looking for a viable toolset for incorporating it into my programming. With that in mind, I'd like to ask some followup questions about the toolchain(s) proposed by Tim and the others:
On Wed, Aug 7, 2013 at 5:36 PM, Tim Daly <d...@axiom-developer.org> wrote: > 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. I'm concerned that the ability to freely order comments and code will not interact well with Clojure's namespaces. With Clojure's namespaces, you can have things with the same name in two different namespaces. Functions local to a namespace are referred to in one way, whereas you need some sort of prefix to refer to one in a different namespace. These prefixes are often aliases, and the aliases may vary from one context to another, for example, in one namespace I may refer to clojure.string as `str` and in another namespace I may refer to it as `string`. What this means is that Clojure code is pretty much unreadable unless you know the context it occurs in, specifically, you need to which namespace it is, know the symbols that were defined above it in the file, and know the aliases of all the namespaces referred to from this namespace. If you freely bounce around from namespace to namespace in the description of your Clojure code, it's going to be very confusing. This suggests to me that a well-organized literate program in Clojure would tend to document one namespace at a time. Within a namespace, Clojure lets you move code around using `declare` in order to achieve a better narrative flow. So as long as you have a tool that lets you specify the ordering of namespaces, and then captures the top-to-bottom narrative flow within the namespace, I think you'll get a nice, comprehensible literate program. Anything more jumbled than that seems likely to be too hard to follow, due to Clojure's use of namespaces. How do you deal with this "lack of context" when you present your code in a way that is completely unrelated to the namespace organization of your files? Actually it isn't really a change in workflow but a change in mindset. > Literate programming is not documentation, they are different ideas. > Here's why I called it a change in workflow -- please correct me if I'm mistaken: Every time the subject of literate programming comes up, I ask one simple question: When you get a stacktrace, is the file/line number information correct? A year or two back when I asked this, you elaborated that for you, this was mostly a non-issue. You said you developed your code by sending over one tiny code block at a time to the REPL, rather than sending a whole file over, and you never used any debugging facilities. I consider that a change in workflow. > > For Clojure specific efforts see > http://daly.axiom-developer.org/clojure.pdf (PDF) > http://daly.axiom-developer.org/clojure.pamphlet (source) > This is a great example of using literate programming to document a program that is complete and stable. Have you successfully used literate programming in a program that is rapidly evolving? Is it true that there's nothing like org-babel for environments other than emacs? To me, the most compelling reason to stick with tools that use regular Clojure files and regular Clojure comments, especially for open source projects, is that it allows for collaboration between people using different Clojure platforms and tools, whereas locking things into a file that can be only be processed by emacs or a unix shell script would limit the pool of contributors. One thing I do like about org-babel code is that it makes it easy to create "live" examples in the docs that actually recompute when the code changes. As far as I can tell, neither your script nor org-babel mode address the third prong of literate programming as defined by Knuth, specifically, the extensive cross-indexing, letting you know not only where functions are defined, but also where defined functions are used. Why do you not consider this to be as essential as, say, the ability to reorder your code? --Mark -- -- 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.
