feat: babel

1 files changed, 159 insertions, 6 deletions

diff --git a/content-org/emacs.org b/content-org/emacs.org
index 1160a16..76817ee 100644
--- a/content-org/emacs.org
+++ b/content-org/emacs.org
@@ -151,7 +151,7 @@ CLOSED: [2024-01-30 Tue 19:10]
 :PROPERTIES:
 :EXPORT_FILE_NAME: literate-programing-in-emacs
 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: abstract A short introduction into the idea of literate programming
-:EXPORT_HUGO_MENU: :menu emacs-guides :name "Literate programing"
+:EXPORT_HUGO_MENU: :menu "emacs-guides" :identifier "litprog" :name "Literate programming"
 :END:
 
 *** Abstract
@@ -178,6 +178,7 @@ The idea is therefore a conversion of an entity out of which one can extract cod
 A semi-abstract in-between called "web[fn:web]".
 The process of creating code is called "tangling", and generation of document is a "weave".
 
+
 *** An example
 
 Let's say we want to show the reader how to install DWM.
@@ -257,13 +258,165 @@ Wherever one can see a logical A, B and C points, we can explain the interconnec
 
 You can learn more (including much better example) by reading the [[https://michal.sapka.me/papers/literate_programming_knuth_1984.pdf][original Knuth's paper]].
 
-** TODO Babel
+** DONE Executing code in Org files with Babel
+CLOSED: [2024-02-07 Wed 21:23]
+:PROPERTIES:
+:EXPORT_FILE_NAME: org-babel
+:EXPORT_HUGO_CUSTOM_FRONT_MATTER: abstract A short introduction into the world if Org Babel
+:EXPORT_HUGO_MENU: :menu "emacs-guides" :parent "litprog" :name "Literate programing in Org with Babel"
+:END:
+*Abstract*: a very short introduction into the word of Org Babel.
+
+No other package seems to have had such huge impact on Emacs community as the introduction of Org Babel[fn:magit].
+It made folks not only love their Org Mode, but /live/ in it.
+
+In short: Babel allows for [[/emacs/literate-programing-in-emacs/][literate programming]] form within an Org document.
+
+[fn:magit] you may argue and say that =magit= had bigger impact.
+I disagree.
+Magit made using git nicer and easier, but it is still the old, old git.
+Babel changed the way we use the edit code, the way we think and how we work.
+
+*** Source code basics
+
+Babel comes baked into any modern version of =Emacs=, so you've already got everything you need.
+Open any =org= document, add the code to the document within source code blocks:
+
+#+BEGIN_SRC emacs-lisp
+  regular text
+
+  ,#+BEGIN_SRC emacs-lisp
+  (+ 1 1)
+  ,#+END_SRC
+
+  and more regular text
+#+END_SRC
+
+Now, move the pointer to with the blocks, tap =C-c C-c= and the code is evaluated.
+The result will be appended just below the source code, in a =RESULT= block.
+
+You now know how to do literate programming in Emacs.
+Create an Org document, add your narrative, add your source code and execute.
+Simple, isn't it?
+
+By default, =Babel= allows only for execution of =emacs-lisp= mode, but it supports many more.
+You can enable all supported via:
+
+  #+begin_src emacs-lisp
+    (org-babel-do-load-languages 'org-babel-load-languages
+                                 '((shell      . t)
+                                   (js         . t)
+                                   (emacs-lisp . t)
+                                   (clojure    . t)
+                                   (python     . t)
+                                   (ruby       . t)
+                                   (dot        . t)
+                                   (css        . t)
+                                   (plantuml   . t)))
+#+end_src
+
+There are even more provided as dedicated packages.
+
+*** Being faster
+
+Typing =#+BEGIN_SRC= can become tedious pretty quick.
+We can use the =org-tempo= package to make it much faster.
+
+
+#+begin_src emacs-lisp
+  (require 'org-tempo)
+  (setq org-structure-template-alist
+        '(("s" . "src")))
+#+end_src
+
+  Now, we can create new block simply by taping =<s= and pressing tab.
+
+  Org tempo supports many more blocks, you can refer to [[https://orgmode.org/manual/Structure-Templates.html][the official manual]].
+
+*** Joining the blocks together
+
+In /strict/ Literate Programming sense, your /web// should not be where you execute code.
+Instead, you should extract programmatic parts and run it separately - the process is called /tangling/.
+
+Babel bypasses this limitation with =noweb= mode, in which code blocks can reference each other.
+First, you need to name your code blocks:
+
+#+begin_src emacs-lisp
+,#+NAME: two
+,#+BEGIN_SRC emacs-lisp
+(+ 1 1)
+,#+END_SRC
+#+end_src
+
+Then we can use it the result other code blocks
+
+#+begin_src emacs-lisp
+,#+NAME: three
+,#+BEGIN_SRC emacs-lisp :noweb yes
+(+ <<two>> 1)
+,#+END_SRC
+#+end_src
+
+Here, the =<<two>>= will be replaced with the result of block named =two=.
+This makes the block =three= return the number =3=.
+
+This mode gives quite a lot more option.
+You can read about them inside [[https://orgmode.org/manual/Noweb-Reference-Syntax.html][manual]].
+
+*** Running on remote machines
+
+To make it even /cooler/, Babel integrates with =Tramp= mode which allows for execution over ssh!
+You can add a tramp-style header argument as =:dir= and the code will be executed over the established connection.
+
+#+begin_src emacs-lisp
+,#+BEGIN_SRC shell :dir /user@host:~/
+rm -rf /
+,#+END_SRC
+#+END_SRC
+
+And boom - we've got a bomb.
+
+*** Babel as source for Emacs configuration
+
+The most popular use case of Babel however is Emacs configuration.
+You can have as many org files as you want, have the configuration inside =emacs-lisp= code blocks and use that as config.
+
+**** Loading files directly
+
+If your config isn't /very/ complicated, you can force Emacs to parse the files on boot.
+To achieve that, add
+
+#+begin_src emacs-lisp
+(org-babel-load-file "~/.emacs.d/config.org")
+#+END_SRC
+
+To your =init.el=.
+
+What happens is, that Emacs will create a corresponding =config.el= (/tangle/) file and load it as a elisp file.
+Just remember not to name your config as =init.org= as there will be naming conflict with =init.el=.
+
+**** Pre-tangling
+
+If you don't want /tangling/ on boot time, but rather want to have it ready you can manually /org-babel-tangle/.
+To achieve it, add a =tangle= header argument to all you code blocks:
+
+#+begin_src emacs-lisp
+,#+BEGIN_SRC emacs-lisp :tangle ~/.emacs.d/init.el
+(+ 1 1)
+,#+END_SRC
+#+END_SRC
+
+And then, after any changes of the file run =org-babel-tangle= and your =init.el= will be up-to-date.
+This is the approach [[https://protesilaos.com/codelog/2023-12-18-emacs-org-advanced-literate-conf/][Prot]] uses, but his config consists of over /17_000/ [sic!] lines of org file, so your mileage may vary.
+
+*** Links
 
-Org Babel is an extension of Org mode allowing for arbitraty inserting and executing code inside Org file.
-It puts everything we know on it's head - it's the literate part (comment) that is guest.
-With Babel the text document is what you are working with, and code is added as a neccesary part.
+If you are interested in the subject, you can look at much more details sources:
 
-And with this, seemingly insignificant change, our approach shifted.
+- [[https://orgmode.org/worg/org-contrib/babel/intro.html][Official website]]
+- [[https://howardism.org/Technical/Emacs/literate-devops.html][Literate devops]] on Howardism
+- [[https://protesilaos.com/codelog/2023-12-18-emacs-org-advanced-literate-conf/][Advanced literate configuration]] on Prot's website.
+- [[https://org-babel.readthedocs.io/en/latest/][Cheat sheet]]
 
 ** DONE Moving My RSS Reading to Emacs With Elfeed
 CLOSED: [2023-05-19 Wed 23:00]