My init.el isn’t very organized. Partly, that’s because I like having a single file rather than the multitude of special configuration files that many of my Emacs heroes prefer. But even given that it’s a single file, it’s not really organized. I have sections that more or less group functionality but like many Emacs configurations it has grown (some would say metastasized) over the years and accumulated a thick layer of barnacles.
Now Grant Rettke has shamed me even more by publishing his configuration. It’s a wonderful example of literate programming. Others have used Org-mode and Babel for their Emacs configurations but Rettke’s is a marvel. It’s really more of an essay that explains what he’s trying to do, why he chose each configuration item, and even why he didn’t choose others. He has a long section on key bindings, what he was trying to accomplish, and what he finally chose.
It’s worth reading through his configuration just for some of the ideas. I learned about packages and settings that I wasn’t familiar with. The easiest way to do that is to read the TC3F.txt file because it’s nicely formatted. Ideally, you’d want to read TC3F.org but for some reason GitHub displays it in raw mode rather than the nicely formatted mode that GitHub usually uses for Org files. It’s also worth taking a look at the makefile to see how he builds init.el from his TC3F.org file.
Most readers will probably find Rettke’s Org file overkill—it’s 4,460 lines long—but I like the idea of documenting why you made the choices you did and what a particular piece of code is doing. The table of contents at the beginning makes it easy to locate a particular part of the configuration. In Rettke’s case there’s the extra step of building the configuration file by running the makefile but these days I usually only make a couple of changes a month so it’s not much of a burden, at least for me. If that bothers you, you can have it loaded automatically by bootstrapping it from a minimal init.el as Sacha demonstrates with her configuration.
My point in writing about Rettke’s configuration is not that I think everyone will want to have the same kind of comprehensive document but that it serves as an excellent example of how you can use literate programming for your Emacs configuration. As I said above, it’s worth reading through the TC3F.txt file to find packages and features that you didn’t know about and the TC3F.org file to see how you can put together an Emacs configuration using literate programming methods.