From 2089daeb88d9e1537d025ec5db675903208ad986 Mon Sep 17 00:00:00 2001 From: mms Date: Wed, 7 Feb 2024 22:09:39 +0100 Subject: feat: babel --- content-org/emacs.org | 165 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 159 insertions(+), 6 deletions(-) (limited to 'content-org/emacs.org') 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 => 1) +,#+END_SRC +#+end_src + +Here, the =<>= 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] -- cgit v1.2.3