#+BEGIN_EXPORT html
<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
	@cleopatra echo "Building" "coqffi tutorial"
	@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 \
	      2>&1 >> build.log

site/posts/CoqffiEcho.html : coqffi-tutorial-build
literate-programming-build : coqffi-tutorial-build

ARTIFACTS += ${COQFFI_ARCHIVE}
#+END_SRC