Making init files intelligible

Emacs is massively customisable. These customisations are stored in elisp source files (e.g. ~/.emacs.d/init.el), which are interpreted by emacs on startup. The difficulty is that these files are usually composed of various snippets from a variety of sources, which results in a configuration that can be hard to read and maintain.

So how do we avoid this? You can simply comment the elisp code, but in reality this doesn't scale very well. The same setting gets duplicated in multiple locations, and worse. So instead, we want a hierarchical structure, where there's a correct place for each setting. This means that when you decide to fine tune the behaviour of a particular setting, you know where to look for the current setting.

The magic bullet to make this work is org-mode. This allows creating a structured document, which has code snippets in it. Note that we've reversed the sense of the configuration file here: rather than code with a smattering of comments, we're now talking about a document with a smattering of code. But a document for configuration is only useful if it can be interpreted by emacs. This is where org-babel comes in. This translates the org-mode file and extracts all the code blocks. The documentation includes an example that does exactly what we need. This example init.el translates the document into code on starting up emacs, which is then interpreted by emacs. So the init file is always up to date whenever you restart emacs.

I recommend keeping your ~/.emacs.d/ directory as a git repository, synced to Github. As a bonus, github renders the org-mode file in the same fashion that it renders markdown or jupyter notebooks. If you choose to name the main configuration file README.org, then this is the page that renders as the front page of the repository.

Here's some examples:

• Raw (i.e. unrendered) readme.org - this is the form in which the configuration file is written. Note that org-mode makes this easier to use when opened in emacs rather than a web browser.

• How Github renders the file. Much more readable. Note that this link and the previous link are to a snapshot in time; the current readme.org may have diverged from this.

• An example of how well this scales. This is a link to Sacha Chua's config (of emacs news fame).

• A reminder that you'll need some boilerplate in your ~/.emacs.d/init.el file.