diff options
Diffstat (limited to 'content/emacs/literate-programing-in-emacs.md')
| -rw-r--r-- | content/emacs/literate-programing-in-emacs.md | 117 |
1 files changed, 0 insertions, 117 deletions
diff --git a/content/emacs/literate-programing-in-emacs.md b/content/emacs/literate-programing-in-emacs.md deleted file mode 100644 index 258a96d..0000000 --- a/content/emacs/literate-programing-in-emacs.md +++ /dev/null @@ -1,117 +0,0 @@ -+++ -title = "Emacs: 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] - weight = 2002 - parent = "guides" - identifier = "litprog" - name = "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. |