5.1 KiB
+++ title = "Literate Programming Emacs Configuration" author = ["Elia el Lazkani"] date = 2020-09-12T21:00:00+02:00 lastmod = 2021-06-28T00:01:52+02:00 tags = ["emacs", "org-mode", "configuration"] categories = ["text-editors"] draft = false +++
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")
warning
Make sure org-mode and org-babel are both installed and configured on your system before trying to run org-babel-load-file
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.