blog.lazkani.io/content/posts/literate-programing-emacs-configuration.md

+++
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.

<!--more-->


## Introduction {#introduction}

If you haven't checked [org-mode](https://orgmode.org/) 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](https://orgmode.org/worg/org-contrib/babel/intro.html)_ 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 {#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.

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

<div class="admonition warning">
<p class="admonition-title">warning</p>

Make sure _org-mode_ and _org-babel_ are both **installed** and **configured** on your system before trying to run `org-babel-load-file`

</div>


## Org-mode Conversion {#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.

```text
#+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 {#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.

```org
#+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.

```org
* 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 {#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.