Initial Impressions using Org-Babel for Literate Programming

2018-09-21

I thought I'd break my year long radio static and talk about my brief encounters writing a literate program inside of org-babel, and compare it to my experiences working with CWEB.

For those who do not know, org-babel is a system built on top org-mode, which is built on top of emacs.

Org-babel is an environment that is mainly designed to allow one to write and execute code snippets inside of an org-mode document. Org-babel can also be turned into a literate programming environment. It was this aspect that I wanted to explore.

For reference, I'm pretty new to emacs, org, and org-mode (about 8 months now). Literate programming is something I have bit more experience in. Over the past 2 years, I've written a handful of literate programs in C using CWEB. A few of these are open source.

CWEB and WEB are without a doubt the gold standards for what literate programming environments should be like.

The Program

Unfortunately, this is something I cannot show because it's related to work. I will say that the program was a small offline analysis utility written in C with 274 significant lines of code.

The goods

easy setup

Org-mode is nice to learn because it is very well documented, and you do not need to learn much to be productive. Org-babel was the exact same way, which made things very nice. I myself found most of what I needed on the org-babel introductory page on the org-mode website.

Org-babel lives inside of org-mode, so it was easy to build on top of what I already know.

Great editor integration

Because it basically extra features for org-mode, org-babel has some pretty amazing editor integration inside of emacs. This meant I could use useful org-mode tricks things like section folding, TODOs, hyperlinks, and lists. In addition, syntax highlighting was enabled for the code blocks, which made readability very nice. It was very warmly welcomed level of interactivity.

CWEB, on the other hand, has no fancy integrations or syntax highlighting, which could make navigation a real drag on larger documents. I actually had better luck looking at the rendered PDF most times (which I suppose was the intent of CWEB in the first place, but still).

very pretty HTML output

Org-babel "weaves" documents into a number of different formats using the the org-mode export features, HTML being one of the backends. The HTML content includes codeblocks with syntax highlighting which look really nice!

I really enjoyed being able to read documents using a web browser instead of a PDF reader. It felt nicer, but that's no surprise since HTML content is optimized to be read on a screen, while TeX generated PDF content is optimized to read on printed paper.

Github Integration

Github has support for reading org-mode files. It was super cool to be able to send my coworkers links to my org file and have them see the HTML output without needing to install anything.

The Bads

ugly syntax

Let's be clear, org syntax is simple and clear. What I'm referring to are the clunky extension codes jammed for the org-babel functionality.

This is the most minimal way you can make a named codeblock in org-babel

 #+NAME: hello_world
 #+BEGIN_SRC c
 #include <stdio.h>

 int main(int argc, char *argv[])
 {
     printf("Hello world\n");
     return 0;
 }
 #+END_SRC

By comparison, here is how you'd do it in CWEB:

 @<hello_world@>=
 #include <stdio.h>

 int main(int argc, char *argv[])
 {
     printf("Hello world\n");
     return 0;
 }

You see how much better that is? Way less typing required CWEB, and the syntax is more visual.

With org-babel, I learned that you can actually get emacs to type some template code for you by typing "

No debugging line numbers

Org-tangle doesn't seem to have any way to insert line directives inside of tangled C code. This makes debugging a generated programming very painful. Instead of the compiler telling you the line number of the code block in the org-mode file, it tells you the line number of generated code. That means opening up the C code to find the line in question, then somehow tracing it to whereever it is on the org-mode file. Really frustrating.

Slow Tangling

This one is the dealbreaker for me. Generating code with org-tangle is unbearably slow. It took a good 10 seconds to generate my tiny ~300 line program. This seemed to get noticeably slower as my program grew. Delays like this made adjustments quite tedious.

Conclusion

Org-mode has great potential for being a great tool for literate programming, even with some of the clunky syntax. As it stands now, org-babel is too inefficient to be useful for anything more than generating small scripts.

I'm still enthusiastic about the idea of using org-mode for building literate programs in C, and may build some handrolled parsers for faster execution.