First complete draft for the Root of Generation section

3 files changed, 37 insertions, 26 deletions

diff --git a/Makefile b/Makefile
index ce4543d..31fe106 100644
--- a/Makefile
+++ b/Makefile
@@ -5,7 +5,8 @@ GENFILES :=
 CONTENTS :=
 GENSASS :=
 
-EMACS := ROOT="${ROOT}" emacs
+EMACSBIN := emacs
+EMACS := ROOT="${ROOT}" ${EMACSBIN}
 TANGLE := --batch --load="${ROOT}/scripts/tangle-org.el" 2>> build.log
 
 default: init-log build
diff --git a/site/posts/meta.org b/site/posts/meta.org
index 918d15b..22f200f 100644
--- a/site/posts/meta.org
+++ b/site/posts/meta.org
@@ -13,10 +13,9 @@ build toolchain, called *~cleopatra~*. The motivations behind this name are
 twofold. First, I wanted to follow the example of [[https://soupault.neocities.org/][~soupault~]], named after [[https://fr.wikipedia.org/wiki/Philippe_Soupault][a
 famous personality]]. Secondly, one of my main objective when I started working on
 this “project” was to be able to easily use whatever format I wanted to author
-my content. Did you know that Cleopatra was a reputed polyglot (at least
+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
 <div id="history">site/posts/meta.org</div>
 <article class="index">
diff --git a/site/posts/meta/Bootstrap.org b/site/posts/meta/Bootstrap.org
index e8d4416..0f3a07e 100644
--- a/site/posts/meta/Bootstrap.org
+++ b/site/posts/meta/Bootstrap.org
@@ -76,12 +76,6 @@ In a nutshell,
   you don’t want that, just move the directory outside the ~site/~ directory,
   and update the ~CLEODIR~ variable accordingly.
 
-- ~EMACS~ ::
-  Tell *~cleopatra~* the command to use to call Emacs. You can modify it to use
-  a custom Emacs you build yourself if you so desire. Note that the command *has
-  to be prefixed by ~ROOT=${ROOT}~, otherwise the source defined in
-  *~cleopatra~* documents will not be tangled in the right places.
-
 For this website, these constants are defined as follows.
 
 #+BEGIN_SRC makefile :tangle Makefile :noweb tangle
@@ -108,13 +102,6 @@ CONTENTS :=
 GENSASS :=
 #+END_SRC
 
-#+BEGIN_REMARK
-One desired feature for *~cleopatra~* would be to let it populate ~GENFILES~ and
-~GENSASS~ automatically, by looking for relevant ~:tangle~ directives. The
-challenge lies in the “relevant” part: the risk exists that we have false
-posivite. Whether or not it is an issue remains an open question.
-#+END_REMARK
-
 ** Easy Tangling of Org Documents
 
 We provide the necessary bits to easily tangle Org documents.
@@ -138,10 +125,12 @@ restore it using ~git~.
 #+END_SRC
 
 We define variables that ensure that the ~ROOT~ environment variable is set and
-~tangle-org.el~ is loaded when using Emacs.
+~tangle-org.el~ is loaded when using Emacs. You can modify ~EMACS~ to use a
+custom Emacs that you build yourself if you so desire.
 
 #+BEGIN_SRC makefile :tangle Makefile :noweb tangle
-EMACS := ROOT="${ROOT}" emacs
+EMACSBIN := emacs
+EMACS := ROOT="${ROOT}" ${EMACSBIN}
 TANGLE := --batch --load="${ROOT}/scripts/tangle-org.el" 2>> build.log
 #+END_SRC
 
@@ -168,17 +157,34 @@ For *(1)*, we rely on a particular behavior of ~make~ regarding the ~include~
 directive. If an operand of ~include~ does not yet exists, ~make~ will search
 for a rule to generate it.
 
+Basically, we are looking for recipes of the following form:
+
 #+BEGIN_SRC makefile :noweb yes
 <<extends(MK="${MK}", MF="${MF}", IN="${IN}", GF="${GF}", GS="${GS}")>>
 #+END_SRC
 
+where
+
+- ~${IN}~ is the input Org document
+- ~${MK}~ lists the tangled Makefiles (typically one, but it could be more)
+- ~${GF}~ lists the tangled scripts
+- ~${GS}~ lists the tangled SASS scripts
+
 ~&:~ is used in place of ~:~ to separate the target from its dependencies in
 this rule to tell to ~make~ that the runned commands will generate all these
 files.
 
-#+BEGIN_TODO
-Introduce ~noweb~ and ~extends~.
-#+END_TODO
+Writing these rules manually —has yours truly had to do in the early days of his
+website— has proven to be error-prone.
+
+One desirable feature for *~cleopatra~* would be to generate them automatically,
+by looking for relevant ~:tangle~ directives inside the input Org document. The
+challenge lies in the “relevant” part: the risk exists that we have false
+posivite. However and as a first steps towards a fully automated solution, we
+can leverage the evaluation features of Babel here.
+
+Here is a bash script which, given the proper variables, would generate the
+expected Makefile rule.
 
 #+NAME: extends
 #+BEGIN_SRC bash :var MK="" :var IN="" :var GF="" :var GS="" :results output
@@ -195,17 +201,18 @@ ${MK} ${GF} ${GS} \\
 EOF
 #+END_SRC
 
+The previous source block is given a name (=extends=), and an explicit lists of
+variables (~IN~, ~MK~, ~GF~, and ~GS~). Thanks to the [[https://orgmode.org/worg/org-tutorials/org-latex-export.html][noweb syntax of Babel]], we
+can insert the result of the evaluation of =extends= inside another source block
+when the latter is tangled.
+
 The twist is, we derive the rule to tangle ~bootstrap.mk~ using
-~<<extends>>~.
+~<<extends>>~. The syntax is the following:
 
 #+BEGIN_SRC verbatim
 <<extends(IN="Bootstrap.org", MK="bootstrap.mk", GF="scripts/update-gitignore.sh")>>
 #+END_SRC
 
-This means that modifying code block of ~<<extends>>~ is as “dangerous” as
-modifying ~Makefile~ itself. Keep that in mind if you start hacking
-*~cleopatra~*!
-
 For purpose of illustrations, here is the snippet generated by Babel from the
 previous source block.
 
@@ -213,6 +220,10 @@ previous source block.
 <<extends(IN="Bootstrap.org", MK="bootstrap.mk", GF="scripts/update-gitignore.sh")>>
 #+END_SRC
 
+Beware that, as a consequence, modifying code block of ~<<extends>>~ is as
+“dangerous” as modifying ~Makefile~ itself. Keep that in mind if you start
+hacking *~cleopatra~*!
+
 From now on, the bootstrap process is completed: further generation processes
 will fully be defined using literate programming, with no special treatment for
 its output. For instance, you may not want to use ~soupault~? You can! Just