From 9cc680e579d575605c0a1ff186ae2b6e5f9ce9da Mon Sep 17 00:00:00 2001 From: Thomas Letan Date: Sat, 29 Feb 2020 08:52:10 +0100 Subject: Continue to work on soupault configuration --- site/cleopatra/Bootstrap.org | 2 +- site/cleopatra/Soupault.org | 264 ++++++++++++++++++++++++++++--------------- 2 files changed, 172 insertions(+), 94 deletions(-) (limited to 'site/cleopatra') 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 -<> +<> #+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 @@

soupault Configuration

#+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 ~<> directory where ~soupault~ generates its output, +and an eventual ~<>~ 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/<>" +build_dir = "<>/<>" 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 #+END_SRC -will replace the content of this ~
~ with the revisions table of +This plugin will replace the content of this ~
~ with the revisions table of ~site/posts/FooBar.org~. +*** Customization + +#+BEGIN_SRC html :tangle templates/history.html :noweb tangle +
+ Revisions +

+ This revisions table has been automatically generated + from the git history + of this website repository, and the change + descriptions may not always be as useful as they + should. +

+ +

+ You can consult the source of this file in its current + version here. +

+ + + {{#history}} + + + + + + {{/history}} +
{{date}}{{subject}} + + {{abbr_hash}} + +
+
+#+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 -
- JSON manipulation operators definition -#+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 -
-#+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 -
- Revisions -

- This revisions table has been automatically generated - from the git history - of this website repository, and the change - descriptions may not always be as useful as they - should. -

- -

- You can consult the source of this file in its current - version here. -

- - - {{#history}} - - - - - - {{/history}} -
{{date}}{{subject}} - - {{abbr_hash}} - -
-
-#+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 +<> +<> +<> +#+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 += <>/ +#+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 <>; 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 ~<>~ +directory exists. The responsibility to use ~make serve~ in a good setting lies +with final users. -- cgit v1.2.3