Literate Org-mode configuration for Emacs is liberating

TLDR: Check out the Docs section for my Emacs config in Org-mode

The literate programming paradigm, as conceived by Donald Knuth, represents a move away from writing programs in the manner and order imposed by the computer, and instead enables programmers to develop programs in the order demanded by the logic and flow of their thoughts. Literate programs are written as an uninterrupted exposition of logic in an ordinary human language, much like the text of an essay, in which macros are included to hide abstractions and traditional source code.

Wikipedia article on Literate Programming

I had graduated to using an Org-mode based configuration with vanilla Emacs, until discovering Scimax a few years ago. At this point, it seemed easier to switch back to using elisp script files in multiple files which were loaded in the desired / necessary order. The plan was to use a file for each major ‘concept’, for example one file each for hydras, Org-mode, mu4e, and so on.

While it is not difficult to manage multiple script files with the projectile package, it does become cumbersome and inelegant to record notes and thoughts in the comment form along with code. Over time, it also becomes difficult to decide the placement of multi-package functions and snippets. As my configuration has evolved - I’ve felt an increasing need to shift back to a literate configuration using Org for Emacs, and also separate the personal parts of my configuration to enable sharing on Github.

Using a literate configuration enables a live documentary of my Emacs configuration and also adding meaningful notes and snippets which are directly or indirectly related to configuring Emacs. For example, it is important to have IPython and Jupyter installed for Scimax to work correctly, and I can include notes and working scripts for the same.

There are discussions on Emacs init time increasing by using a tangled org file. However, this is atleast partially remedied by including a function to tangle the config file whenever it is saved, and there are other methods like the one described by Holger Schurig, which I intend to try out soon. Personally, I have not found any degrade in Emacs init time via Scimax.

Related