feat: literature config + pledge

4 files changed, 122 insertions, 6 deletions

diff --git a/content/emacs/elfeed-literate-config.md b/content/emacs/elfeed-literate-config.md
index 47a4666..6ad965c 100644
--- a/content/emacs/elfeed-literate-config.md
+++ b/content/emacs/elfeed-literate-config.md
@@ -4,11 +4,11 @@ author = ["Michał Sapka"]
 date = 2023-06-02T23:00:00+02:00
 categories = ["emacs"]
 draft = false
-weight = 2003
+weight = 2004
 abstract = "Setting up config inside an org file"
 [menu]
   [menu.emacs-guides]
-    weight = 2003
+    weight = 2004
     identifier = "literate-configuration-of-elfeed"
     parent = "elfeed"
     name = "Literate configuration"
diff --git a/content/emacs/literate-programing-in-emacs.md b/content/emacs/literate-programing-in-emacs.md
new file mode 100644
index 0000000..8df4841
--- /dev/null
+++ b/content/emacs/literate-programing-in-emacs.md
@@ -0,0 +1,116 @@
++++
+title = "Introduction to Literate programming"
+author = ["Michał Sapka"]
+date = 2024-01-30T19:10:00+01:00
+categories = ["emacs"]
+draft = false
+weight = 2002
+abstract = "A short introduction into the idea of literate programming"
+[menu]
+  [menu.emacs-guides]
+    weight = 2002
+    identifier = "introduction-to-literate-programming"
+    name = "Literate programing"
++++
+
+## 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.
\ No newline at end of file
diff --git a/content/emacs/moving-my-rss-reading-to-emacs-with-elfeed.md b/content/emacs/moving-my-rss-reading-to-emacs-with-elfeed.md
index a6925c2..f923ab5 100644
--- a/content/emacs/moving-my-rss-reading-to-emacs-with-elfeed.md
+++ b/content/emacs/moving-my-rss-reading-to-emacs-with-elfeed.md
@@ -4,11 +4,11 @@ author = ["Michał Sapka"]
 date = 2023-05-19T23:00:00+02:00
 categories = ["emacs"]
 draft = false
-weight = 2002
+weight = 2003
 abstract = "Setting up config inside an org file"
 [menu]
   [menu.emacs-guides]
-    weight = 2002
+    weight = 2003
     identifier = "elfeed"
     name = "Following RSS with Elfeed"
 +++
diff --git a/content/emacs/notmuch.md b/content/emacs/notmuch.md
index f7a32e1..0a7cc29 100644
--- a/content/emacs/notmuch.md
+++ b/content/emacs/notmuch.md
@@ -4,11 +4,11 @@ author = ["Michał Sapka"]
 date = 2023-07-03T23:00:00+02:00
 categories = ["emacs"]
 draft = false
-weight = 2004
+weight = 2005
 abstract = "My email based workflow for GitHub Pull Review Requests"
 [menu]
   [menu.emacs-guides]
-    weight = 2004
+    weight = 2005
     identifier = "managing-email-with-notmuch-and-emacs"
     name = "Reading and automating email using Notmuch"
 +++