dotfiles/docs/notes/literate-programming.org

#+TITLE: Literate Programming
#+AUTHOR: Christopher James Hayward

#+ROAM_KEY: https://chrishayward.xyz/notes/literate-programming/

#+HUGO_BASE_DIR: ~/.local/source/website
#+HUGO_AUTO_SET_LASTMOD: t
#+HUGO_SECTION: notes

+ Programming paradigm
+ Programs expressed in natural language with code snippets
+ Produces machine readable code and human readable documentation

* Introduction

Described in its introduction[fn:knuth-1984] as a

#+begin_quote
Programming paradigm in which a computer program is given an explanation of its logic in a natural language, such as English, interspersed with snippets of macros and traditional source code, from which compilable source code can be generated.
#+end_quote

Knuth describes a *practitioner* in the introduction of his 1984 paper[fn:knuth-1984] as

#+begin_quote
An essayist concerned with exposition and excellence of style. Someone who carefully selects the name for each variable and describes their meaning. They will strive for a program that is comprehensible because concepts are introduced in a manner best for human understanding.
#+end_quote

* Concept

#+begin_example
                     _____
                    |     | -> Send to Boss
 _____              | doc | -> Copy to Team
|     | -> Weave -> |_____| -> Copy to Support
| org |               _____
|_____| -> Tangle -> |     | -> Test on CI
                     | src | -> Copy to CDN
                     |_____| -> Send to Customer
#+end_example

Illustrated above we see the process of *weaving* and *tangling* the literate source file, and how each of the produced components is handled respectively. 

| File | Description                  |
|------+------------------------------|
| org  | Literate document / file     |
| src  | Machine readable source code |
| doc  | Human readable documentation |

* Resources

[fn:knuth-1984] Knuth, D. E. (1984). Literate Programming. The Computer Journal, 27(2), 97–111. https://doi.org/10.1093/comjnl/27.2.97