Refactor the build process to use cleopatra the Second

9 files changed, 121 insertions, 165 deletions

diff --git a/site/cleopatra.org b/site/cleopatra.org
new file mode 100644
index 0000000..645b794
--- /dev/null
+++ b/site/cleopatra.org
@@ -0,0 +1,56 @@
+#+BEGIN_EXPORT html
+<h1><code>cleopatra</code></h1>
+#+END_EXPORT
+
+The generation of this website is far from being trivial, and requires the
+combination of —probably too— many tools. For instance, my write-ups about Coq
+are actually Coq files, and I use ~coqdoc~ to generate the HTML pages you read.
+The theme is not written in CSS, but in SASS that needs to be compiled.  Even
+more, the whole website is postprocessed using ~soupault~.
+
+At some point, I felt like the whole process was interesting enough so that it
+would deserve a write-up of its own, but the risk was that such a piece of text
+would quickly become out-dated. This is reminescent of documenting any software
+project, and I was aware at that time of a dedicated paradigm to prevent these
+kind of issues: [[http://www.literateprogramming.com/][literate programming]].
+I spent quite some time turning my custom toolchain into a literate program, so
+that its actual code source would actually be the write-ups I wanted to add to
+my website. This was an interesting challenge, since it meant *~cleopatra~*
+would have to generate itself before it could build my website. In other words,
+*~cleopatra~* achieves the bootstsrapping challenge!
+
+I really enjoyed this first experiment with literate programming, and I started
+using *~cleopatra~* for other projects of mine where literate programming felt
+like an interesting choice. In doing so, it quickly became clear *~cleopatra~*
+was cumbersome to set-up for a new project. At the end,
+[[https://cleopatra.soap.coffee][I ended up rewriting it]] to overcome the
+specific issues posed by its initial design[fn:bootstrap]. But the so-called
+generation processes I had written for *~cleopatra~* the first basically “just
+worked” with *~cleopatra~* the second.
+
+So, coming back to this series, it is just the very reason why I started using
+*~cleopatra~* in the first place: the generation processes used by this website,
+written as literate programs.
+
+#+BEGIN_EXPORT html
+<article class="index">
+#+END_EXPORT
+
+- [[file:cleopatra/coq.org][Authoring Contents As Coq Documents ~(TODO)~]] ::
+
+- [[./cleopatra/org.org][Authoring Contents As Org Documents ~(TODO)~]] ::
+
+- [[./cleopatra/theme.org][Theming with SASS ~(TODO)~]] ::
+
+- [[./cleopatra/soupault.org][Processing HTML with ~soupault~]] ::
+  ~soupault~ is a HTML processor, and it can be used as a static website
+  generator. We leverage *~soupault~* to provide a unified look and feel to a
+  website generated with diverse tools.
+
+#+BEGIN_EXPORT html
+</article>
+#+END_EXPORT
+
+[fn:bootstrap] For the record, this second version is also implemented using
+literate programming, and if I was first using the first version to build it, I
+quickly “made the bootstrap jump.”
diff --git a/site/cleopatra/Contents.org b/site/cleopatra/Contents.org
deleted file mode 100644
index 0863709..0000000
--- a/site/cleopatra/Contents.org
+++ /dev/null
@@ -1,3 +0,0 @@
-#+BEGIN_EXPORT html
-<h1>Authoring Contents and HTML Generation</h1>
-#+END_EXPORT
diff --git a/site/cleopatra/Contents/Coq.org b/site/cleopatra/coq.org
index 893efab..a657fcf 100644
--- a/site/cleopatra/Contents/Coq.org
+++ b/site/cleopatra/coq.org
@@ -21,7 +21,7 @@ COQDOCARG := --no-index --charset utf8 --short \
              --body-only --coqlib "${COQLIB}"
 
 %.html : %.v coq.mk
-	@echo "  export  $*.v"
+	@cleopatra echo Exporting "$*.v"
 	@coqc ${COQCARG} $<
 	@coqdoc ${COQDOCARG} -d $(shell dirname $<) $<
 	@rm -f $(shell dirname $<)/coqdoc.css
diff --git a/site/cleopatra/index.org b/site/cleopatra/index.org
deleted file mode 100644
index 9bf2e68..0000000
--- a/site/cleopatra/index.org
+++ /dev/null
@@ -1,47 +0,0 @@
-#+BEGIN_EXPORT html
-<h1><code>cleopatra</code></h1>
-#+END_EXPORT
-
-The generation of [[https://soap.coffee/~lthms][my personal website]] is far from being trivial, and requires a
-combination of —probably too— many tools. It turned out that some choices I have
-made early on gave to the build toolchain I ended up writing a pretty nice
-property: I could easily integrate its code to the very website it was conceived
-to build, by means of [[http://www.literateprogramming.com/][literate programming]]!
-
-The document you are reading is just that: the literate program of my home-grown
-build toolchain ---called *~cleopatra~*---. The motivations behind this name are
-twofold.
-
-- I wanted to follow the example of [[https://soupault.neocities.org/][~soupault~]], named after [[https://fr.wikipedia.org/wiki/Philippe_Soupault][a famous personality]].
-- My main objective when I started working on this “project” was to be able to
-  easily use whatever format I wanted to author my contents. Did you know that
-  Cleopatra was a reputed polyglot (at least according to [[https://fr.wikipedia.org/wiki/Polyglotte][Wikipedia France]])?
-
-#+BEGIN_EXPORT html
-<article class="index">
-#+END_EXPORT
-
-#+BEGIN_TODO
-*~cleopatra~* is a literate program whose “program” part is working as
-expected. Its “literate” part still requires some work, though.
-#+END_TODO
-
-- [[./Bootstrap.org][Bootstrapping an Extensible Toolchain]] ::
-  *~cleopatra~* is an extensible toolchain that builds a static website /and/ it
-  is part of this very website. This means *~cleopatra~* is bootstrapped: it
-  generates iteself.
-
-- [[./Soupault.org][~soupault~ Configuration]] ::
-  ~soupault~ is a HTML processor, and it can be used as a static website
-  generator. This is the approach used for this very website, and this document
-  is the literate program of the dedicated *~cleopatra~* generation process.
-
-- [[./Contents/Org.org][Generating Contents from Org Documents ~(TODO)~]] ::
-
-- [[./Contents/Coq.org][Generating Contents from Coq Documents ~(TODO)~]] ::
-
-- [[./Theme.org][Theming and Templating ~(TODO)~]] ::
-
-#+BEGIN_EXPORT html
-</article>
-#+END_EXPORT
diff --git a/site/cleopatra/Contents/Org.org b/site/cleopatra/org.org
index bd107fc..bab4dc9 100644
--- a/site/cleopatra/Contents/Org.org
+++ b/site/cleopatra/org.org
@@ -32,6 +32,7 @@
 (use-package org :ensure t)
 (use-package htmlize :ensure t)
 (use-package lua-mode :ensure t :defer t)
+(use-package rust-mode :ensure t :defer t)
 (use-package sass-mode :ensure t :defer t)
 (use-package haskell-mode :ensure t :defer t)
 (use-package toml-mode :ensure t :defer t)
@@ -53,6 +54,7 @@
 (setq org-src-fontify-natively t)
 (setq org-confirm-babel-evaluate nil)
 (setq org-export-with-toc nil)
+(setq org-export-with-sub-superscripts nil)
 
 (add-to-list 'org-entities-user
              '("im" "\\(" nil "<span class=\"imath\">" "" "" ""))
@@ -94,6 +96,12 @@
 #+END_SRC
 
 #+BEGIN_SRC makefile :tangle org.mk
+EMACSBIN := emacs
+EMACS := ROOT="${ROOT}" ${EMACSBIN}
+TANGLE := --batch \
+          --load="${ROOT}/scripts/tangle-org.el" \
+          2>> build.log
+
 ORG_POSTS := $(shell find site/ -name "*.org")
 ORG_HTML := $(ORG_POSTS:.org=.html)
 
@@ -113,13 +121,13 @@ INIT := --batch --load="${ROOT}/scripts/packages.el" \
         2>> build.log
 
 .emacs : scripts/packages.el
-	@echo "    init  emacs configuration"
+	@cleopatra echo Initiating  "Emacs configuration"
 	@${EMACS} ${INIT}
 	@touch .emacs
 
 %.html : %.org scripts/packages.el scripts/export-org.el \
          .emacs org.mk
-	@echo "  export  $*.org"
+	@cleopatra echo Exporting "$*.org"
 	@${EMACS} $< ${EXPORT}
 #+END_SRC
 
diff --git a/site/cleopatra/Soupault.org b/site/cleopatra/soupault.org
index 5ad51d6..dd90daf 100644
--- a/site/cleopatra/Soupault.org
+++ b/site/cleopatra/soupault.org
@@ -130,7 +130,7 @@ numbered_list = true
 #+END_SRC
 
 #+BEGIN_TODO
-Propose a patch to ~soupault~'s upstream to add numbering in titles.
+We could propose a patch to ~soupault~'s upstream to add numbering in titles.
 #+END_TODO
 
 ** Fixing Org Internal Links
@@ -140,8 +140,9 @@ For some reason, Org prefix internal links to other Org documents with
 from the begining of a URL.
 
 #+BEGIN_TODO
-This file should be part of ~Org.org~, but that would require to aggregate
-“subconfig” into a larger one.
+This plugin definition should be part of [[./Contents/Org.org][the ~org~
+generation process]], but that would require to aggregate “subconfig” into a
+larger one.
 #+END_TODO
 
 This plugin key component is the =fix_org_urls= function.
@@ -652,9 +653,11 @@ mode. Currently, only inline mode is supported.
 var katex = require("katex");
 var fs = require("fs");
 var input = fs.readFileSync(0);
+var displayMode = process.env.DISPLAY != undefined;
 
 var html = katex.renderToString(String.raw`${input}`, {
-    throwOnError: false
+    throwOnError : false,
+    displayModed : displayMode
 });
 
 console.log(html)
@@ -670,14 +673,23 @@ widget = "preprocess_element"
 selector = ".imath"
 command = "node scripts/katex.js"
 action = "replace_content"
+
+[widgets.display-math]
+widget = "preprocess_element"
+selector = ".dmath"
+command = "DISPLAY=1 node scripts/katex.js"
+action = "replace_content"
 #+END_SRC
 
 The \im\KaTeX\mi font is bigger than the serif font used for this
 website, so we reduce it a bit with a dedicated SASS rule.
 
 #+BEGIN_SRC sass :tangle site/style/plugins.sass
-.imath
-  font-size: smaller
+.imath, .dmath
+  font-size : smaller
+
+.dmath
+  text-align : center
 #+END_SRC
 
 * *~cleopatra~* Generation Process Definition
@@ -703,8 +715,9 @@ single (configurable) directory.
 #+NAME: stages
 #+BEGIN_SRC makefile :noweb no-export
 soupault-build :
-	@echo "     run  soupault"
+	@cleopatra echo Running  soupault
 	@soupault
+
 ARTIFACTS += <<build-dir>>/
 #+END_SRC
 
diff --git a/site/cleopatra/Theme.org b/site/cleopatra/theme.org
index 41faa8b..3bba6b7 100644
--- a/site/cleopatra/Theme.org
+++ b/site/cleopatra/theme.org
@@ -7,7 +7,7 @@ SASS := site/style/main.sass
 CSS := $(SASS:.sass=.css)
 
 theme-build : ${SASS}
-	@echo " compile  ${CSS}"
+	@cleopatra echo Compiling  "${CSS}"
 	@sassc --style=compressed --sass ${SASS} ${CSS}
 
 soupault-build : theme-build
diff --git a/site/index.org b/site/index.org
index 0a5a9f8..749877b 100644
--- a/site/index.org
+++ b/site/index.org
@@ -73,22 +73,27 @@ One of my goal with this website is for it to /feel/ simple, but the truth is
 under the hood it is generated from a bunch of files using a not-that-simple
 process.
 
-- [[/cleopatra/][A Series on Generating this Static Website]] ::
-  The toolchain behind the generation of this website ---called *~cleopatra~*---
-  is a literate program which build itself in addition to the HTML files
-  composing this corner of the Internet. This series /is/ *~cleopatra~*.
-
-  1. [[/cleopatra/Bootstrap.html][Bootstrapping an Extensible Toolchain]]
-  2. [[/cleopatra/Soupault.html][~soupault~ Configuration]]
-  3. [[/cleopatra/Contents/Org.org][Generating Contents from Org Documents ~(TODO)~]]
-  4. [[/cleopatra/Contents/Coq.org][Generating Contents from Coq Documents ~(TODO)~]]
-  5. [[/cleopatra/Theme.html][Theming and Templating ~(TODO)~]]
+- [[./cleopatra.html][A Series on Generating this Static Website]] ::
+  This series consolidates the [[https://cleopatra.soap.coffee][*~cleopatra~*]]
+  generation processes used to build this website. That is, each write-up is a
+  literate program responsible for a particular step of the build process, and
+  you are guaranteed that the code you read is the code that has been used to
+  generate the HTML page you read it from.
+
+  1. [[./cleopatra/coq.org][Authoring Contents As Coq Documents ~(TODO)~]]
+  2. [[./cleopatra/org.org][Authoring Contents As Org Documents ~(TODO)~]]
+  3. [[./cleopatra/theme.org][Theming with SASS ~(TODO)~]]
+  4. [[./cleopatra/soupault.org][Processing HTML with ~soupault~]]
 
 - [[./posts/Thanks.html][Thanks!]] ::
   If it were not for many awesome FOSS projects, this corner of the Internet
   would not exist. This is my attempt to give well-deserved credit to them and
   their creators.
 
+- [[./posts/CleopatraV1.html][*~cleopatra~* the First]] ::
+  This write-up is the literate program of the first version of *~cleopatra~*,
+  before it became a command-line program implemented in Rust.
+
 #+BEGIN_EXPORT html
 </article>
 #+END_Export
diff --git a/site/cleopatra/Bootstrap.org b/site/posts/CleopatraV1.org
index 0a2f821..349e237 100644
--- a/site/cleopatra/Bootstrap.org
+++ b/site/posts/CleopatraV1.org
@@ -1,7 +1,16 @@
 #+BEGIN_EXPORT html
-<h1>Bootstrapping an Extensible Toolchain</h1>
+<h1><strong><code>cleopatra</code></strong>: Bootstrapping an Extensible Toolchain</h1>
 #+END_EXPORT
 
+#+BEGIN_TODO
+You are about to read the first version of *~cleopatra~*, the toolchain
+initially implemented to build the website you are reading. Since then,
+*~cleopatra~* has been completely rewritten as a
+[[https://cleopatra.soap.coffee][independant, more generic command-line
+program]]. That being said, the build process described in this write-up remains
+the one implemented in *~cleopatra~* the Second.
+#+END_TODO
+
 A literate program is a particular type of software program where code is not
 directly written in source files, but rather in text document as code
 snippets. In some sense, literate programming allows for writing in the same
@@ -19,8 +28,6 @@ purpose is to introduce two Makefiles: ~Makefile~ and ~bootstrap.mk~.
 
 #+TOC: headlines 2
 
-* The Root of Generation
-
 ~Makefile~ serves two purposes: it initiates a few global variables, and it
 provides a rule to generate ~bootstrap.mk~.  At this point, some readers may
 wonder /why/ we need ~Makefile~ in this context, and the motivation behind this
@@ -45,7 +52,7 @@ For readers interested in using *~cleopatra~* for their own websites, this
 documents tries to highlight the potential modifications they would have to
 make.
 
-** Global Constants and Variables
+* Global Constants and Variables
 
 First, ~Makefile~ defines several global “constants” (although as far as I know
 ~make~ does not support true constant values, it is expected further generation
@@ -91,7 +98,7 @@ CONFIGURE :=
 Generation processes shall declare new build outputs using the ~+=~ assignement
 operators. Using another operator will likely provent an underisable result.
 
-** Easy Tangling of Org Documents
+* Easy Tangling of Org Documents
 
 *~cleopatra~* is a literate program implemented with Org mode, an Emacs major
 editing mode. We provide the necessary bits to easily tangle Org documents.
@@ -138,7 +145,7 @@ ${EMACS} $< ${TANGLE}
 endef
 #+END_SRC
 
-** Bootstrapping
+* Bootstrapping
 
 The core purpose of ~Makefile~ remains to bootstrap the chain of generation
 processes. This chain is divided into three stages: ~prebuild~, ~build~, and
@@ -268,98 +275,15 @@ this section, we first detail the structure of a typical generation process.
 Then, we construct ~bootstrap.mk~ by enumerating the generation processes that
 are currently used to generate the website you are reading.
 
-** Getting Started
-
-#+BEGIN_TODO
-1. Defining ~proc-prebuild~, ~proc-build~, and ~proc-postbuild~
-2. Declaring dependencies between stages of generation processes
-3. Declaring build outputs (see ~ARTIFACTS~ and ~CONFIGURE~)
-#+END_TODO
-
-** Active Generation Processes
-
-*** Theming and Templating
-
-The [[./Theme.org][~theme~]] generation process controls the general appearance
-of the website.  More precisely, it introduces the main template used by
-~soupault~ (~main/templates.html~), and the main SASS sheet used by this
-template.
-
-If a generation process produces a set of styles within a specific SASS files,
-the current approach is
-
-1. To make this file a dependency of ~theme-build~
-2. To modify ~style/main.sass~ in ~theme~
-   to import this file
-
-#+BEGIN_TODO
-Eventually, the second step will be automated, but in the meantime
-this customization is mandatory.
-#+END_TODO
-
-#+BEGIN_SRC makefile :tangle bootstrap.mk :noweb yes :exports none
-<<extends(IN="Theme.org", PROC="theme", AUX="templates/main.html site/style/main.sass")>>
-#+END_SRC
+Each generation process shall
 
-*** Configuring Soupault
+1. Define ~proc-prebuild~, ~proc-build~, and ~proc-postbuild~
+2. Declare dependencies between stages of generation processes
+3. Declare build outputs (see ~ARTIFACTS~ and ~CONFIGURE~)
 
-The [[./Soupault.org][~soupault~]] generation configures and run ~soupault~, in
-order to generate a static website.
-
-If a generation process ~proc~ produces files that will eventually be integrated to
-your website, its ~proc-build~ recipe needs to be executed /before/ the
-~soupault-build~ recipe. This can be enforced by making the dependency explicit
-to ~make~, /i.e./,
-
-#+BEGIN_SRC makefile
-soupault-build : proc-build
-#+END_SRC
-
-#+BEGIN_TODO
-Eventually, generation processes shall be allowed to produce specific ~soupault~
-widgets to be integrated into ~soupault.conf~.
-#+END_TODO
-
-#+BEGIN_SRC makefile :tangle bootstrap.mk :noweb yes :exports none
-<<extends(IN="Soupault.org", PROC="soupault", AUX="soupault.conf plugins/urls-rewriting.lua plugins/external-urls.lua site/style/plugins.sass scripts/history.sh templates/history.html package.json scripts/katex.js katex.mk")>>
-#+END_SRC
-
-*** Authoring Contents
-
-The fact that *~cleopatra~* is a literate program which gradually generates
-itself was not intended: it is a consequence of my desire to be able to easily
-use whatever format I so desire for writing my contents, and Org documents in
-particular.
-
-In the present website, contents can be written in the following format:
-
-- HTML Files ::
-  This requires no particular set-up, since HTML is the /lingua franca/ of
-  ~soupault~.
-- Regular Coq files ::
-  Coq is a system which allows to write machine-checked proofs, and it comes
-  with a source “prettifier” called ~coqdoc~.  [[./Contents/Coq.org][Learn more
-  about the generation process for Coq files​]]
-- Org documents ::
-  Emacs comes with a powerful editing mode called [[https://orgmode.org/][Org
-  mode]], and Org documents are really pleasant to work with.
-  [[./Contents/Org.org][Learn more about the generation process for Org
-  documents]]
-
-#+BEGIN_SRC makefile :tangle bootstrap.mk :noweb yes :exports none
-<<extends(IN="Contents/Coq.org", PROC="coq", AUX="site/style/coq.sass")>>
-<<extends(IN="Contents/Org.org", PROC="org", AUX="scripts/packages.el scripts/export-org.el site/style/org.sass")>>
-#+END_SRC
-
-** Wrapping-up
-
-#+BEGIN_TODO
-~clean~ and ~cleanall~ should probably follow a similar approach than the build
-stages.
-#+END_TODO
+* Wrapping-up
 
 #+BEGIN_SRC bash :tangle scripts/update-gitignore.sh :shebang "#+/bin/bash"
-
 BEGIN_MARKER="# begin generated files"
 END_MARKER="# begin generated files"