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