From a85c838cb85a2600b418180396c467cbe9eeab52 Mon Sep 17 00:00:00 2001 From: Thomas Letan Date: Sun, 23 Feb 2020 11:20:27 +0100 Subject: First complete draft for the Root of Generation section --- Makefile | 3 ++- site/posts/meta.org | 3 +-- site/posts/meta/Bootstrap.org | 57 ++++++++++++++++++++++++++----------------- 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
site/posts/meta.org
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 <> #+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 -~<>~. +~<>~. The syntax is the following: #+BEGIN_SRC verbatim <> #+END_SRC -This means that modifying code block of ~<>~ 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. <> #+END_SRC +Beware that, as a consequence, modifying code block of ~<>~ 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 -- cgit v1.2.3