132 lines
5.1 KiB
Markdown
132 lines
5.1 KiB
Markdown
+++
|
|
title = "Literate Programming Emacs Configuration"
|
|
author = ["Elia el Lazkani"]
|
|
date = 2020-09-12
|
|
lastmod = 2020-09-12
|
|
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.
|