+++ 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 {#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") ```

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 {#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" "" 'evil-window-left :n :desc "Up" "" 'evil-window-up :n :desc "Down" "" 'evil-window-down :n :desc "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" "" 'evil-window-left :n :desc "Up" "" 'evil-window-up :n :desc "Down" "" 'evil-window-down :n :desc "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.