Improving the end of the Bootstrapping cleopatra document

5 files changed, 44 insertions, 8 deletions

diff --git a/site/cleopatra/Bootstrap.org b/site/cleopatra/Bootstrap.org
index 37124cb..67073a5 100644
--- a/site/cleopatra/Bootstrap.org
+++ b/site/cleopatra/Bootstrap.org
@@ -10,9 +10,9 @@ place both the software program and its technical documentation.
 That being said, *~cleopatra~* is a toolchain to build a website before being a
 literate program, and one of its objective is to be /part of this very website
 it is used to generate/. To acheive this, *~cleopatra~* has been written as a
-collection of org files which can be either “tangled” using [[https://orgmode.org/worg/org-contrib/babel/][Babel]] or “exported”
-as a HTML document. Tangling here refers to extracted marked code blocks into
-files.
+collection of org files which can be either “tangled” using
+[[https://orgmode.org/worg/org-contrib/babel/][Babel]] or “exported” as a HTML
+document. Tangling here refers to extracted marked code blocks into files.
 
 The page you are currently reading is *~cleopatra~* entry point. Its primilarly
 purpose is to introduce two Makefiles: ~Makefile~ and ~bootstrap.mk~.
@@ -287,12 +287,46 @@ are currently used to generate the website you are reading.
 
 *** 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 tangle :exports none
 <<extends(IN="Theme.org", PROC="theme", AUX="templates/main.html site/style/main.sass")>>
 #+END_SRC
 
 *** Configuring Soupault
 
+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 tangle :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")>>
 #+END_SRC
diff --git a/site/cleopatra/Contents/Coq.org b/site/cleopatra/Contents/Coq.org
index ee12806..a792ef9 100644
--- a/site/cleopatra/Contents/Coq.org
+++ b/site/cleopatra/Contents/Coq.org
@@ -8,7 +8,7 @@ COQ_HTML := $(COQ_POSTS:.v=.html)
 
 coq-build : ${COQ_HTML}
 
-themepre-build : site/style/coq.sass
+theme-build : site/style/coq.sass
 soupault-build : coq-build
 
 ARTIFACTS += *.vo *.vok *.vos .*.aux *.glob .lia.cache
diff --git a/site/cleopatra/Contents/Org.org b/site/cleopatra/Contents/Org.org
index 385d2d3..cdb0ad6 100644
--- a/site/cleopatra/Contents/Org.org
+++ b/site/cleopatra/Contents/Org.org
@@ -63,7 +63,7 @@ ORG_HTML := $(ORG_POSTS:.org=.html)
 org-prebuild : .emacs
 org-build : ${ORG_HTML}
 
-theme-prebuild : site/style/org.sass
+theme-build : site/style/org.sass
 soupault-build : org-build
 
 ARTIFACTS += ${ORG_HTML} "*.html~"
diff --git a/site/cleopatra/Soupault.org b/site/cleopatra/Soupault.org
index cd461bb..f8e57b0 100644
--- a/site/cleopatra/Soupault.org
+++ b/site/cleopatra/Soupault.org
@@ -13,7 +13,7 @@ serve : build
 	@echo "   start  a python server"
 	@cd build; python -m http.server 2>/dev/null
 
-theme-prebuild : site/style/plugins.sass
+theme-build : site/style/plugins.sass
 
 ARTIFACTS += build/
 #+END_SRC
diff --git a/site/cleopatra/index.org b/site/cleopatra/index.org
index a71b67c..03ce34d 100644
--- a/site/cleopatra/index.org
+++ b/site/cleopatra/index.org
@@ -31,11 +31,13 @@ expected. Its “literate” part still requires some work, though.
   is part of this very website. This means *~cleopatra~* is bootstrapped: it
   generates iteself.
 
-- [[./Contents.org][Authoring Content and HTML Generation ~(WIP)~]] ::
+- [[./Contents/Org.org][Generating Contents from Org Documents ~(TODO)~]] ::
+
+- [[./Contents/Coq.org][Generating Contents from Coq Documents ~(TODO)~]] ::
 
 - [[./Soupault.org][Soupault Configuration ~(WIP)~]] ::
 
-- [[./Theme.org][Theming and Templating ~(WIP)~]] ::
+- [[./Theme.org][Theming and Templating ~(TODO)~]] ::
 
 #+BEGIN_EXPORT html
 </article>