chainsawriot

Advent of emacs #3: How I do literate configuration in emacs

Posted on Dec 3, 2022 by Chung-hong Chan

On day 1, I talked about use-package. For using use-package, one needs to relaunch emacs to “refresh” the configuration, install emacs packages and stuffs. But how do I relaunch emacs?

Well, let’s dive into how I do configuration in emacs first. There are 4 layers: literate programming, literate configuration, tangle, and reload.

Literate programming

Before I talk about literate configuration, it is better to talk about literate programming first. Donald Knuth is the pioneer of this programming paradigm. I quote from his website:

“Literate programming is a methodology that combines a programming language with a documentation language, thereby making programs more robust, more portable, more easily maintained, and arguably more fun to write than programs that are written only in a high-level language.”

The original system by Knuth (1984) is called web. It combines \(\TeX\) (a documentation language) with Pascal (a programming language). One can use \(\TeX\) to describe what’s going on in the Pascal code. The web system has two functions: tangle to extract all the Pascal code; and weave to extract all the \(\TeX\).

web in action. Source: Knuth (1984)

I would say, this paradigm is actually very popular in the data science community, although the community has the Rumpelstiltskin problem. Jupyter Notebook is a literate programming system. Other examples are Sweave, odfWeave, Pweave, knitr, Scribble, Quarto, and of course, Org Mode.

Org mode is a built-in emacs package. Org Mode is used by emacs users for basically all the things: from tracking their TODOs to running the International Space Station (This is a joke. ISS is probably not running on Org Mode). But Org Mode without the literate programming layer is just an outliner. Carsten Dominik, the creator of Org Mode, has a paper in Journal of Statistical Software on how to use Org Mode to write reproducible papers. The idea, similar to Knuth’s original literate programming idea, is to write the paper in an Org file, mix it with R. The Org file is sweaved to \(\LaTeX\) with all R code executed to generate numbers, figures, and tables.

Literate programming with Org

Okay, everyone is entitled to have an opinion. Here is my opinion: To put it lightly, I have mixed feelings with Org Mode for writing papers with literate programming. I didn’t and don’t writing my papers with Org mode ¹. All of them are either in markdown (either RMarkdown or increasingly more often, Quarto) or raw \(\LaTeX\). I have actually written about the status of my paper writing previously. Using markdown is odd enough already in my field. I have exactly one collaborator, Nate TeBluthuis, who uses emacs. His preferred method is \(\LaTeX\). And I interviewed him about the idea of writing a paper with Org Mode together. His reaction is: “Why not quarto via markdown or restructured text instead?”

I am also not a big fan of certain Org markups, especially the link syntax. I consider markdown a bit easier to read. Also, I like YAML for metadata. But that can well be my prejudice.

#+Title: My opinion

* Hello

[[http://www.chainsawriot.com][this website]] is /boring/!

---
title: "My opinion"
---

# Hello

[this website](http://www.chainsawriot.com) is *boring*!

But for literate configuration, I have a completely different opinion.

Literate configuration

I use Org mode exclusively for literate configuration. The idea is almost the same as literate programming. For emacs, the configuration language is emacs lisp and that is actually a programming language. So you can use the same literate programming technique to do configuration. And that’s what we call literate configuration: combine a configuration language (emacs lisp) with a documentation language (Org). ²

The result is actually quite nice. My configuration file is on Github and Github can render the Org file nicely.

The idea is to have emacs lisp code blocks mixed in an Org file, like this:

* Packages recommended by chainsawriot

In his [[https://chainsawriot.com/postmannheim/2022/12/01/aoe1.html][blog post]], he recommends these packages.

#+BEGIN_SRC emacs-lisp
(use-package magit)
(use-package quarto-mode)
(use-package rust-mode)
#+END_SRC

So now, I have a nice looking, nicely documented configuration file. But how to use it? It goes back to Donald Knuth.

Tangle

The idea is to tangle (see above) my Org configuration file ³ to a stand-alone file with all the emacs lisp code (e.g. “.emacs”) and then use that file as my configuration file. The documentation of Org mode has more detail. But the general idea is to have a header to tell Org mode to tangle my Org configuration file to a specific location.

#+Title: Emacs Configuration
#+PROPERTY: header-args :tangle .emacs

Then I tangle it by M-x org-babel-tangle (or C-c C-v t, but see Day 2). I have a “.emacs” file in the same directory as my Org configuration file (“~/dev/dotfiles”). I can symlink that point “~/dev/dotfiles/.emacs” to “~/.emacs”. Then I have my actual configuration file at “~/.emacs”.

Reload

Now after the great detour, we can finally answer the question at the very beginning. But how do I relaunch emacs?

If I just need to relaunch emacs to have the new configuration file to take effect, I don’t need to relaunch emacs. For many situations, I can just load my new configuration file by M-x load-file and then point to my “~/.emacs”.

But what I really want to do, is to modify my Org configuration file and then activate the new configuration. I do that by writing a bit of emacs lisp.

(defun refresh-emacs ()
  (interactive)
  (org-babel-tangle-file "~/dev/dotfiles/emacs.org")
  (load-file "~/dev/dotfiles/.emacs"))
(global-set-key (kbd "C-c e") #'refresh-emacs)

The above code snippet does two things: 1) it creates a new [interactive] command called refresh-emacs, which tangles my Org configuration file, and then load my “.emacs”, 2) bind C-c e to that command. Punkt.

So, after editing my Org configuration file, I press C-c e (of course, I can also press M-x refresh-emacs. But C-c e has been in my muscle memory already). Then I have my new configuration activated.

Today’s post is driven by a fundamental question of how do I relaunch emacs. But what about an even more fundamental question: How do I launch emacs?

Let’s talk it tomorrow.

For a short time, I wrote some blog posts with Org as a deliberate practice. But this blog, running on Jekyll, needs markdown files. Some I needed to convert the written Org files to markdown files anyway. After the deliberate practice, I quickly switched back to markdown. ↩
Actually, literate configuration is not limited to emacs and emacs lisp. You can use Org to do literate configuration for many programs, e.g. your shell (sh), npm (json, which is just javascript), even programs configure using non-programming languages such as cargo (TOML). ↩
Another reason I use Org exclusively for literate configuration is that it follows Donald Knuth’s original terminology. One can do the same thing with RMarkdown and knitr. But who on earth, except experienced knitters (those who really really knit with two knitting needles), knows what purl means? Actually, knit is kind-of bad too. But to be fair, the figurative usage of fabric making terms (weave and tangle) by Knuth is not a good idea from the very beginning. ↩