jedcn.com

Notes in Passing

Emacs-setup

Overview

I am happy to have finished the first draft of my emacs configuration! It is rudimentary, but I am proud of it all the same. The configuration, and a written description of what is included are available in PDF and HTML and elisp.

Background

I had been looking for an excuse to wander around emacs, and the opportunity arose recently as part of moving my config to a new laptop. Rather than wholesale copy my old config, I was inspired to create a new one by this advice:

As an Emacs user, you’re going to have to get comfortable seeking out new pieces of elisp, bringing them in, configuring them, and eventually writing your own. The Starter Kit can help this process by giving hints as to where to start and what to look for, but constructing a solid configuration is ultimately a personal journey for which you must take the first steps.

– technomancy, Emacs Starter Kit, v3

Looking to take my “first steps,” and with my interest sparked in Knuth’s Literate Programming by Sacha Chua, I set off to write a coherent prose description of my elisp config. The end result is my emacs-setup, and the ability to generate a description of my config as well as just the pure elisp.

Goals

I set out to make a configuration that was:

  • Beautiful: The literate programming facilities in emacs allowed me to rely on the LaTeX typesetting system and this meant the end goal could be a nice looking PDF.
  • Well Documented: I am not comfortable with elisp, and I don’t spend that much time hacking on my config. Thorough documentation enables me to more quickly get back into context when I return in the future.

Combining these two, my emphasis was on strong documentation and beautiful typesetting from the start and as a top priority. I suspect Beautiful and Well Documented would be the natural result of most Literate Programming attempts. However, additional goals were to make the configuration:

  • Organized: The system I am using allows my configuration to be broken down into discrete files. Each file has a distinct purpose. This is similar to the themes that Zach Holman espouses with his dotfiles.
  • Reproducible: I wanted a system where I could run an rm -rf ~/.emacs.d without flinching and reliably be back to where I was before the rm just a few moments later. This is inspired by working with vagrant and every-so-often testing your configuration management setup by doing a vagrant destroy; vagrant up.
  • Easily Tested: I wanted to work with a system that allowed me to have distinct installations living on the same machine. This is closely related to reproducibility: if I can easily work with a new version of my configuration at /tmp/emacs-test, then I can be confident in deleting ~/.emacs.d.

Reproducible and Easily Tested are not difficult to achieve with emacs. The hardest part was having the discipline, from an early stage, to actively delete my ~/.emacs.d several times a day. I admit, the first time I just did a mv ~/.emacs.d ~/.emacs.d-please-work, but it was pleasant to get to a point where I could delete and re-create with ease.

In Closing

This was the first literate program that I wrote, and I enjoyed doing it. I think I have a system that I understand, that I can maintain, and that I can extend. Having written this up, I’m off to go watch some emacsrocks.com or read up on some emacsredux.com or learn more about elisp via emacsbites.com.

Before I close the chapter on this post, I would be remiss if I didn’t at least point out that Babel and Org-mode, the parts of emacs that enable literate programming, are a real delight to work with! If you are thinking of treading this path, be sure to check out Schulte’s A Multi-Language Computing Environment for Literate Programming and Reproducible Research.

Resources