1 files changed, 119 insertions, 0 deletions
diff --git a/content/emacs/literate-programing-in-emacs.md b/content/emacs/literate-programing-in-emacs.md
new file mode 100644
index 0000000..3379bb2
--- /dev/null
+++ b/content/emacs/literate-programing-in-emacs.md
@@ -0,0 +1,119 @@
++++
+title = "Introduction to Literate programming"
+author = ["Michał Sapka"]
+date = 2024-01-30T19:10:00+01:00
+categories = ["emacs"]
+draft = false
+weight = 3005
+image_dir = "emacs"
+image_max_width = 480
+primary_menu = "cool-emacs-appendix"
+abstract = "A short introduction into the idea of literate programming"
+aliases = ["/cool-emacs/literate-programing-in-emacs/"]
+[menu]
+  [menu.cool-emacs-appendix]
+    weight = 3005
+    identifier = "introduction-to-literate-programming"
++++
+
+## Abstract {#abstract}
+
+In this article I give a short, theoretical introduction to the idea of Literate programming
+
+
+## Introduction {#introduction}
+
+Literate programming is not a subject that comes out often, except if you are talking with an Emacs enthusiast.
+There is a significant chance that most programmers don't even know the term.
+Let's fix that with a 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:1]
+
+The idea is therefore a conversion of an entity out of which one can extract code or documentation.
+A semi-abstract in-between called "web[^fn:2]".
+The process of creating code is called "tangling", and generation of document is a "weave".
+
+
+## An example {#an-example}
+
+Let's say we want to show the reader how to install DWM.
+We can create a document in a style:
+
+> 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:
+>
+> ```shell
+> wget https://dl.suckless.org/dwm/dwm-6.4.tar.gz
+> ```
+>
+> then, simply extract it
+>
+> ````shell
+> tar - xvzf dwm-6.4.tar.gz
+> ````
+>
+> And then we compile it
+>
+> `````shell
+> cd dwm-6.4
+> doas make clean install
+> `````
+>
+> After the compilation finishes, add executable to your .xinit
+>
+> ``````shell
+> echo "exec dwm" >> ~/.xinit
+> ``````
+
+So yeah, it's a blog post.
+A blog post which one can execute.
+The example assumes shell, but the actual language can be anything.
+We can _tangle_ C code without any problems.
+
+
+## Literate programming {#literate-programming}
+
+This is **not** the way we do programming.
+We smack spaghetti code together, add a random sentence here and there, commit is as "bug fix" and voilà!
+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 necessary 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.
+
+
+## Conclusion {#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:3]) 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 [original Knuth's paper](https://michal.sapka.me/papers/literate_programming_knuth_1984.pdf).
+
+[^fn:1]: ["Literate Programming -- Propaganda and Tools", Christopher Lee, 1997](https://web.archive.org/web/20170603045917/http://vasc.ri.cmu.edu:80/old_help/Programming/Literate/literate.html)
+[^fn:2]: this name was choosen, because at the time it was not in use related to computing.
+    We're dealing with history here!
+[^fn:3]: I know that Jupyter is not strictly a literate program, but it's close enough.