summaryrefslogtreecommitdiffstats
path: root/site/cleopatra/literate-programming.org
diff options
context:
space:
mode:
authorThomas Letan <lthms@soap.coffee>2020-12-20 12:47:37 +0100
committerThomas Letan <lthms@soap.coffee>2020-12-20 12:47:37 +0100
commit9722f57891b99694a60d2fcb376375606741445e (patch)
tree8b69d0ac330580a89bc3e4d270d75cbb78554053 /site/cleopatra/literate-programming.org
parent240f069dad61a85dbfc281472a2af6cb91ef07d4 (diff)
Provide some insight on how literate programming projects are built
Diffstat (limited to 'site/cleopatra/literate-programming.org')
-rw-r--r--site/cleopatra/literate-programming.org67
1 files changed, 47 insertions, 20 deletions
diff --git a/site/cleopatra/literate-programming.org b/site/cleopatra/literate-programming.org
index 3b56924..be25097 100644
--- a/site/cleopatra/literate-programming.org
+++ b/site/cleopatra/literate-programming.org
@@ -2,12 +2,56 @@
<h1>Literate Programming Projects</h1>
#+END_EXPORT
+Literate programming is an interesting exercice. It forces programmers
+to think about how to present their code for other people to
+understand it. It poses several significant challenges, in particular
+in terms of code refactoring. If a given piece of code is too much
+entangled with proses explaining it, rewriting it becomes cumbersome.
+
+That being said, literate programming is particularly well-suited for
+blog posts, since at the very least it provides the tool to enforce
+the code presented to readers is correct.
+
+We use Emacs and ~org-mode~ to tangle the literate programming
+projects present in the ~posts/~ directory of this website. This is
+done with the following emacs lisp script.
+
+#+BEGIN_SRC emacs-lisp :tangle export-lp.el
+(cleopatra:configure) ; opinionated configuration provided by cleopatra
+
+(org-babel-do-load-languages
+ 'org-babel-load-languages
+ '((shell . t))) ; allow the execution of shell block code
+
+ ;; scan the posts/ directory and tangled it into lp/
+(setq org-publish-project-alist
+ '(("lp"
+ :base-directory "site/posts"
+ :publishing-directory "lp"
+ :recursive t
+ :publishing-function cleopatra:tangle-publish)))
+
+(org-publish-all)
+#+END_SRC
+
+Tangling literate programming is done in the =prebuild= phase of
+*~cleopatra~*.
+
#+BEGIN_SRC makefile :tangle literate-programming.mk
literate-programming-prebuild :
@cleopatra echo "Tangling" "literate programming project"
@cleopatra exec -- cleopatra-run-elisp export-lp.el \
>> build.log 2>&1
+ARTIFACTS += lp/ site/posts/deps.svg
+#+END_SRC
+
+In the =build= phase, we actually try to compile the tangled projects.
+As of now, there is only one literate program: [[../posts/CoqffiEcho.org][the Echo server
+implemented in Coq]] which demonstrates how ~coqffi~ can be used to
+implement realistic software projects.
+
+#+BEGIN_SRC makefile :tangle literate-programming.mk
COQFFI_ARCHIVE := site/files/coqffi-tutorial.tar.gz
coqffi-tutorial-build : literate-programming-prebuild
@@ -15,28 +59,11 @@ coqffi-tutorial-build : literate-programming-prebuild
@cd lp/coqffi-tutorial; dune build --display quiet
@cleopatra echo "Archiving" "coqffi tutorial"
@rm -f ${COQFFI_ARCHIVE}
- @tar --exclude="_build" -C lp/ -czvf ${COQFFI_ARCHIVE} coqffi-tutorial >> build.log
+ @tar --exclude="_build" -C lp/ -czvf ${COQFFI_ARCHIVE} coqffi-tutorial \
+ 2>&1 >> build.log
site/posts/CoqffiEcho.html : coqffi-tutorial-build
literate-programming-build : coqffi-tutorial-build
-ARTIFACTS += lp/ ${COQFFI_ARCHIVE} site/posts/deps.svg
-
-#+END_SRC
-
-#+BEGIN_SRC emacs-lisp :tangle export-lp.el
-(cleopatra:configure)
-
-(org-babel-do-load-languages
- 'org-babel-load-languages
- '((shell . t)))
-
-(setq org-publish-project-alist
- '(("lp"
- :base-directory "site/posts"
- :publishing-directory "lp"
- :recursive t
- :publishing-function cleopatra:tangle-publish)))
-
-(org-publish-all)
+ARTIFACTS += ${COQFFI_ARCHIVE}
#+END_SRC