Literate Programming Emacs Configuration

I was working on a project that required a lot of manual steps. I generally lean towards automating everything but in some cases that is, unfortunately, not possible.

Documenting such project is not an easy task to accomplish, especially with so many moving parts and different outputs.

Since I have been using org-mode more frequently for documentation and organization in general, I gravitated towards it as a first instinct.

I wasn’t sure of the capabilities of org-mode in such unfamiliar settings but I was really surprised by the outcome.

Introduction

If you haven’t checked org-mode already, you should.

As its main capability it is to keep it simple for writing things down and organizing them, org-mode is great to keep track of the steps taking along the way.

The ability to quickly move between plain text and into code blocks is excellent. Coupling org-mode with org-babel gives you the ability to run the source code blocks and get the output back into the org file itself. That is extremely neat.

With those two abilities alone, I could document things as I go along. This included both the commands I am running and the output I got back. Fantastic.

After some search online, I found out that this method is called literal coding. It consists of having the plain text documentation and the code in the same file and with the help of both previously mentioned emacs packages one can get things working.

That sounds like fun!

Emacs Configuration

After digesting all the information I mentioned so far, that got me thinking. What about emacs?

A quick look online got me the answer. It is possible to do with emacs as well. Alright, let’s get right into it shall we ?

First step, I added the following line to my main configuration. In my case, my main configuration file is the doom distribution’s configuration file.

(org-babel-load-file "~/path/to/my/configuration.org")

Org-mode Conversion

After I pointed my main emacs configuration to the org configuration file I desire to use, I copied all the content of my main emacs configuration in an emacs-lisp source code block.

#+BEGIN_SRC emacs-lisp
... some code ...
#+END_SRC

I, then, reloaded my emacs to double check that everything works as expected and it did.

Document the code

Now that we have everything in one org file, we can go ahead and start documenting it. Let’s see an example of before and after.

I started small, bits and pieces. I took a snippet of my configuration that looked like the following.

#+BEGIN_SRC emacs-lisp
(setq display-line-numbers-type t)
(setq display-line-numbers-type 'relative)
(after! evil
   (map! :map evil-window-map
         (:leader
          (:prefix ("w" . "Select Window")
           :n :desc "Left"  "<left>" 'evil-window-left
           :n :desc "Up"    "<up>" 'evil-window-up
           :n :desc "Down"  "<down>" 'evil-window-down
           :n :desc "Right" "<right>" 'evil-window-right))))
#+END_SRC

I converted it to something that looks very familiar to org users out there.

* Line Numbering
** Enable line numbering
   Enabling line numbering by turning the flag on.
   #+BEGIN_SRC emacs-lisp
(setq display-line-numbers-type t)
   #+END_SRC

** Configure /relative/ line numbering
   Let's also make sure it's the /relative/ line numbering.
   This helps jumping short distances very fast.
   #+BEGIN_SRC emacs-lisp
(setq display-line-numbers-type 'relative)
   #+END_SRC

* Evil
** Navigation
   I'd like to use the /arrows/ to move around. ~hjkl~ is not very helpful or pleasant on /Colemak/.
   #+BEGIN_SRC emacs-lisp
(after! evil
  (map! :map evil-window-map
        (:leader
         (:prefix ("w" . "Select Window")
          :n :desc "Left"  "<left>" 'evil-window-left
          :n :desc "Up"    "<up>" 'evil-window-up
          :n :desc "Down"  "<down>" 'evil-window-down
          :n :desc "Right" "<right>" 'evil-window-right))))
   #+END_SRC

It might not be much a looker in such a block, but trust me, if you have an org-mode parser it will make total sense. It will export to html very well too.

Most importantly, the emacs configuration still works.

Conclusion

I went through my emacs configuration and transformed it into a documented org file. My configuration looks a little bit neater now and that’s great.

The capabilities of literal programming goes way beyond this post, which goes without saying, and this is not the only use case for it.