Browse Source

Publishing literate programming emacs configuration

master
Elia el Lazkani 9 months ago
parent
commit
c23914cf53
  1. 1
      .gitignore
  2. 125
      posts/text-editors/literate-programming-emacs-configuration.org

1
.gitignore

@ -2,6 +2,7 @@
__pycache__/
output/
cache/
themes/willy-theme
.doit.db
.doit.db.*
.venv/

125
posts/text-editors/literate-programming-emacs-configuration.org

@ -0,0 +1,125 @@
#+BEGIN_COMMENT
.. title: Literate Programming Emacs Configuration
.. date: 2020-09-12
.. slug: literate-programing-emacs-configuration
.. updated: 2020-09-12
.. status: published
.. tags: emacs, org-mode, configuration,
.. category: text-editors
.. authors: Elia el Lazkani
.. description: Once I got familiar with org-mode a bit more, I decided to take it a step further towards documenting everything.
.. type: text
#+END_COMMENT
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.
{{{TEASER_END}}}
* Introduction
If you haven't checked [[https://orgmode.org/][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 /[[https://orgmode.org/worg/org-contrib/babel/intro.html][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.
#+BEGIN_SRC emacs-lisp
(org-babel-load-file "~/path/to/my/configuration.org")
#+END_SRC
#+BEGIN_EXPORT html
<div class="admonition warning">
<p class="admonition-title">warning</p>
#+END_EXPORT
Make sure /org-mode/ and /org-babel/ are both *installed* and *configured* on your system before trying to run ~org-babel-load-file~
#+BEGIN_EXPORT html
</div>
#+END_EXPORT
* 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_EXAMPLE
#+BEGIN_SRC emacs-lisp
... some code ...
#+END_SRC
#+END_EXAMPLE
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_EXAMPLE
#+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
#+END_EXAMPLE
I converted it to something that looks very familiar to /org/ users out there.
#+BEGIN_EXAMPLE
* 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
#+END_EXAMPLE
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.
Loading…
Cancel
Save