Optimal Emacs Settings for Org-mode for Literate Programming

For some time I have been interested in using Emacs and Org-mode for developing Clojure in a Literate Programming way. I discussed the basic ideas, some of the benefits of doing so, etc, etc. It is now time to start showing how I am doing this, what are the rules of thumb I created, what is the structure of my programs, etc.

However, before I start writing about any of this, I think the next step is to explain how I configured Org-mode to have a frictionless experience to develop my applications in Literate Programming using Org-mode. Then in a subsequent series of blog posts I will explain how I structured my Clojure project, what is my development workflow, etc.

Note that if you don’t have Emacs setup for Clojure/Cider, I would encourage you to read this other blog post which explains how to setup a Clojure environment in Emacs.

This is the first post of a series of blog posts that will cover the full workflow. I will demonstrate how I do Literate Programming for developing a Clojure application, but exactly the same workflow would work for any other programming language supported by Org-mode (Python, R, etc.). The only thing that is required is to adapt the principles to the project structures in these other languages. The series of blog posts will cover:

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

Continue reading “Optimal Emacs Settings for Org-mode for Literate Programming”

Improving org-babel-clojure

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)

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)”

Creating and Running Unit Tests Directly in Source Files with Org-mode

Developing a computer program is not an easy task. The process needs a constant focus. Any interruption of that process means that time is spent re-focusing on it and errors are more prone to be introduced. The process involves analyzing a problem to solve by executing a series of steps. It involves writing about the problem we are trying to solve and writing about the solution we found to solve it. Finally it involves writing test procedures that can run to make sure that the current state of the implementation of the solution behaves as expected and that expected behavior is not altered by subsequent modifications.

Continue reading “Creating and Running Unit Tests Directly in Source Files with Org-mode”

My Literate Programming Commitment

From now on, I make the commitment that everything new I will produce is literate programming code.

The Open Source Revolution

For about a decade, we are experiencing a kind of Open Source revolution with the rise of Git (and all its free online hosting services such as GitHub, BitBucket and GitLab). At the same time the tech Juggernaut like Google, Microsoft, Facebook, Baidu, Twitter and probably all others are increasing their commitment to release several of their internal projects as open source software. There is also a myriad of young and vibrant communities that get created around new programming languages such as Clojure, Scala, R and many others. More and more code is available to people to look at and for developers to use.

My company Structured Dynamics and I are participants of that movement for more than fifteen years, producing open source software, ontologies, datasets and participating into other open source projects by fixing bugs and adding functionalities.

Continue reading “My Literate Programming Commitment”