Literate [Clojure] Programming: Tangle All in Org-mode

Frederick Giasson

This blog post is the fifth of a series of blog posts about Literate [Clojure] Programming in Org-mode where I explain how I develop my [Clojure] applications using literate programming concepts and principles.

This new blog post introduce a tool that is often necessary when developing literate applications using Org-mode: the tangle all script. As I explained in a previous blog post, doing literate programming is often like writing: you write something, you review and update it… often. This means that you may end-up changing multiple files in your Org-mode project. Depending how you configured you Emacs environment and Org-mode, you may have missed to tangle a file you changed that may cause issues down the road. This is the situation I will cover in this post.

This series of blog posts about literate [Clojure] programming in Org-mode is composed of the following articles:

  1. Configuring Emacs for Org-mode
  2. Project folder structure
  3. Anatomy of a Org-mode file
  4. Tangling all project files (this post)
  5. Publishing documentation in multiple formats
  6. Unit Testing

Continue reading “Literate [Clojure] Programming: Tangle All in Org-mode” →

Literate [Clojure] Programming Using Org-mode

Frederick Giasson

Literate Programming is a great way to write computer software, particularly in fields like data science where data processing workflows are complex and often need much background information. I started to write about Literate Programming a few months ago, and now it is the time to formalize how I create Literate Programming applications.

This blog post belong to a series of posts about Literate [Clojure] Programming:

  1. Configuring Emacs for Org-mode
  2. Project folder structure (this post)
  3. Anatomy of a Org-mode file
  4. Tangling all project files
  5. Publishing documentation in multiple formats
  6. Unit Testing

Continue reading “Literate [Clojure] Programming Using Org-mode” →

Improving org-babel-clojure

Frederick Giasson

In a previous blog post, I started to play with org-babel-clojure to improve its capabilities such that Clojure gets better integrated into Org-mode for creating notebooks and Literate programs. The first thing I wanted to do is to remove the 20 seconds timeout that was defaulted with the nrepl. That meant that it was not possible to run procedures for longer than 20 seconds before it died with a timeout. Once this was implemented, the next step was to add a new feature to see the underlying process of a code block. Because the nature of my work (extensive work with big datasets), my procedures take time to run (minutes… hours…) and much information [about the process] is output to the terminal. However, in the org-babel-clojure implementation, you had to wait until the code was executed before being able to see the processing. What I did at the time is to add a new :async code block parameter which told org-babel-clojure to output all the output of the nrepl, when it was being processed, in a new window.

That worked like a charm. However, after much interaction with Nicolas Goaziou, one of the core maintainers of Org-mode, it was clear that my implementation was not an asynchronous implementation but really just a live processing output.

At the same time, I did find another major irritant: if an exception was raised in my Clojure code, then nothing was output to Org-mode, it was simply silently dying. The only way to see the exception was to switch to the Clojure major mode (using C-c ') and to rerun the code block.

Continue reading “Improving org-babel-clojure” →

My Optimal GNU Emacs Settings for Developing Clojure (Revised)

Frederick Giasson

It has been 2 years since I last revised my optimal GNU Emacs settings for developing Clojure. Since then, many things have changed in the Cider/Emacs ecosystem and it is why a revision of these settings is now warranted.

There is one set of settings that I will not discuss in this blog post, and these are all the settings related to Literate Programming using Org-mode. Since much needs to be said about these, they will be the topic of a subsequent blog post that will focus exclusively on that matter.

Continue reading “My Optimal GNU Emacs Settings for Developing Clojure (Revised)” →

Literate Programming and Team Development

Frederick Giasson

I recently wrote a post about how I was using Literate Programming principles in Org-mode to write the unit tests of my applications side-by-side with the code it tests. I got some good feedbacks about the post, however one that particularly caught my eye is a blog post on the Irreal blog which states:

One possible problem with this procedure is if you’re working in a team and not everyone is an Emacs user. Non Emacs users won’t be keen to tangle an Org document to get the code and probably won’t feel comfortable making changes to an Org file. Unless everyone you’re working with is an Emacs user or you’re working alone, this means that Giasson’s workflow will have to be limited to initial development. Still, it’s a powerful technique and well worth experimenting with.

It is not the first time I have read such observation about Literate Programming (and Org-mode & Emacs). This is certainly a right and legitimate concern. Literate Programming is a set of concepts and principles with two actions at its core: weaving (generating human readable version of the application) and tangling (generating the computer code of the application) [a literate document]. The literate document has to comply with some syntax to determine what needs to be weaved and what needs to be tangled. This syntax needs to be implemented in a development environment to be usable. It could be fully integrate (like with Org-mode) or part of a development workflow (like CWEB). It is for this reason that there may be a possible problem: because the way to write a software application is inherently different than how we learned to program and it requires some specific development environments or workflows. This is fine if there is only one developer on the application or only a few that already use the same environment.

Continue reading “Literate Programming and Team Development” →