Continue to work on soupault configuration

2 files changed, 172 insertions, 94 deletions

diff --git a/site/cleopatra/Bootstrap.org b/site/cleopatra/Bootstrap.org
index b1a76ff..0a2f821 100644
--- a/site/cleopatra/Bootstrap.org
+++ b/site/cleopatra/Bootstrap.org
@@ -321,7 +321,7 @@ 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")>>
+<<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
diff --git a/site/cleopatra/Soupault.org b/site/cleopatra/Soupault.org
index 79faa34..45ad5d6 100644
--- a/site/cleopatra/Soupault.org
+++ b/site/cleopatra/Soupault.org
@@ -2,36 +2,45 @@
 <h1><code>soupault</code> Configuration</h1>
 #+END_EXPORT
 
-#+TOC: headlines 2
-
-#+BEGIN_SRC makefile :tangle soupault.mk
-soupault-build :
-	@echo "     run  soupault"
-	@soupault
-
-serve : soupault-prebuild
-	@echo "   start  a python server"
-	@cd build; python -m http.server 2>/dev/null
+In a nutshell, the purpose of ~soupault~ is to post-process HTML files generated
+by the generation processes of *~cleopatra~*. It is parameterized by two
+settings, the ~<<build-dir>> directory where ~soupault~ generates its output,
+and an eventual ~<<subdir>>~ wherein the website contents lives. The latter
+allows to generate only a subpart of a larger website.
 
-theme-build : site/style/plugins.sass
+For the present website, these two settings are initialized as follows.
 
-ARTIFACTS += build/
+#+NAME: build-dir
+#+BEGIN_SRC text
+build
 #+END_SRC
 
-* General Settings
-
 #+NAME: prefix
 #+BEGIN_SRC text
 ~lthms
 #+END_SRC
 
+The rest of this document proceeds as follows. We first describe the general
+settings of ~soupault~. Then, we enumerate the widgets enabled for this website.
+Finally, we provide a proper definition for ~soupault~ the *~cleopatra~*
+generation process.
+
+#+TOC: headlines 2
+
+* ~soupault~ General Settings
+
+#+BEGIN_TODO
+The list of ignored extensions should be programmatically generated with the
+help of *~cleopatra~*.
+#+END_TODO
+
 #+BEGIN_SRC toml :tangle soupault.conf :noweb tangle
 [settings]
 strict = true
 verbose = false
 debug = false
 site_dir = "site"
