feat: literate prog 1st draft

2 files changed, 142 insertions, 1 deletions

diff --git a/content-org/emacs.org b/content-org/emacs.org
index 12fc38a..cc5012e 100644
--- a/content-org/emacs.org
+++ b/content-org/emacs.org
@@ -1,4 +1,4 @@
-#+TITLE: Michał Sapka's Emacs Config
+#+TITLE: Emacs @ mms site
 #+AUTHOR: Michał Sapka
 #+URL: https://michal.sapka.me
 #+STARTUP: show2levels indent logdone
@@ -40,6 +40,7 @@ Varia
 :PROPERTIES:
 :EXPORT_HUGO_MENU: :menu emacs-guides
 :END:
+
 ** DONE Input Completiton in Emacs
 CLOSED: [2023-05-26 Wed 23:00]
 :PROPERTIES:
@@ -147,6 +148,124 @@ The great thing about FIDO is that it, like Icomplete, uses Minibuffer API[fn:mi
 #+END_SRC
 
 [fn:minibuffer] [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Minibuffer-Completion.html][Guide on Minibuffer completition]]
+** TODO Introduction to Literate programming
+:PROPERTIES:
+:EXPORT_FILE_NAME: literate-programing-in-emacs
+:EXPORT_HUGO_CUSTOM_FRONT_MATTER: abstract A short intro into the idea of literate programing
+:EXPORT_HUGO_MENU: :menu emacs-guides :name "Literate programing"
+:END:
+
+*** Abstract
+
+Here I give a short, theoretical introduction to the idea of Literate programing
+
+*** Preface
+
+Literate programing is not a subject that comes out often, except if you are talking with an Emacs enthusiast.
+There is a signifcant chance, that most programmers don't even know the term.
+Let's fix that with a quote:
+
+#+begin_quote
+Literate programming is an approach to programming which emphasises that programs should be written to be read by people as well as compilers.
+From a purist standpoint, a program could be considered a publishable-quality document that argues mathematically for its own correctness.
+A different approach is that a program could be a document that teaches programming to the reader through its own example.
+A more casual approach to literate programming would be that a program should be documented at least well enough that someone could maintain the code properly and make informed changes in a reasonable amount of time without direct help from the author.
+At the most casual level, a literate program should at least make its own workings plain to the author of the program so that at least the author can easily maintain the code over its lifetime.
+
+-- Christopher Lee[fn:lee]
+#+end_quote
+
+The idea is therefore an convertion of an entity out of which one can extract code or documentation.
+An 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.
+We can create a document in a style:
+
+#+begin_quote
+DWM is a window manager that can be changed only via source code modification.
+Here, we will fetch and compile it.
+First, we need to download the tarball:
+
+#+begin_src shell
+wget https://dl.suckless.org/dwm/dwm-6.4.tar.gz
+#+end_src
+
+then, simply extract it
+
+#+begin_src shell
+tar - xvzf dwm-6.4.tar.gz
+#+end_src
+
+And then we compile it
+
+#+begin_src shell
+  cd dwm-6.4
+  doas make clean install
+#+end_src
+
+After the compilation finishes, add executable to your .xinit
+
+#+begin_src
+  echo "exec dwm" >> ~/.xinit
+#+end_src
+#+end_quote
+
+So yeah, it's a blog post.
+A blog post which one can exeute.
+The example assumes shell, but the actual language can be anything.
+We can /tangle/ C code without any problems.
+
+*** Literate programing
+
+This is *not* the way we do programing.
+We smack spagetti code together, add a random sentence here and there, commit is as "bug fix" and voila!
+In a few months no one knows what's going on.
+Success, up to the next JIRA task.
+
+Very often code comments are treated as an harmful or (at best) a neccessar evil.
+We think that code should be self-documenting.
+And this is completely valid.
+A developer needs to understand what given code does, just by reading it.
+If your function is so convoluted, nested and complicated that it's impossible to comprehend without a descriptive comment.
+
+But this is not the whole story.
+A function may be very simple, but there is always /context/ in which it is used.
+
+Literate Programming promotes telling story to the reader.
+You are free to do narration giving all extra info in one place.
+Since the code coexists with documentation, the reader gets the whole picture.
+
+[fn:lee] [[https://web.archive.org/web/20170603045917/http://vasc.ri.cmu.edu:80/old_help/Programming/Literate/literate.html]["Literate Programming -- Propaganda and Tools", Christopher Lee, 1997]]
+[fn:babel] [[https://orgmode.org/worg/org-contrib/babel/intro.html][Org Babel]]
+[fn:jupyter] I know that Jupyter is not strictly a literate program, but it's close enough.
+[fn:web] the name was choosen, because at the time it was not in use ralated to computing.
+We're dealing with history here!
+
+*** Conclusion
+
+Now, this is not a generic fix for all programs.
+We work on massive systems with hundreds of intertwined, moving parts.
+It is impossible to create a cohesive narrative when the program jumps all over the place.
+
+Literate programing, however, found a different home.
+It is loved by scientists (just look at Jupyter Notebooks[fn:jupyter]) who use it for reproducible resarch.
+We, amongts Emacs crowed, use it extensively for literate configuration of our environments.
+It could be used for scripts, runbooks, debugging logs and so on.
+Wherever one can see a logical A, B and C points, we can explain the interconnections.
+
+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
+
+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.
+
+And with this, seemingly insignificant change, our approach shifted.
+
 ** DONE Moving My RSS Reading to Emacs With Elfeed
 CLOSED: [2023-05-19 Wed 23:00]
 :PROPERTIES:
diff --git a/content-org/links.org b/content-org/links.org
new file mode 100644
index 0000000..8cf9230
--- /dev/null
+++ b/content-org/links.org
@@ -0,0 +1,22 @@
+* BSD flavors
+* BSD Blogs and vlogs
+* Emacs blogs and vlogs
+* Linux distributions
+* Linux learning materials
+* Ruby news
+* Privacy
+* E/N Blogs
+* Retro computing
+* Security
+* Essential services
+** Tarsnap
+** Internet Archive?
+* Web browsers
+* XMPP
+* Self hosted services
+* Self hosted Git servers and UIs
+* Internet search
+* Mastodon servers
+* MacOS essentials
+* Text editors
+* iOS apps