Syntactic Sugar

EMACS IS an incredible application, more text interface than editor. Like an old baseball glove, it slowly molds to the user's hand over a period of many years. This is achieved by keeping a .emacs settings file. The user edits this file with all their customizations - snippets of Elisp code which are called by the editor on startup. I have a relatively basic .emacs file, but it still extends my editor in a myriad of useful ways. My .emacs file is like a well traveled passport, with stamps of all the destinations I've been with it. The problem is, it's also a bit of a mess.

I've recently become interested in the concept of literate programming. The basic idea is you write a document containing your thought processes, and explaining what's going on in the code. Crucially, however, the document also contains the code in visible and compilable snippets - you can read the document, as a document, then compile and run the document as code. Those of us familiar with the wonderful Jupyter notebooks in the python world should feel right at home. Handily, I've seen many examples of people writing their .emacs files in org-mode, then using Babel to extract the relevant emacs lisp code and run it seamlessly. Lets jump in.

Firstly, we'll begin by creating a settings.org file, and chucking it somewhere useful. I like to keep my Org files under a "~/org" directory, so I'll be using that. You do you. If you have a preexisting .emacs file, copy the code from that and place it in your new settings.org file. Add the line "#+BEGIN_SRC emacs-lisp" to the very top of the file, and "#+END_SRC" to the very end. Save the file and move your old .emacs file to somewhere new so Emacs can't see it (this is to ensure we know our changes are really working.

Next, edit the file ~/.emacs.d/init.el. If that file does not exist, create it. Just make sure the ~ home directory is the same as the one emacs sees (for example, I change my home directory to one in drop box). In your init.el file, add the following lines:

(require 'org)
(org-babel-load-file
 (expand-file-name "Settings.org"
                   "~/org/"))

Naturally, replacing "~/org/" with whatever directory you saved your settings.org file in. Save init.el, and close Emacs. Re-open emacs and everything should be working as normal. Except there's one crucial difference - your customizations were loaded from an Org file.

Now, we're free to get literate. Just remember that any Elisp code should be bracketed by the '#+BEGIN_SRC emacs-lisp' and '#+END_SRC' statements. You can have multiple such blocks in a file, and you should, i.e:

Expanding on this idea, I can begin to format and organize my .emacs file using Org convention:

There are a few benefits to doing things this way. Firstly, the simple act of organizing things in this way helped me to identify quite a few obsolete areas of my config. Secondly, it makes changes to my settings a lot easier - if something breaks, it's easier to diagnose - simply add a property of :tangle no to a section of the settings file, and that setting will no longer be included in your emacs settings:

The highlighted code means all that visual rubbish will be enabled. Not that I would want to do that.

Finally, because our settings are a Org file, it's easy to make use of Org's export functionalities:

Or using Fabrice Niessen's wonderful org-html-themes:

I've uploaded a copy of my Settings.org, exported to read-the-org here, so you can get an idea of how to set everything out.