My personal experience with the literate config style in Emacs as of the end of 2018, and why I think I don't like it.
To skip all the lyrics and get right to the points click here.
Lyrical digression and necessary disclaimer
The concept of literate config was attractive to me because when you read it, it feels like the actual documentation for some library or framework. I mean, pieces of code with exhaustive description around it, not just a couple line of comments. Epic examples which inspired me to try it out were Sacha Chua's and wasamasa's.
It's simple. You create a file named
config.org in your
directory. You organize it as you organize any org file, but with a
bits of elisp like this:
* Org-mode heading Text describing the code below, your intention etc #+BEGIN_SRC emacs-lisp (defun some-elisp-code (&optional params) (...)) #+END_SRC
Then, in your
init.el you call
(org-babel-load-file (concat user-emacs-directory "config.org"))
org-babel-load-file grabs all elisp pieces from your org
file and put them together into a file called
config.el. You can
find it near the original file.
You put your org config file under the VCS, put it on GitHub which renders it properly, you're happy, people give you stars and life feels complete. Not even mention that you can export the config to HTML and put it on your site (Sacha's one, for example).
Things I didn't like
First, my unfinished org config is here. Now, to the list:
I can't easily navigate elisp from org file. E.g. I can do C-h f and C-h v over functions and variables, but I can't directly go to their definitions with M-.. Maybe
xrefcan be configured the right way, but I haven't got to it.
I can't edit the code directly in the config file, I have to open dedicated buffer with C-c '. It didn't look like a big deal when I've seen somebody else doing that, but it's quite cumbersome for me.
Text, surrounding the code, creates too much noise. It makes config harder to navigate, and the code itself doesn't look like the first class citizen. I'm not even mentioning
#+END_SRCstuff (I've just mentioned it actually).
Surrounding text itself looks redundant to me. I don't do anything significantly complex, and when I do, I tend to write comments and descriptive commit headers and messages.
I don't see any benefit for me personally. I see how it's more convenient for other people to read and study such config, but I don't seem to gain any benefit myself.
With all that being said, I won't trash this experiment. I'll save it under the dedicated branch and will back up to my main config which I'll separate into multiple files, as I would do with a regular software project.
Meanwhile, I'd gladly hear what possible advantages of an org style config am I missing. Maybe there is something that would outweigh cons which are deal-breakers for me now.
Check the discussion on Reddit. As always, people there suggested lots of interesting ways how they deal with inconveniences I've mentioned earlier.