-build_dir = "build/<<prefix>>"
+build_dir = "<<build-dir>>/<<prefix>>"
 
 page_file_extensions = ["html"]
 ignore_extensions = [
@@ -71,7 +80,8 @@ determine the version of ~soupault~ with the following script.
 soupault --version | head -n 1 | tr -d '\n'
 #+END_SRC
 
-The configuration of the widget becomes
+The configuration of the widget ---initially provided by ~soupault~--- becomes
+less subject to the obsolescence.
 
 #+BEGIN_SRC toml :tangle soupault.conf :noweb tangle
 [widgets.generator-meta]
@@ -215,11 +225,76 @@ For instance, considering the following HTML snippet
 </div>
 #+END_SRC
 
-will replace the content of this ~<div>~ with the revisions table of
+This plugin will replace the content of this ~<div>~ with the revisions table of
 ~site/posts/FooBar.org~.
 
+*** Customization
+
+#+BEGIN_SRC html :tangle templates/history.html :noweb tangle
+<details class="history">
+  <summary>Revisions</summary>
+  <p>
+    This revisions table has been automatically generated
+    from <a href="<<repo>>">the <code>git</code> history
+    of this website repository</a>, and the change
+    descriptions may not always be as useful as they
+    should.
+  </p>
+
+  <p>
+    You can consult the source of this file in its current
+    version <a href="<<repo>>/tree/{{file}}">here</a>.
+  </p>
+
+  <table>
+  {{#history}}
+  <tr>
+    <td class="date">{{date}}</a></td>
+    <td class="subject">{{subject}}</a></td>
+    <td class="commit">
+      <a href="<<repo>>/commit/{{filename}}/?id={{hash}}">
+        {{abbr_hash}}
+      </a>
+    </td>
+  </tr>
+  {{/history}}
+  </table>
+</details>
+#+END_SRC
+
+#+BEGIN_SRC sass :tangle site/style/plugins.sass
+#history
+  table
+    @include margin-centered(2rem)
+    border-top: 2px solid $primary-color
+    border-bottom: 2px solid $primary-color
+    border-collapse: collapse;
+
+  td
+    border-bottom: 1px solid $primary-color
+    padding: .5em
+    vertical-align: top
+
+  td.commit
+    font-size: smaller
+
+  td.commit
+    font-family: 'Fira Code', monospace
+    color: $code-fg-color
+    font-size: 80%
+    white-space: nowrap;
+#+END_SRC
+
 *** Implementations Details
 
+#+BEGIN_SRC toml :tangle soupault.conf
+[widgets.generate-history]
+widget = "preprocess_element"
+selector = "#history"
+command = 'scripts/history.sh templates/history.html'
+action = "replace_content"
+#+END_SRC
+
 #+BEGIN_TODO
 This plugin should be reimplemented using ~libgit2~ or other ~git~ libraries, in
 a language more suitable than bash.
@@ -267,11 +342,6 @@ function. We define the three operations our revisions history script uses:
 - =jappend ARRAY VALUE= ::
   Append a =VALUE= at the end of an =ARRAY=
 
-#+BEGIN_EXPORT html
-<details>
-  <summary>JSON manipulation operators definition</summary>
-#+END_EXPORT
-
 We use [[https://stedolan.github.io/jq/][~jq~]] to manipulate JSON data. Since
 ~jq~ processes JSON from its standard input, we first define a helper =_jq=
 to deal with JSON from variables seamlessly.
@@ -315,22 +385,29 @@ function jappend () {
 }
 #+END_SRC
 
-#+BEGIN_EXPORT html
-</details>
-#+END_EXPORT
+Besides JSON manipulation, we will use ~git~ to get the information we need. By
+default, ~git~ subcommands use a pager when its output is likely to be
+long. This typically includes ~git-log~. To disable this behavior, ~git~ exposes
+the ~--no-pager~ command.
 
 #+BEGIN_SRC bash :tangle scripts/history.sh
 function _git () {
   git --no-pager "$@"
 }
+#+END_SRC
+
+Afterwards, we use =_git= in place of ~git~.
 
+#+BEGIN_SRC bash :tangle scripts/history.sh
 FORMAT='{'\
 '  "subject" : "%s",'\
 '  "abbr_hash" : "%h",'\
 '  "hash" : "%H",'\
 '  "date" : "%cs"'\
 '}'
+#+END_SRC
 
+#+BEGIN_SRC bash :tangle scripts/history.sh
 function generate_json () {
   local file="${1}"
   local logs=$(_git log \
@@ -384,69 +461,6 @@ Everything is defined. We can call =main= now.
 main "$(cat)" "${1}"
 #+END_SRC
 
-#+BEGIN_SRC html :tangle templates/history.html :noweb tangle
-<details class="history">
-  <summary>Revisions</summary>
-  <p>
-    This revisions table has been automatically generated
-    from <a href="<<repo>>">the <code>git</code> history
-    of this website repository</a>, and the change
-    descriptions may not always be as useful as they
-    should.
-  </p>
-
-  <p>
-    You can consult the source of this file in its current
-    version <a href="<<repo>>/tree/{{file}}">here</a>.
-  </p>
-
-  <table>
-  {{#history}}
-  <tr>
-    <td class="date">{{date}}</a></td>
-    <td class="subject">{{subject}}</a></td>
-    <td class="commit">
-      <a href="<<repo>>/commit/{{filename}}/?id={{hash}}">
-        {{abbr_hash}}
-      </a>
-    </td>
-  </tr>
-  {{/history}}
-  </table>
-</details>
-#+END_SRC
-
-#+BEGIN_SRC sass :tangle site/style/plugins.sass
-#history
-  table
-    @include margin-centered(2rem)
-    border-top: 2px solid $primary-color
-    border-bottom: 2px solid $primary-color
-    border-collapse: collapse;
-
-  td
-    border-bottom: 1px solid $primary-color
-    padding: .5em
-    vertical-align: top
-
-  td.commit
-    font-size: smaller
-
-  td.commit
-    font-family: 'Fira Code', monospace
-    color: $code-fg-color
-    font-size: 80%
-    white-space: nowrap;
-#+END_SRC
-
-#+BEGIN_SRC toml :tangle soupault.conf
-[widgets.generate-history]
-widget = "preprocess_element"
-selector = "#history"
-command = 'scripts/history.sh templates/history.html'
-action = "replace_content"
-#+END_SRC
-
 ** Rendering Equations Offline
 
 *** Users instructions
@@ -477,18 +491,14 @@ We introduce a Makefile recipe to call ~npm install~. This command produces a
 file called ~package-lock.json~ that we add to ~GENFILES~ to ensure \im \KaTeX
 \mi will be available when ~soupault~ is called.
 
-#+BEGIN_REMARK
 If ~Soupault.org~ has been modified since the last generation, Babel will
 generate ~package.json~ again. However, if the modifications of ~Soupault.org~
 do not concern ~package.json~, then ~npm install~ will not modify
 ~package-lock.json~ and its “last modified” time will not be updated. This means
 that the next time ~make~ will be used, it will replay this recipe again. As a
 consequence, we systematically ~touch~ ~packase-lock.json~ to satisfy ~make~.
-#+END_REMARK
-
-#+BEGIN_SRC makefile :tangle soupault.mk
-soupault-prebuild : package-lock.json
 
+#+BEGIN_SRC makefile :tangle katex.mk
 package-lock.json : package.json
 	@echo "    init  npm packages"
 	@npm install &>> build.log
@@ -537,3 +547,71 @@ website, so we reduce it a bit with a dedicated SASS rule.
 .imath
   font-size: smaller
 #+END_SRC
+
+* *~cleopatra~* Generation Process Definition
+
+We introduce the ~soupault~ generation process, obviously based on the
+[[https://soupault.neocities.org/][~soupault~ HTML processor]]. The structure of
+a *~cleopatra~* generation process is always the same.
+
+#+BEGIN_SRC mkefile :tangle soupault.mk :noweb no-export
+<<stages>>
+<<dependencies>>
+<<ad-hoc-cmds>>
+#+END_SRC
+
+In the rest of this section, we define these three components.
+
+** Build Stages
+
+From the perspective of *~cleopatra~*, it is a rather simple component, since
+the ~build~ stage is simply a call to ~soupault~, whose outputs are located in a
+single (configurable) directory.
+
+#+NAME: stages
+#+BEGIN_SRC makefile :noweb no-export
+soupault-build :
+	@echo "     run  soupault"
+	@soupault
+ARTIFACTS += <<build-dir>>/
+#+END_SRC
+
+** Dependencies
+
+Most of the generation processes (if not all of them) need to declare themselves
+as a prerequisite for ~soupault-build~. If they do not, they will likely be
+executed after ~soupault~ is called.
+
+This file defines an auxiliary SASS sheet that needs to be declared as a
+dependency of the build stage of the [[./Theme.org][~theme~ generation
+process]].
+
+Finally, the offline rendering of equations requires \im \KaTeX \mi to be
+available, so we include the ~katex.mk~ file, and make ~package-lock.json~ (the
+proof that ~npm install~ has been executed) a prerequisite of ~soupault-build~.
+
+#+NAME: dependencies
+#+BEGIN_SRC makefile
+theme-build : site/style/plugins.sass
+include katex.mk
+soupault-build : package-lock.json
+#+END_SRC
+
+** Ad-hoc Commands
+
+Finally, this generation process introduces a dedicated (~PHONY~) command to
+start a HTTP server in order to navigate the generated website from a browser.
+
+#+NAME: ad-hoc-cmds
+#+BEGIN_SRC makefile
+serve :
+	@echo "   start  a python server"
+	@cd <<build-dir>>; python -m http.server 2>/dev/null
+
+.PHONY : serve
+#+END_SRC
+
+This command does not assume anything about the current state of generation of
+the project. In particular, it does not check whether or not the ~<<build-dir>>~
+directory exists. The responsibility to use ~make serve~ in a good setting lies
+with final users.