Un générateur de site statique - retour accueil
git clone git://bebou.netlib.re/catium
Log | Files | Refs | README |
commit 643192f108cb083bef9722894181f10a1ebb4d4b parent ccac239e717957f352b831f4780c98a74ebb096c Auterice: Arthur Pons <arthur.pons@unistra.fr> Date: Sun, 29 Sep 2024 14:17:49 +0200 MAJ doc suite à publication du site Diffstat:
| M | CONSTRUIRE | | | 591 | +++++++++++++++++++++++++++++++++++++++---------------------------------------- |
| A | HISTOIRE | | | 177 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| M | README | | | 513 | +------------------------------------------------------------------------------ |
| M | USAGE | | | 169 | +++++++++++++++++++++++++++++++++++++++++-------------------------------------- |
4 files changed, 553 insertions(+), 897 deletions(-)
diff --git a/CONSTRUIRE b/CONSTRUIRE @@ -1,12 +1,12 @@ # Comment vous aussi vous auriez pu construire catium -Imaginez vouloir construire une site et être doté.e d'un outil qui traduit le +Imaginez vouloir construire une site et être doté.e d’un outil qui traduit le format dans lequel vous préférez écrire en html. Peut-être que vous aimez écrire en markdown et utilisez pandoc, cmark[^1] ou même le [script initial de -John Gruber]. Peut-être que vous aimez écrire en asciidoc et utilisez -asciidoctor. Peut-être que vous avez votre propre format avec votre propre -traducteur ! Comment, avec l'aide des outils Unix, créer votre propre -générateur de sites statiques ? +John Gruber](https://daringfireball.net/projects/markdown/). Peut-être que vous +aimez écrire en asciidoc et utilisez asciidoctor. Peut-être que vous avez +votre propre format avec votre propre traducteur ! Comment, avec l’aide des +outils Unix, créer votre propre générateur de sites statiques ? ## Générer une page @@ -15,13 +15,13 @@ générateur de sites statiques ? Vous avez un fichier index.md comme ceci : # Super document cool - + Blablabla - + * super liste * trop cool -et pouvez le convertir en faisant `cmark index.md` : +et pouvez le convertir en faisant cmark index.md : <h1>Super document cool</h1> <p>Blablabla</p> @@ -30,16 +30,16 @@ et pouvez le convertir en faisant `cmark index.md` : <li>trop cool</li> </ul> -Premier problème, si vous avez pour ambition d'avoir un site décemment -construit vous remarquerez qu'il manque de l'html. On pourrait vouloir ajouter -la balise `<html>` et `<meta>` pour l'encodage utf-8 par exemple. Ici -habituellement deux solutions s'offrent à vous. Soit vous comptez sur votre -traducteur pour le faire. C'est le cas par exemple de lowdown avec son option +Premier problème, si vous avez pour ambition d’avoir un site décemment +construit vous remarquerez qu’il manque de l’html. On pourrait vouloir ajouter +la balise `<html>` et `<meta>` pour l’encodage utf-8 par exemple. Ici +habituellement deux solutions s’offrent à vous. Soit vous comptez sur votre +traducteur pour le faire. C’est le cas par exemple de lowdown avec son option `-s` (pour standalone) mais tous ne le font pas : <<-. lowdown -s # titre - + [lien](katzele.netlib.re) . @@ -53,20 +53,20 @@ qui donne <title>Untitled article</title> </head> <body> - + <h1 id="titre">titre</h1> - + <p><a href="katzele.netlib.re">lien</a></p> </body> </html> soit vous utilisez un générateur de site existant. En réalité une troisième -s'offre à vous ! Résoudre ce problème à l'aide d'un outil que vous avez déjà +s’offre à vous ! Résoudre ce problème à l’aide d’un outil que vous avez déjà sous la main, le shell. -Il existe en shell posix une syntaxe nommé `here-document` ou `heredoc`[^2]. -Cette syntaxe permet de créer des sortes de gabarits (ou templates ou layouts) -de la sorte : +Il existe en shell posix une syntaxe nommée here-document ou heredoc[^2]. Cette +syntaxe permet de créer des sortes de gabarits (ou templates ou layouts) de la +sorte : title="machin" <<delim cat @@ -81,9 +81,9 @@ donne le titre : machin blabla -On notera que les variables shell appelées à l'intérieur sont étendues. Et bien -c'est également le cas des captures de commandes type `$(pwd)` ! On peut donc -imaginer l'utiliser pour insérer notre sortie de traducteur au sein d'un +On notera que les variables shell appelées à l’intérieur sont étendues. Et bien +c’est également le cas des captures de commandes type `$(pwd)` ! On peut donc +imaginer l’utiliser pour insérer notre sortie de traducteur au sein d’un gabarit html : title="Un article super" @@ -120,12 +120,11 @@ qui donne </body> </html> -Hop pas besoin d'outils extérieur.\ -Si l'on fait de ce code un script on pourrait l'exécuter pour générer l'html. -Evidemment ce serait limité puisque l'on aurait toujours la sortie du fichier +Hop pas besoin d’outils extérieur. +Si l’on fait de ce code un script on pourrait l’exécuter pour générer l’html. +Evidemment ce serait limité puisque l’on aurait toujours la sortie du fichier index.md. On peut donc décider de passer en argument le nom du fichier markdown -et le titre tant qu'à faire. -On aurait donc un script du type : +et le titre tant qu’à faire. On aurait donc un script du type : title="$1" <<delim cat @@ -134,29 +133,27 @@ On aurait donc un script du type : [...] delim -Qu'on appelerait en faisant `./script "Un article super" ./index.md`. Si nos -besoins ne vont pas plus loin nous avons déjà quelque chose d'à peu près -fonctionnel. Pour rendre tout cela simple d'usage et mieux encapsuler -l'information dans des documents qui se suffisent à eux même nous allons -pousser plus loin. +Qu’on appelerait en faisant `./script "Un article super" ./index.md`. Si nos +besoins ne vont pas plus loin nous avons déjà quelque chose d’à peu près +fonctionnel. Pour rendre tout cela simple d’usage et mieux encapsuler +l’information nous allons pousser plus loin. -Vous remarquerez ici que l'information du titre réside dans votre tête, -à l'écriture de la commande et non pas, comme il est préférable, dans -le document lui-même. L'idéal serait qu'index.md puisse contenir toutes -ses informations, le markdown du corps de l'article mais également -les méta-données afférentes. C'est comme cela que fonctionnent la plupart -des générateurs de site avec des syntaxes propres. On voudrait pouvoir, -par exemple, écrire : +Vous remarquerez ici que l’information du titre réside dans votre tête, à +l’écriture de la commande et non pas, comme il est préférable, dans le document +lui-même. L’idéal serait qu’index.md puisse contenir toutes ses informations, +le markdown du corps de l’article mais également les méta-données afférentes. +C’est comme cela que fonctionnent la plupart des générateurs de site avec des +syntaxes propres. On voudrait pouvoir, par exemple, écrire : title: "Un super article" ---- - + # Super document cool [...] -et que la variable title de notre script prenne pour valeur "Un super article". -Pour ce faire on pourrait modifier notre script pour parser index.md et -en récupérer l'info que l'on souhaite. Par exemle +et que la variable title de notre script prenne pour valeur “Un super article”. +Pour ce faire on pourrait modifier notre script pour parser index.md et en +récupérer l’info que l’on souhaite. Par exemle title=$(grep '^title:' | cut -d':' -f2) @@ -164,39 +161,32 @@ donnerait la bonne valeur à la variable et $(sed -n '/----/,$ p` "$1" | grep -v '^----' | cmark) -Parserait uniquement la partie markdown en ométtant les méta-données. C'est +parserait uniquement la partie markdown en ométtant les méta-données. C’est pourtant sur une autre solution que nous allons partir, une solution qui nous permettera plus de flexibilité par la suite et surtout la possibilité de dynamiquement créer certaines parties du contenu markdown. -### le format "à la catium" et la prolifération des scripts shell - -Cette autre solution consiste à faire du document index.md lui même -un script. Et oui, dans catium, si c'est pas une makefile, c'est -un script shell. Comme le dit le meme : +### le format “à la catium” et la prolifération des scripts shell +Cette autre solution consiste à faire du document index.md lui même un script. Et oui, dans catium, si c’est pas une makefile, c’est un script shell. Comme le dit le meme : -``` -shshsh shshsh shshsh sh sh shshsh shshsh sh sh sh sh -sh sh sh sh sh shsh sh sh sh sh sh shshsh -shsh shshsh shshsh sh shsh sh sh sh sh sh sh -sh shsh sh sh sh shs sh sh sh sh sh sh -sh sh sh sh sh sh sh shshsh shshsh shshsh sh sh + shshsh shshsh shshsh sh sh shshsh shshsh sh sh sh sh + sh sh sh sh sh shsh sh sh sh sh sh shshsh + shsh shshsh shshsh sh shsh sh sh sh sh sh sh + sh shsh sh sh sh shs sh sh sh sh sh sh + sh sh sh sh sh sh sh shshsh shshsh shshsh sh sh - Wait it's all shell scripts ? - / - 🚶🔫🚶 - Always has been -``` + Wait it's all shell scripts ? + / + 🚶🔫🚶 - Always has been -A ce stade on peut renommer index.md en index.sh, ça fera plus sens. L'idée -est dorénavant que notre script devienne une sorte d'interpréteur d'index.sh. -On l'appelera dorénavant "page". Il devra préparer le nécessaire pour que la +A ce stade on peut renommer index.md en index.sh, ça fera plus sens. L’idée est +dorénavant que notre script devienne une sorte d’interpréteur d’index.sh. On +l’appelera dorénavant “page”. Il devra préparer le nécessaire pour que la syntaxe de la page index.sh instancie les bonnes variables et génère le -nécessaire pour l'affichage final de l'html. +nécessaire pour l’affichage final de l’html. -Par exemple, on pourrait grâce à un alias, cacher derrière la syntaxe `title: -"Un super article"` une fonction qui créé la variable title. Pour cela -on peut écrire : +Par exemple, on pourrait grâce à un alias, cacher derrière la syntaxe `title: "Un super article"` une fonction qui créé la variable title. Pour cela on peut écrire : alias title:="title" title() title="$*" @@ -205,29 +195,28 @@ Ainsi, dans index.sh : title: "Un super article" # devient - maketitle "Un super article" + title "Un super article" # devient title="Un super article" -index.sh a créé sa propre variable. Ce système est généralisable à -n'importe quelle métadonnée. Si vous testez cette articulation tel quel -vous rencontrerez un problème. En effet, l'alias déclaré dans l'interpréteur -page n'est pas disponible dans le script index.sh si on l'appel en écrivant -`./$1` et en faisant `./page index.sh` par exemple. C'est parce que en le -faisant de cette manière là, index.sh est exécuté dans un sub-shell, sur un -processus différent ne partageant aucune variable, alias ou fonction -en commun avec son parent. Pour contourner ce problème on peut utiliser -le built-in shell `.`[^3] qui prend en argument le chemin d'un fichier. -Cette fonction va dérouler le code du fichier dans le script courant et -l'exécuter comme s'il y avait été écrit. Le code dans index.sh aura donc -bien accès à ce qui a été déclaré dans l'interpréteur page. Ainsi `./page -index.sh` fera : +index.sh a créé sa propre variable. Ce système est généralisable à n’importe +quelle métadonnée. Si vous testez cette articulation tel quel vous rencontrerez +un problème. En effet, l’alias déclaré dans l’interpréteur page n’est pas +disponible dans le script index.sh si on l’exécute en écrivant `./$1` et en +faisant `./page index.sh` par exemple. C’est parce que en le faisant de cette +manière là, index.sh est exécuté dans un sub-shell, sur un processus différent +ne partageant aucune variable, alias ou fonction en commun avec son parent. +Pour contourner ce problème on peut utiliser le built-in shell .[^3] qui prend en +argument le chemin d’un fichier. Cette fonction va dérouler le code du fichier +dans le script courant et l’exécuter comme s’il y avait été écrit. Le code dans +index.sh aura donc bien accès à ce qui a été déclaré dans l’interpréteur page. +Ainsi `./page index.sh` fera : alias title:="title" title() title="$*" - + . "$1" - + <<delim cat <!DOCTYPE html> <html> @@ -242,12 +231,11 @@ deviendra alias title:="title" title() title="$*" - + title: "Un super article" - ---- - + [...] - + <<delim cat <!DOCTYPE html> <html> @@ -259,43 +247,41 @@ deviendra delim et `title: "Un super article"` se déroulera comme décrit précedemment et ainsi -de suite. Vous remarquerez peut-être que le `----` écrit ici paraît louche. A -priori tenter d'exécuter `----` dans le shell renverra une erreur puisqu'aucun -alias ou aucune[^4] commande ni fonction ne porte ce nom. Pour y remédier on -peut simplement créer un alias bidon `alias ----=":"` de façon à appeler le -builtin `:` qui, par définition, ne fait strictement rien. - -Super ! On sait comment gérer les métadonnées. En réalité on vient d'inventer une -sorte de [DSL] qui ressemble volontairement beaucoup à du [YAML] très simple. -Cette syntaxe est devenu très commune dans les générateurs de sites statiques. - -Maintenant qu'on a trouvé notre alternative à `title=$(grep '^title:' | cut --d':' -f2)` il nous faut trouver celle à `$(sed -n '/----/,$ p` "$1" | grep -v -'^----' | cmark)`. Si on ne le fait pas l'exécution d'index.sh aura vite fait -de nous faire remarquer que le premier mot de notre page n'est pas une commande. - -Pour cela utilisons la même logique que pour les métadonnées, pensons à une -syntaxe qui nous convienne et créeons, en amont dans l'interpréteur le -nécessaire pour que cette syntaxe soit comprise et génère le bon contenu. -Pour pouvoir dire "attention, ce qui suit c'est du markdown" on peut -réutiliser les heredoc. Quelque de la sorte devrait générer l'html : +de suite. + +Super ! On sait comment gérer les métadonnées. En réalité on vient d’inventer +une sorte de [DSL](https://en.wikipedia.org/wiki/DSL) qui ressemble +volontairement beaucoup à du [YAML](https://en.wikipedia.org/wiki/YAML) très +simple. Cette syntaxe est devenu très commune dans les générateurs de sites +statiques. + +Maintenant qu’on a trouvé notre alternative à `title=$(grep '^title:' | cut +-d':' -f2)` il nous faut trouver celle à `$(sed -n '/----/,$ p “$1” | grep -v +‘—-’ | cmark)`. Si on ne le fait pas l’exécution d’index.sh aura vite fait de +nous faire remarquer que le premier mot de notre page n’est pas une commande. + +Pour cela utilisons la même logique que pour les métadonnées. Imaginons une +syntaxe qui nous convienne et créons, en amont dans l’interpréteur le +nécessaire pour que cette syntaxe soit comprise et génère le bon contenu. Pour +pouvoir dire “attention, ce qui suit c’est du markdown” on peut réutiliser les +heredoc. Quelque chose de la sorte devrait générer l’html : title: "Un article super" - ---- - + <<delim cmark # Ceci est du markdown - + blabla delim -Sauf qu'il nous faut capturer la sortie de lowdown pour pouvoir ensuite l'afficher -au bon endroit dans le heredoc template qui suit dans l'interpréteur page. On pourrait -le mettre dans une variable en l'entourant d'une capture de commande : +Sauf qu’il nous faut capturer la sortie de cmark pour pouvoir ensuite +l’afficher au bon endroit dans le heredoc template qui suit dans l’interpréteur +page. On pourrait le mettre dans une variable en l’entourant d’une capture de +commande : corps=$(<<delim cmark # Ceci est du markdown - + blabla delim ) @@ -306,12 +292,13 @@ et dans le template faire $(echo "$corps") </main> -mais vous conviendrez que ça n'est pas très élégant. On va donc opter pour -mettre le résultat dans un fichier temporaire. +mais vous conviendrez que ça n’est pas très élégant (et peut-être sensible au +quoting hell ?). On va donc opter pour mettre le résultat dans un fichier +temporaire. <<delim cmark > A # Ceci est du markdown - + blabla delim [..] @@ -319,35 +306,34 @@ mettre le résultat dans un fichier temporaire. $(cat A) </main> -ce qui permet d'adopter une syntaxe plus sympathique à l'aide d'un nouvel alias : +ce qui permet d’adopter une syntaxe plus sympathique à l’aide d’un nouvel alias : section="<<endsection cmark > A" [...] section # Ceci est du markdown - + blabla endsection -En ajoutant un petit `rm A` à la fin du script page on peut générer notre page +En ajoutant un petit `rm` A à la fin du script page on peut générer notre page html en faisant `./page index.sh` sans souci. index.sh pourra se lire convenablement bien et contiendra les infos à son propos en son sein. La -totalité du fichier jusqu'ici est : +totalité du fichier jusqu’ici est : title: "Un super titre" - ---- - + section # Ceci est du markdown - + blabla endsection -Avec ces éléments nous avons, à mon avis, tous les éléments d'un générateur de -site très simples. Afin d'organiser un peu les choses on pourrait déporter -le heredoc du layout dans un fichier à part, déclarant une fonction `layout`, -exécuté avec le builtin `.` et donc la fonction serait appelé à la fin. Cela -permet de séparer le layout du reste, le "fond" et la "forme" d'une certaine +Avec ces éléments nous avons, à mon avis, tous les éléments d’un générateur de +site très simples. Afin d’organiser un peu les choses on pourrait déporter le +heredoc du layout dans un fichier à part, déclarant une fonction `layout`, +exécuté avec le builtin . et dont la fonction serait appelé à la fin. Cela +permet de séparer le layout du reste, le “fond” et la “forme” d’une certaine manière. On a donc un fichier de layout, nommé html et dans le dossier layouts : @@ -368,58 +354,56 @@ On a donc un fichier de layout, nommé html et dans le dossier layouts : @@ } -Le fichier index.sh comme décrit juste au dessus et le scrit page : +Le fichier index.sh comme décrit juste au dessus et le script page : alias title:="title" title() title="$*" - + . "$1" - + . layout/html layout rm A Si les sources sont dans contents et les fichiers cibles dans public il -suffirait ensuite de créer un script qui appelerait `./page X.sh > -X.html` sur toutes les pages sh nécessaires, avec `X` le nom du fichier pour, -construire le site. +suffirait ensuite de créer un script qui appellerait `./page X.sh > X.html` sur +toutes les pages sh nécessaires, avec `X` le nom du fichier pour, construire le +site. Il nous reste quelques améliorations à apporter à notre générateur. -### L'encapsulation et les sections +### L’encapsulation et les sections -Premièrement, il manque une information dans le fichier index.sh, celle -de son interpréteur. De fait, le fichier est un script ne s'exécutant -correctement que s'il est passé en argument d'un autre[^5]. Il serait -bon de renseigner cette information dans le fichier. Pour ce faire nous -allons lui ajouter le shebang : +Premièrement, il manque une information dans le fichier index.sh, celle de son +interpréteur. De fait, le fichier est un script ne s’exécutant correctement que +s’il est passé en argument d’un autre[^4]. Il serait bon de renseigner cette +information dans le fichier. Pour ce faire nous allons lui ajouter le shebang : #! page -Ainsi il est possible de l'exécuter en faisant directement `./index.sh` ce qui -en réalité, du fait du fonctionnement du shebang, fera `./page ./index.sh` ce -qui revient à ce que nous faisions à la main jusque là. Cette façon de faire -est, selon moi, plus élégante, mais permet également de savoir que cette page -a été écrite pour être interprétée par un script nommé page ce qui, à défaut -de l'avoir, est toujours une bonne information à prendre. Ce système peut être +Ainsi il est possible de l’exécuter en faisant directement `./index.sh` ce qui en +réalité, du fait du fonctionnement du shebang, fera `./page ./index.sh` ce qui +revient à ce que nous faisions à la main jusque là. Cette façon de faire est, +selon moi, plus élégante, mais permet également de savoir que cette page a été +écrite pour être interprétée par un script nommé page ce qui, à défaut de +l’avoir, est toujours une bonne information à prendre. Ce système peut être utilisé pour créer des typologies de pages (article, notes etc) qui seraient générées de manières différentes. -En réalité dans Catium c'est le shebang +En réalité dans catium c’est le shebang #! /usr/bin/env ./page -qui est utilisé pour des raisons obscures de compatibilité avec les *bsd et les -mac[^7]. +qui est utilisé pour des raisons obscures de compatibilité avec les *BSD et les +mac[^5]. -Deuxièmement, comment faire si l'on souhaite, sur une même page, écrire -du blocs de markdown qui doivent aller à deux endroits différents dans -le layout. Ce besoin est très courant dans les pages avec une structure plus -complexe, du type à avoir des div un peu partout, de façon à avoir une -présentation moins linéaire à l'aide de css par exemple. Pour répondre à ce -besoin que l'on a estimé être suffisament important pour être intégré au -générateur dans sa version la plus simple il faut ajouter un peu de complexité -dans l'interpréteur page. +Deuxièmement, comment faire si l’on souhaite, sur une même page, écrire deux +blocs de markdown qui doivent aller à deux endroits différents dans le layout. +Ce besoin est très courant dans les pages avec une structure plus complexe, du +type à avoir des div un peu partout, de façon à avoir une présentation moins +linéaire à l’aide de css. Pour répondre à ce besoin que l’on a estimé être +suffisamment important pour être intégré au générateur dans sa version la plus +simple il faut ajouter un peu de complexité dans l’interpréteur page. On souhaiterait pouvoir écrire dans index.sh : @@ -446,12 +430,11 @@ et par exemple dans le layout : @@ } -On voit que intuitivement on passe une sorte d'argument à notre alias -section[^6]. Il faudrait pouvoir, sur la base de cet argument, stocker -les données de chacune des sections pour pouvoir les appeler séparément -dans le layout. Pour pouvoir traiter cette donnée comme un argument -l'alias ne suffira plus, il faudra passer par une fonction qu'on pourrait -par exemple nommer `save` : +On sent intuitivement qu'il faut passer une sorte d’argument à notre alias +section[^6]. Il faudrait pouvoir, sur la base de cet argument, stocker les données +de chacune des sections pour pouvoir les appeler séparément dans le layout. +Pour pouvoir traiter cette donnée comme un argument l’alias ne suffira plus, il +faudra passer par une fonction qu’on pourrait par exemple nommer `save` : alias section:="<<endsection save" save() cat >> "$1" @@ -463,135 +446,136 @@ Ainsi dans index.sh : endsection # Devient - + <<endsection save truc blabla endsection - + # Puis - + <<endsection cat >> truc blabla endsection -On peut ainsi ouvrir et fermer autant de sections que l'on veut, y compris -plusieurs fois la même grâce à l'opérateur de redirection `>>` qui concatène -plutôt que ne remplace. -Il faut dorénavant que la fonction que l'on appel dans le layout pour -"injecter" les données d'une section à un endroit particulier fasse la -traduction du format vers de l'html. On écrit donc une fonction `show` comme -ceci : +On peut ainsi ouvrir et fermer autant de sections que l’on veut, y compris +plusieurs fois la même grâce à l’opérateur de redirection `>>` qui concatène +plutôt que ne remplace. +Il faut dorénavant que la fonction que l’on appelle dans le layout pour +“injecter” les données d’une section à un endroit particulier fasse la +traduction du format vers de l’html. On écrit donc une fonction `show` comme ceci +: show() cmark "$1" -Cette fonction va donner tout le contenu enregistré dans la section qu'on lui -passe en argument (main footer, comme vous voulez) à `cmark` et en ressortira -de l'HTML. +Cette fonction va donner tout le contenu enregistré dans la section qu’on lui +passe en argument (main, footer, comme vous voulez) à `cmark` et en ressortira de +l’HTML. -Afin d'éviter que les fichiers ne se marchent sur les pieds si l'on a plusieurs -articles, de polluer l'espace de travail et de potentiellement engorger la +Afin d’éviter que les fichiers ne se marchent sur les pieds si l’on a plusieurs +articles, de polluer l’espace de travail et de potentiellement engorger la mémoire de votre ordinateur on peut faire en sorte que tout cela se produise dans un dossier temporaire, sur des fichiers temporaires tous détruits une fois -la génération finie. Pour on créer au début de page un dossier temporaire de -travail avec `mktemp`, on dit au shell de le supprimer si le processus reçoit -le signal `EXIT` (une fois qu'il termine quoi) et on fait une petite fonction -pour le layout puisque l'on ne peut plus juste cat les fichiers comme s'ils -existaient à la racine de notre projet : +la génération finie. Pour cela on créé au début de page un dossier temporaire +de travail avec `mktemp`, on dit au shell de le supprimer si le processus reçoit +le signal `EXIT` (une fois qu’il termine quoi) : tmpdir=$(mktemp -d) trap "rm -rf $tmpdir" EXIT -Il ne nous manque plus qu'à adapter `save` et `show` pour prendre en compte ce +Il ne nous manque plus qu’à adapter `save` et `show` pour prendre en compte ce nouveau dossier : save() cat >> "$tmpdir/$1" show() cmark "$tmpdir/$1" -Et voilà, à une exception près[^8] vous avez recréé absolument tout Catium -dans sa version non étendue. Bravo ! +Et voilà, à une exception près[^7] vous avez recréé absolument tout Catium dans +sa version non étendue. Bravo ! -## Automatiser la génération, le makefile +## Automatiser la génération : le makefile -Il y aurait pleins de manières de partir de cet existant et d'automatiser -la création d'un site de plusieurs fichiers .sh. Un simple script shell -pourrait faire l'affaire. Cependant, pour des raisons pédagogique et, -potentiellement de performances, nous avons opté pour utiliser make. +Il y aurait pleins de manières de partir de cet existant et d’automatiser la +création d’un site de plusieurs fichiers .sh. Un simple script shell pourrait +faire l’affaire. Cependant, pour des raisons pédagogique et, potentiellement de +performances, nous avons opté pour make. Make est un programme spécifiquement créé pour gérer la construction de logiciels. Initialement fait pour compiler des programmes en C à une époque où -les ressources étaient assez rares, make permet à l'utilisateurice de déclarer +les ressources étaient assez rares, make permet à l’utilisateurice de déclarer les règles de dépendances entre les différents éléments de son logiciel. make -créera avec ces règles un graph de dépendances lui permettant, lorsqu'il est +créera avec ces règles un graph de dépendances lui permettant, lorsqu’il est appelé, de ne recréer que le strict nécessaire ainsi économisant du temps de -calcul. Sur le principe la compilation de logiciels et la construction d'un +calcul. Sur le principe la compilation de logiciels et la construction d’un site statique ne sont pas différents. On peut donc faire usage de make pour -créer orchestrer la génération de notre site. +orchestrer la génération de notre site. -Tous le nécessaire pour que make puisse fonctionner doit être inscrit -dans un fichier nommé `makefile` à la racine du projet. +Tout le nécessaire pour que make puisse fonctionner doit être inscrit dans un +fichier nommé makefile à la racine du projet. -Catium utilise Gnu Make et quelques syntaxes lui sont très spécifiques. +Catium utilise Gnu Make et quelques syntaxes lui sont très spécifiques. A +l’avenir un effort sera peut-être consenti pour génériciser la syntaxe. -## Le but +### Le but -Le but est que make fasse automatiquement les appels aux articles -et place leurs sorties dans les bons fichiers de destinations. Par exemple, +Le but est que make fasse automatiquement les appels aux articles et place +leurs sorties dans les bons fichiers de destinations. Par exemple, - ./contents/index.sh > public/index.sh + ./contents/index.sh > public/index.html -Et ainsi pour tous les fichiers .sh qui existent dans l'arborescence à -l'intérieur de contents. +Et ainsi pour tous les fichiers .sh qui existent dans l’arborescence à +l’intérieur de contents. -Dans un second temps on souhaite qu'il copie bêtement tous les autres -fichiers présents dans l'arborescence comme les images par exemple : +Dans un second temps on souhaite qu’il copie bêtement tous les autres fichiers +présents dans l’arborescence comme les images : cp contents/super_image.jpg public/super_image.jpg -Dans notre cas tout simple les fichiers .css et le favicon seront -gérés de la même manière que tous les images n'étant pas des .sh. +Dans notre cas tout simple les fichiers .css et le favicon seront gérés de la +même manière que tous les images n’étant pas des .sh. ### Lister nos fichiers sources -La première étape est de lister toutes les sources de notre site. -On souhaite faire des choses différentes selon que le fichier soit -un .sh ou pas alors on créé deux variables. Dans sources on met la liste des -fichiers sh, dans annexes les autres : +La première étape est de lister toutes les sources de notre site. On souhaite faire des choses différentes selon que le fichier soit un .sh ou pas alors on créé deux variables. Dans sources on met la liste des fichiers sh, dans annexes les autres : sources != find contents -type f -name '*.sh' annexes != find contents -type f -not -name '*.sh' La syntaxe `!=` dit à make que ce qui suit est une commande à faire exécuter -par le shell et non pas des fonctions make. On utilise donc ici le find -que vous pourriez utiliser dans votre terminal en temps normal. +par le shell et non pas des fonctions make. On utilise donc ici le find que +vous pourriez utiliser dans votre terminal en temps normal. + +### Créer les cibles Une fois ces deux listes obtenues, on cherche à créer deux nouvelles listes -contenant les chemins des fichiers correspondants à faire servir par le -serveur web. On les appelera fichiers cibles. Par exemple, si l'on -a le chemin "contents/blog/article.sh" dans la variable sources, -il faudra créer le chemin "public/blog/article.html". Autrement dit on remplace -contents par public et l'extension .sh par l'extension .html. Pour les autres -fichiers seul le premier dossier du chemin est à changer. +contenant les chemins des fichiers correspondants à faire servir par le serveur +web. On les appellera fichiers cibles. Par exemple, si l’on a le chemin +“contents/blog/article.sh” dans la variable sources, il faudra créer le chemin +“public/blog/article.html”. Autrement dit on remplace contents par public et +l’extension .sh par l’extension .html. Pour les autres fichiers seul le premier +dossier du chemin est à changer. -Pour le faire on fait usage des "substitutions references" de GMake dont la syntaxe est : +Pour le faire on fait usage des “substitutions references” de GMake dont la +syntaxe est : - variablecréé = ${variableinitiale:abc%uvw=efg%xyz} + variablecréée = ${variableinitiale:abc%uvw=efg%xyz} Ici, pour toutes les lignes dans la variableinitiale, make cherchera les -caractères `abc` et `uvw` et attribuera tout ce qu'il y a entre à `%`. Il +caractères `abc` et `uvw` et attribuera tout ce qu’il y a entre à `%`. Il remplacera ensuite tous les `abc` par `efg` et les `uvw` par `xyz` en -conservant la partie `%`. Ainsi, si l'on reprend notre exemple précédent on -identifie que la partie commune est `blog/articl` et qu'il faut changer ce qu'il -y a avant et après. On peut donc écrire : +conservant la partie `%`. Ainsi, si l’on reprend notre exemple précédent on +identifie que la partie commune (`%`) est `blog/article` et qu’il faut changer +ce qu’il y a avant et après. On peut donc écrire : pageshtml = ${sources:contents/%.sh=public/%.html} annexescibles = ${annexfiles:contents/%=public/%} -Vous voyez que pour les annexes pas besoin de modifier l'extension donc pas +Vous voyez que pour les annexes pas besoin de modifier l’extension donc pas besoin de la partie après le `%`. On a donc dorénavant dans `pageshtml` et `annexescibles` la liste des chemins des cibles. -C'est maintenant que la partie intéressante de make commence, les règles ! La -syntaxe générale d'une règle est la suivante : +### Écrire les règles + +C’est maintenant que la partie intéressante de make commence, les règles ! La +syntaxe générale d’une règle est la suivante : cible : liste dépendances ; commandes @@ -602,113 +586,114 @@ ou Pour chacun des chemins de cibles construits précédemment make va chercher une règle permettant de construire le fichier en question. Pour cela il cherche une -règle ayant pour cible le même chemin. Une fois qu'il a trouvé une règle qui +règle ayant pour cible le même chemin. Une fois qu’il a trouvé une règle qui correspond, il vérifie si la cible existe. - * Si elle n'existe pas il cherche à construire toutes ses dépendances puis - exécute la commande. - * Si la cible existe mais que certaines de ses dépendances n'existent pas il - va les construire d'abord et passer au point suivant. + * Si elle n’existe pas il cherche à construire toutes ses dépendances puis + exécute la commande. + * Si la cible existe mais que certaines de ses dépendances n’existent pas il + va les construire d’abord et passer au point suivant. * Si la cible existe déjà et que les dépendances existent il vérifie si ses - dépendances ont été modifiées après sa dernière modification. Si oui alors - make suppose que la cible n'est pas à jour (ses sources sont plus récentes - qu'elle même) et make relance la commande. + dépendances ont été modifiées après la dernière modification de la cible. + Si oui alors make suppose que la cible n’est pas à jour (ses sources sont + plus récentes qu’elle même) et make relance la commande. -A noter que tout cela ce fait de façon récursive. Quand make tente de créer une -dépendance il suit les mêmes règles. Si la dépendance n'existe pas il faut donc -qu'il existe une règle pour la créer. +A noter que tout cela se fait de façon récursive. Quand make tente de créer une +dépendance il suit les mêmes règles. Si la dépendance n’existe pas il faut donc +qu’il existe une règle pour la créer. -Pour créer une page html la règle pourrait la suivante : +Pour créer une page html la règle pourrait être la suivante : public/blog/article.html : contents/blog/article.sh layouts/html - mkdir -p public/blog; contents/blog/article.sh > public/blog/article.html + @mkdir -p public/blog + contents/blog/article.sh > public/blog/article.html -Vous noterez que la cible dépend de layouts/html de façon à ce qu'elle -soit reconstruite si le layout change. +Vous noterez que la cible dépend de layouts/html de façon à ce qu’elle soit +reconstruite si le layout change. Ajouter un `@` devant une commande permet +de ne pas l'afficher dans la sortie lorsqu'on lancera make. -Vous pourrez penser "mais on ne va pas écrire les règles pour toutes -les pages non ?" et vous auriez raison. Il est possible d'écrire des -règles génériques, pouvant matcher plusieurs chemins de plusieurs cibles. -Par exemple, la règle suivante conviendra pour créer tous les fichiers -html : +Vous pourriez penser “mais on ne va pas écrire les règles pour toutes les pages +non ?” et vous auriez raison. Il est possible d’écrire des règles génériques +pouvant matcher plusieurs chemins de plusieurs cibles. Par exemple, la règle +suivante conviendra pour créer tous les fichiers html : public/%.html : contents/%.sh layouts/html - mkdir -p $(shell dirname $@); $< > $@ + @mkdir -p $(shell dirname $@) + $< > $@ -De la même manière qu'auparavant on généricise les chemins à l'aide de `%`. On +De la même manière qu’auparavant on généricise les chemins à l’aide de `%`. On récupère le chemin du dossier du fichier cible avec dirname et on fait usage des variables automatiques `$<` et `$@` faisant références respectivement à la -première dépendance et la cible. +première dépendance et la cible. Pour éviter que la commande de création du +dossier de destination s’affiche dans la console lorsque l’on construira le +site on peut la préfixer d’un `@`. Pour les autres fichiers, de façon similaire : - public/% : contents/% - mkdir -p $(shell dirname $@); cp $< $@ + public/% : contents/% + @mkdir -p $(shell dirname $@) + cp $< $@ -Si vous écrivez un makefile de la sorte et tenter de l'exécuter vous vourrez -qu'il ne créera pas tout le site. Make créé les cibles qu'on lui donne en +Si vous écrivez un makefile de la sorte et tenter de l’exécuter vous vourrez +qu’il ne créera pas tout le site. Make créé les cibles qu’on lui donne en argument. `make public/index.html` déclenchera la règle correspondant à cette -cible si elle existe. Cela dit par défaut sans argument make créé uniquement la -cible de la première règle qu'il rencontre dans le makefile, dans l'ordre du -fichier. Comment en sachant cela, forcer la création de toutes les cibles dans -les variables pageshtml et annexescibles ? +cible si elle existe. Cela dit sans argument make créé uniquement la cible de +la première règle qu’il rencontre dans le makefile, dans l’ordre du fichier. +Comment, en sachant cela, forcer la création de toutes les cibles dans les +variables pageshtml et annexescibles ? En utilisant les propriétés des règles décrites précédemment. - 1. Si make n'a pas d'arguement, la première règle du fichier est déclenchée. - 2. Si la cible d'une règle n'existe pas, il va essayer de la créer. On peut - donc en déduire que si la commande de la règle ne créer pas la cible la règle - sera toujours déclenchée. - 3. Make cherche d'abord à créer toutes les dépendances d'une cible avant de - créer la cible. + * Si make n’a pas d’argument, la première règle du fichier est déclenchée. + * Si la cible d’une règle n’existe pas, il va essayer de la créer. On peut + donc en déduire que si la commande de la règle ne créer pas la cible, la + règle sera toujours déclenchée. + * Make cherche d’abord à créer toutes les dépendances d’une cible avant de + créer la cible. -On en conclu que si l'on écrit une règle qui +On en conclu que si l’on écrit une règle qui ; - 1. Précède toutes les autres - 2. A une commande qui ne créé pas de fichier ayant pour chemin la cible. - Aucune commande fera très bien l'affaire. - 3. A pour dépendances toutes les cibles que l'on souhaite construire. + * Précède toutes les autres + * A une commande qui ne créé pas de fichier ayant pour chemin la cible + (aucune commande fera très bien l’affaire) + * A pour dépendances toutes les cibles que l’on souhaite construire. -Alors lorsque l'on lancera make, il cherchera à construire toutes -les cibles à chaque fois. +Alors lorsque l’on lancera make, il cherchera à construire toutes ces cibles à +chaque fois. -Cette règle est très courante dans les makefiles et est généralement nommée -par convention "all", mais elle pourrait s'appeler "toto". Pour lister les +Cette règle est très courante dans les makefiles et est généralement nommée par +convention “all”, mais elle pourrait s’appeler “toto”. Pour lister les dépendances on peut utiliser les variables déjà existantes : all: ${pageshtml} ${annexescibles} -En utilisant les mêmes propriétés nous allons écrire une règle qu'il faudra +En utilisant les mêmes propriétés nous allons écrire une règle qu’il faudra appeler volontairement en passant sa cible en argument à make, se déclenchera toujours, et exécutera une commande. Cette règle permettra de nettoyer le -dossier de destination "public" : +dossier de destination “public” : clean:; rm -r public/* -Si elle n'est pas première dans le fichier et que la cible clean n'est une -dépendance d'aucune autre règle, elle ne se déclenchera qu'en faisant `make +Si elle n’est pas première dans le fichier et que la cible clean n’est une +dépendance d’aucune autre règle, elle ne se déclenchera qu’en faisant `make clean`. Puisque la commande ne créé pas de fichier ayant pour chemin la cible -alors elle se déclenchera toujours. Cela dit, puisqu'elle n'a pas non plus -de dépendances, s'il se trouve qu'un jour un fichier "clean" existe à la -racine du projet, il sera considéré comme toujours à jour. Aucune dépendance -ne pourra être potentiellement plus récente que lui et la règle ne se -déclenchera plus. C'est pour palier ce genre de scénarios qu'il existe une -directive `.PHONY` qui permet de lister ce genre de règles[^9]. Ainsi -make saura qu'il faut, pour ces règles, ignorer la préexistence de la cible. - -Et voilà, vous avez réécri le makefile de catium tel qu'il existe aujourd'hui -! - -[^1]: que l'on utilisera pour les exemples dans ce document -[^2]: documentée ici https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_07_04 -[^3]: oui le nom de la fonction est simplement `.`. -[^4]: du moins très probablement aucune -[^5]: quand bien même la syntaxe a été écrite de façon à ce qu'un.e humain.e puisse le comprendre -[^6]: auquel on a ajouté un `:` pour ressemble aux autres déclarations -[^7]: Voir: https://www.in-ulm.de/~mascheck/various/shebang/#interpreter-script ou le commit 4bd895 -[^8]: la ligne `[ "$1" ] || set -` que je ne m'explique pas -[^9]: même s'il est très improbable qu'un fichier all ou clean se faufile dans votre projet, on sait jamais. -[script initial de John Gruber]: https://daringfireball.net/projects/markdown/ -[DSL]: https://en.wikipedia.org/wiki/DSL -[YAML]: https://en.wikipedia.org/wiki/YAML +alors elle se déclenchera toujours. Cela dit, puisqu’elle n’a pas non plus de +dépendances, s’il se trouve qu’un jour un fichier “clean” existe à la racine du +projet, il sera considéré comme toujours à jour. Aucune dépendance ne pourra +être potentiellement plus récente que lui et la règle ne se déclenchera plus. +C’est pour palier ce genre de scénarios qu’il existe une directive `.PHONY` qui +permet de lister ce genre de règles[^8]. Ainsi make saura qu’il faut, pour ces +règles, ignorer la préexistence de la cible. + +Et voilà, vous avez réécrit le makefile de catium tel qu’il existe aujourd’hui ! + +[^1]: que l’on utilisera pour les exemples dans ce document +[^2]: documentée ici https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_07_04 +[^3]: oui le nom de la fonction est un point final `.`. +[^4]: quand bien même la syntaxe a été écrite de façon à ce qu’un·e humain·e puisse le comprendre +[^5]: Voir: https://www.in-ulm.de/~mascheck/various/shebang/#interpreter-script ou le commit 4bd895 +[^6]: auquel on a ajouté un : pour ressemble aux autres déclarations +[^7]: la ligne [ "$1" ] || set - que je ne m’explique pas +[^8]: même s’il est très improbable qu’un fichier all ou clean se faufile dans votre projet, on sait jamais. + diff --git a/HISTOIRE b/HISTOIRE @@ -0,0 +1,177 @@ +``` +shshsh sh shshsh shshsh sh sh sh sh +sh sh sh sh sh sh sh shshsh +sh shshsh sh sh sh sh sh sh +sh sh sh sh sh sh sh sh sh +shshsh sh sh sh shshsh shshsh sh sh + + Wait it's all shell scripts ? + / + 🚶🔫🚶 - Always has been +``` + +## Une histoire de Catium + +Je discutais un jour avec une personne du contenu que l'on consommait sur +internet. Le dialogue était à peu près le suivant, elle commence : + +A - "Je suis abonné à plusieurs newsletters de journaux, de blogs, de revues +etc"\ +B - "Ah j'aime pas trop les newsletter, perso j'utilise des flux rss quand ils +existent"\ +A - *souriant je crois un peu nerveusement* "Ah ouais ? C'est pas vieux et +presque mort les flux rss ? Je pensais que plus personne n'utilisait ça."\ +B - "Bah c'est plus vraiment à la mode mais c'est encore presque partout et je +le préfère aux newsletter parce que *blablabla*" + +J'ai repensé plusieurs fois à cet échange depuis. Je n'ai pas été surpris pas +le manque de considération pour des technologies pensées comme vieillissantes, +obsolètes, démodées, remplacées. J'ai été cependant marqué par le fait que +cette personne percevait les flux rss comme plus vieux et donc moins digne +d'intérêt que les mails. Pourtant les mails (entre 27 et 50 ans) sont bien plus +anciens que les flux rss (23 ans). Il y a donc autre chose à l'œuvre, quelque +chose qui modifie notre perception de l'ancienneté d'une technologie +indépendamment de son âge réel. On peut imaginer pleins de facteurs pouvant +l'expliquer, le taux d'adoption en est un assez évident, comme si l'on +commençait à décompter l'âge d'une techno qu'à partir du déclin de son +utilisation. Je pense qu'il y en au moins un autre. Il se trouve que cette +personne écrit une newsletter et qu'elle utilise le service Substack pour le +faire. Substack est une plateforme proposant des services pour construire et +publier des newsletter monétisables. L'outil profite d'une certaine hype, +construit par défaut des newsletter avec tous les codes esthétique du web et +des pages webs associées. J'imagine que ce qui explique en partie que cette +personne ne voit pas la publication et l'agrégation de contenu web à travers +des mails comme une pratique obsolète contrairement aux flux rss est le fait +qu'elle le fait à travers un service qui a techniquement, mais surtout +socialement, repackagé la pratique. On n'envoie plus des mails à la papa, "on a +un Substack". La corolaire dit donc qu'une plateforme de la silicon valley ou +un projet open source à la mode pourrait relancer la popularité des flux rss +sans modifier quoi que ce soit à la techno. + +Ce phénomène, qui s'il en est vraiment un doit déjà être connu et porter un nom +que j'ignore, se retrouve à mon avis avec medium et la pratique d'avoir un blog +ainsi que jekyl/hugo et le fait de construire des sites statiques plutôt qu'une +single page app. + +On peut se réjouir de cette résurgence des sites statiques pour de multiples +raisons. On peut regretter - pas trop fort mais quand même - que cela ait +nécessité l'apparition de nouveaux logiciels pour motiver l'industrie à s'y +remettre. Cela semble être la démonstration parfaite que parfois, peut-être +même souvent, ce que la technologie facilite et sa façon de se présenter à nous +(voir le concept d'affordance, des outils de génération de sites statiques ont +toujours existé) a un impact conséquent sur les comportements humains jusqu'à +créer à posteriori les idées et justifications morales de son utilisation. +Autrement dit, on (du moins je) voyait peu d'articles faisant la promotion des +sites statiques avant l'apparition de ces outils. C'est dorénavant assez +fréquent avec une mention presque systématique de ces outils de là à presque +oublier pourquoi un site statique est dans certains cas préférable. + +Autre constat, ces outils destinés à produire des sites simples, le sont assez +rarement eux-mêmes. Évidemment cela dépend du référentiel choisi. On aura du +mal à argumenter qu'hugo est aussi lourd et complexe à dégainer que React. Mais +au regard des fonctionnalités essentielles pour un générateur de site statique, +il est possible d'argumenter qu'hugo est un logiciel trop complexe et faisant +trop de choix pour vous. On pourrait épiloguer là dessus, pour une autre fois +et une autre personne peut-être. + +Si ces outils ont relancé l'intérêt pour les sites statiques, Catium souhaite +à son tour profiter de l'intérêt nouveau pour les sites statiques afin de +relancer l'intérêt pour une certaine approche du développement d'outils +numériques, que l'on choisit à tort ou à raison d'appeler convivialiste. Plus +concrètement cette envie s'est cristallisée courant 2022 à l'Université de +Strasbourg autour du besoin de générer des sites statiques pour le domaine de +la recherche. L'une des utilisations identifiées était la création de page +personnelles pour les chercheureuses. Pour en faire une démonstration il avait +été décidé de faire la page de Marguerity Perey, chercheuse française ayant +travaillé à l'université de Strasbourg et ayant découvert... le catium.\ +Ce projet initial de générer des pages personnelles de chercheureuses n'est pas +mort. Un template html et une feuille de style adéquate, à l'identité visuelle +Unistra, pourrait aider à le concrétiser. + +C'est finalement la page perso de Marc Chantreux aujourd'hui hors ligne qui +sera le premier site généré et publié grâce à Catium. A date du 11 janvier +2023 le site généré par ce dépôt est le seul en ligne généré par Catium. Le +socle du projet a été conçu et développé par Marc Chantreux. Après la mise en +ligne de ce site le développement s'est étendu à d'autres membres du collectif +Kaztele. + +Il y aurait bien d'autres choses à dire sur la genèse du projet, d'où le titre +de cette rubrique, *Une* histoire de Catium. J'invite les autres parties +prenantes à écrire la leur. + +## Sur la nature de Catium + +Un jour Marc et moi sortions de plusieurs heures de discussions pendant +lesquelles nous avons plusieurs fois fait référence à Catium comme un outil +atomique, se suffisant à lui même. En disant ça nous mettions peut-être dans la +tête de nos interlocuteurs l'image d'un simple couteau qui tient dans la main, +dont les contours sont nettes et la forme plus ou moins identique pour tous ses +utilisateurices. En sortant nous nous sommes partagés une intuition commune : +cette image n'est pas celle qui se formait dans nos têtes quand on parlait de +Catium. Il est compliqué de définir le périmètre exact de ce qu'est Catium. + +Où est-ce que l'outil commence, où est-ce qu'il se termine ? Qu'est-ce qui +relève du générateur et qu'est-ce qui relève du contenu du site ? Ces +interrogations se retrouvent dans certains choix techniques que le projet est +amené à prendre. Ce dépôt permet aujourd'hui de versionner à la fois Catium +(sans savoir ce que c'est exactement) et le contenu du site de Katzele. Si nous +voulions créer un dépôt Catium pour d'autres projets nous devrions répondre à +ces questions pour détricoter l'un de l'autre. + +Pourquoi n'est-ce pas trivial ? + +Prenons en exemple atomic, le script permettant de générer des flux atom. + +Premier point d'accroche, tous les sites n'ont pas besoin d'un flux atom. Bien +que ce soit souvent utile et qu'atomic soit léger, l'inclure dans le dépôt +revient à penser que tous les projets, ou au moins une majorité, ont intérêt à +avoir un script de génération de flux atom. + +Second point, si l'on fait le choix de l'inclure par défaut, tous les flux ne +veulent pas y inclure les mêmes informations. Au delà de la spécification des +flux rss/atom, chaque projet peut vouloir mettre quelque chose de différent +dans les balises. Par exemple la balise "content" est très libre, et son +contenu peut éventuellement être mis en page avec de l'html. Autre exemple, un +flux annonçant des évènements dans le futur voudra sûrement inclure la date +dans le titre, la spécification atom n'ayant pas prévue de balise pour +renseigner la sortie d'un contenu dans le futur. La seule date prévue est celle +de publication du contenu qui ici est l'annonce au présent de la tenue de +l'évènement dans le futur. Il tombe donc sous le sens qu'aucun script atomic ne +se ressemblera. Quel doit donc être l'atomic par défaut ? Le minimum vital ? +Un script générant un flux orienté annonce d'évènements ou publications +d'articles ? + +Troisième point, qui découle du précédent, un projet pourrait vouloir générer +plusieurs flux aux formes différentes. Il pourrait alors vouloir plusieurs +atomic. Ce qui pose la question, qu'est-ce que l'on appel atomic ? Le script +par défaut tel que fourni dans le dépôt source s'il existe un jour ? La version +actuelle maintenue pour le site de Katzele ? L'idée de générer un flux atom via +du shell ? Bref on en a pas fini. + +Nous pourrions décliner ces questions pour toutes les parties de Catium. Pour +revenir à l'échange avec Marc, il avait d'avantage mûri la question que moi. +Catium ne devrait pas être pensé comme, un outil indivisible mais une comme +armature intellectuelle soutenant des outils, certains pré existants, d'autres +créés pour l'occasion. D'ailleurs pour le site de Katzele sed est un outil +autant nécessaire qu'atomic même si l'un a été développé pour et l'autre non.\ +Si l'on voulait pousser cette idée d'armature intellectuelle jusqu'au bout nous +pourrions dire que Catium est un système décrit à travers de la documentation +et non pas ses implémentations. Il n'existerait donc pas de sous-ensemble de ce +dépôt que l'on pourrait raisonnablement appelé Catium. Ce dépôt ne serait que +la première implémentation de Catium, celle sous une forme qui rend les +services dont le collectif Katzele a besoin à un instant T. + +Il existera probablement un jour un dépôt Catium dont le contenu aura été le +résultat de choix plus ou moins raisonnables, fait en fonction des projets qui +veulent utiliser Catium sur le moment[^1]. Ce sera certainement pour le mieux. Si +le concept un peu prétentieux d'armature intellectuelle nous sert à quelque +chose ce sera de faire sens de cette tension : construire un outil +convivialiste qui respecte autant que possible l'autonomie des personnes qui +l'utilisent en minimisant les choix qu'il véhicule et vouloir le publier +facilement n'est pas naturel. La première caractéristique incite à la +construction d'une armature, l'autre à celle d'un outil boite noire.\ +Tracer le contour optimisant la convivialité et la facilité de publication +étant hasardeux, on le fera à main levée et on compensera comme il se doit, en +conversant entre humains, en vivant ensemble. + +[^1]: c'est aujourd'hui le cas [ici](http://git.bebou.netlib.re/catium) diff --git a/README b/README @@ -1,514 +1,3 @@ # Catium -``` -shshsh shshsh shshsh sh sh shshsh shshsh sh sh sh sh -sh sh sh sh sh shsh sh sh sh sh sh shshsh -shsh shshsh shshsh sh shsh sh sh sh sh sh sh -sh shsh sh sh sh shs sh sh sh sh sh sh -sh sh sh sh sh sh sh shshsh shshsh shshsh sh sh - - Wait it's all shell scripts ? - / - 🚶🔫🚶 - Always has been -``` - -## Une histoire de Catium - -Je discutais un jour avec une personne du contenu que l'on consommait sur -internet. Le dialogue était à peu près le suivant, elle commence : - -A - "Je suis abonné à plusieurs newsletters de journaux, de blogs, de revues -etc"\ -B - "Ah j'aime pas trop les newsletter, perso j'utilise des flux rss quand ils -existent"\ -A - *souriant je crois un peu nerveusement* "Ah ouais ? C'est pas vieux et -presque mort les flux rss ? Je pensais que plus personne n'utilisait ça."\ -B - "Bah c'est plus vraiment à la mode mais c'est encore presque partout et je -le préfère aux newsletter parce que *blablabla*" - -J'ai repensé plusieurs fois à cet échange depuis. Je n'ai pas été surpris pas -le manque de considération pour des technologies pensées comme vieillissantes, -obsolètes, démodées, remplacées. J'ai été cependant marqué par le fait que -cette personne percevait les flux rss comme plus vieux et donc moins digne -d'intérêt que les mails. Pourtant les mails (entre 27 et 50 ans) sont bien plus -anciens que les flux rss (23 ans). Il y a donc autre chose à l'œuvre, quelque -chose qui modifie notre perception de l'ancienneté d'une technologie -indépendamment de son âge réel. On peut imaginer pleins de facteurs pouvant -l'expliquer, le taux d'adoption en est un assez évident, comme si l'on -commençait à décompter l'âge d'une techno qu'à partir du déclin de son -utilisation. Je pense qu'il y en au moins un autre. Il se trouve que cette -personne écrit une newsletter et qu'elle utilise le service Substack pour le -faire. Substack est une plateforme proposant des services pour construire et -publier des newsletter monétisables. L'outil profite d'une certaine hype, -construit par défaut des newsletter avec tous les codes esthétique du web et -des pages webs associées. J'imagine que ce qui explique en partie que cette -personne ne voit pas la publication et l'agrégation de contenu web à travers -des mails comme une pratique obsolète contrairement aux flux rss est le fait -qu'elle le fait à travers un service qui a techniquement, mais surtout -socialement, repackagé la pratique. On n'envoie plus des mails à la papa, "on a -un Substack". La corolaire dit donc qu'une plateforme de la silicon valley ou -un projet open source à la mode pourrait relancer la popularité des flux rss -sans modifier quoi que ce soit à la techno. - -Ce phénomène, qui s'il en est vraiment un doit déjà être connu et porter un nom -que j'ignore, se retrouve à mon avis avec medium et la pratique d'avoir un blog -ainsi que jekyl/hugo et le fait de construire des sites statiques plutôt qu'une -single page app. - -On peut se réjouir de cette résurgence des sites statiques pour de multiples -raisons. On peut regretter - pas trop fort mais quand même - que cela ait -nécessité l'apparition de nouveaux logiciels pour motiver l'industrie à s'y -remettre. Cela semble être la démonstration parfaite que parfois, peut-être -même souvent, ce que la technologie facilite et sa façon de se présenter à nous -(voir le concept d'affordance, des outils de génération de sites statiques ont -toujours existé) a un impact conséquent sur les comportements humains jusqu'à -créer à posteriori les idées et justifications morales de son utilisation. -Autrement dit, on (du moins je) voyait peu d'articles faisant la promotion des -sites statiques avant l'apparition de ces outils. C'est dorénavant assez -fréquent avec une mention presque systématique de ces outils de là à presque -oublier pourquoi un site statique est dans certains cas préférable. - -Autre constat, ces outils destinés à produire des sites simples, le sont assez -rarement eux-mêmes. Évidemment cela dépend du référentiel choisi. On aura du -mal à argumenter qu'hugo est aussi lourd et complexe à dégainer que React. Mais -au regard des fonctionnalités essentielles pour un générateur de site statique, -il est possible d'argumenter qu'hugo est un logiciel trop complexe et faisant -trop de choix pour vous. On pourrait épiloguer là dessus, pour une autre fois -et une autre personne peut-être. - -Si ces outils ont relancé l'intérêt pour les sites statiques, Catium souhaite -à son tour profiter de l'intérêt nouveau pour les sites statiques afin de -relancer l'intérêt pour une certaine approche du développement d'outils -numériques, que l'on choisit à tort ou à raison d'appeler convivialiste. Plus -concrètement cette envie s'est cristallisée courant 2022 à l'Université de -Strasbourg autour du besoin de générer des sites statiques pour le domaine de -la recherche. L'une des utilisations identifiées était la création de page -personnelles pour les chercheureuses. Pour en faire une démonstration il avait -été décidé de faire la page de Marguerity Perey, chercheuse française ayant -travaillé à l'université de Strasbourg et ayant découvert... le catium.\ -Ce projet initial de générer des pages personnelles de chercheureuses n'est pas -mort. Un template html et une feuille de style adéquate, à l'identité visuelle -Unistra, pourrait aider à le concrétiser. - -C'est finalement la page perso de Marc Chantreux aujourd'hui hors ligne qui -sera le premier site généré et publié grâce à Catium. A date du 11 janvier -2023 le site généré par ce dépôt est le seul en ligne généré par Catium. Le -socle du projet a été conçu et développé par Marc Chantreux. Après la mise en -ligne de ce site le développement s'est étendu à d'autres membres du collectif -Kaztele. - -Il y aurait bien d'autres choses à dire sur la genèse du projet, d'où le titre -de cette rubrique, *Une* histoire de Catium. J'invite les autres parties -prenantes à écrire la leur. - -## Sur la nature de Catium - -Un jour Marc et moi sortions de plusieurs heures de discussions pendant -lesquelles nous avons plusieurs fois fait référence à Catium comme un outil -atomique, se suffisant à lui même. En disant ça nous mettions peut-être dans la -tête de nos interlocuteurs l'image d'un simple couteau qui tient dans la main, -dont les contours sont nettes et la forme plus ou moins identique pour tous ses -utilisateurices. En sortant nous nous sommes partagés une intuition commune : -cette image n'est pas celle qui se formait dans nos têtes quand on parlait de -Catium. Il est compliqué de définir le périmètre exact de ce qu'est Catium. - -Où est-ce que l'outil commence, où est-ce qu'il se termine ? Qu'est-ce qui -relève du générateur et qu'est-ce qui relève du contenu du site ? Ces -interrogations se retrouvent dans certains choix techniques que le projet est -amené à prendre. Ce dépôt permet aujourd'hui de versionner à la fois Catium -(sans savoir ce que c'est exactement) et le contenu du site de Katzele. Si nous -voulions créer un dépôt Catium pour d'autres projets nous devrions répondre à -ces questions pour détricoter l'un de l'autre. - -Pourquoi n'est-ce pas trivial ? - -Prenons en exemple atomic, le script permettant de générer des flux atom. - -Premier point d'accroche, tous les sites n'ont pas besoin d'un flux atom. Bien -que ce soit souvent utile et qu'atomic soit léger, l'inclure dans le dépôt -revient à penser que tous les projets, ou au moins une majorité, ont intérêt à -avoir un script de génération de flux atom. - -Second point, si l'on fait le choix de l'inclure par défaut, tous les flux ne -veulent pas y inclure les mêmes informations. Au delà de la spécification des -flux rss/atom, chaque projet peut vouloir mettre quelque chose de différent -dans les balises. Par exemple la balise "content" est très libre, et son -contenu peut éventuellement être mis en page avec de l'html. Autre exemple, un -flux annonçant des évènements dans le futur voudra sûrement inclure la date -dans le titre, la spécification atom n'ayant pas prévue de balise pour -renseigner la sortie d'un contenu dans le futur. La seule date prévue est celle -de publication du contenu qui ici est l'annonce au présent de la tenue de -l'évènement dans le futur. Il tombe donc sous le sens qu'aucun script atomic ne -se ressemblera. Quel doit donc être l'atomic par défaut ? Le minimum vital ? -Un script générant un flux orienté annonce d'évènements ou publications -d'articles ? - -Troisième point, qui découle du précédent, un projet pourrait vouloir générer -plusieurs flux aux formes différentes. Il pourrait alors vouloir plusieurs -atomic. Ce qui pose la question, qu'est-ce que l'on appel atomic ? Le script -par défaut tel que fourni dans le dépôt source s'il existe un jour ? La version -actuelle maintenue pour le site de Katzele ? L'idée de générer un flux atom via -du shell ? Bref on en a pas fini. - -Nous pourrions décliner ces questions pour toutes les parties de Catium. Pour -revenir à l'échange avec Marc, il avait d'avantage mûri la question que moi. -Catium ne devrait pas être pensé comme, un outil indivisible mais une comme -armature intellectuelle soutenant des outils, certains pré existants, d'autres -créés pour l'occasion. D'ailleurs pour le site de Katzele sed est un outil -autant nécessaire qu'atomic même si l'un a été développé pour et l'autre non.\ -Si l'on voulait pousser cette idée d'armature intellectuelle jusqu'au bout nous -pourrions dire que Catium est un système décrit à travers de la documentation -et non pas ses implémentations. Il n'existerait donc pas de sous-ensemble de ce -dépôt que l'on pourrait raisonnablement appelé Catium. Ce dépôt ne serait que -la première implémentation de Catium, celle sous une forme qui rend les -services dont le collectif Katzele a besoin à un instant T. - -Il existera probablement un jour un dépôt Catium dont le contenu aura été le -résultat de choix plus ou moins raisonnables, fait en fonction des projets qui -veulent utiliser Catium sur le moment. Ce sera certainement pour le mieux. Si -le concept un peu prétentieux d'armature intellectuelle nous sert à quelque -chose ce sera de faire sens de cette tension : construire un outil -convivialiste qui respecte autant que possible l'autonomie des personnes qui -l'utilisent en minimisant les choix qu'il véhicule et vouloir le publier -facilement n'est pas naturel. La première caractéristique incite à la -construction d'une armature, l'autre à celle d'un outil boite noire.\ -Tracer le contour optimisant la convivialité et la facilité de publication -étant hasardeux, on le fera à main levée et on compensera comme il se doit, en -conversant entre humains, en vivant ensemble. - -## Stop le blabla, comment ça fonctionne ? - -Comme expliqué précédemment la description suivante va mélanger ce qui pourrait -relever de Catium seul et du projet du site de Katzele. - -### Descriptif des dossiers et fichiers du projet - -#### Les fichiers - -makefile - -Le makefile décrivant les recettes pour générer les différents fichiers essentiels du projet. - -page - -Le script permettant de générer les pages html à partir des sources markdown. - -README - -Ce fichier. - -TODO - -La liste des choses à faire pour faire avancer le projet - -#### Les dossiers - -bin - -Contient des exécutables utilisés pour générer des fichiers cibles à partir de -fichiers sources. - - * atomic - un ensemble de fonctions shell pour construire un flux rss - * pug - - * pug2cat - - * shylus - - -lib - -Contient les layout html du site ? - - * html - le layout par défaut du site de Katzele - -rc - -Contient les templates html et css - - * grid.shylus - - * html - - * theme.shylus - - -root - -L'arborescence des fichiers cibles, la racine du site statique généré et à -servir par le serveur http. - -src - -L'arborescence des fichiers sources. Pour Katzele - -### Fonctionnement général - -Pour ce "manuel" j'ai fait le choix d'expliquer comment les choses fonctionnent -en reconstruisant ensemble Catium à un degré d'abstraction que l'on juge -convenable. Non seulement je pense que c'est une approche pédagogique -intéressante mais ce sera aussi la démonstration que penser, construire et -modifier ce genre de systèmes est à la portée de beaucoup plus de gens qu'on ne -le pense. Par forcément dans sa totalité, de bout en bout, pas forcément -spontanément dans un vide, pas forcément en mobilisant chaque petite astuce, -mais dans les grandes lignes. Si à la lecture de ce qui suit vous vous dîtes au -moins une ou deux fois "Ah oui pas bête, j'aurais éventuellement pu y penser !" -alors l'objectif sera accompli.\ -Le fait de pouvoir raconter l'histoire fictive d'une personne reconstruisant -tout Catium dans un simple document texte faisant - -echo "$(wc -l < README) lignes dont $(grep "^ " < README | wc -l) de code soit environ $(dc -e "$(wc -l < README) 50 / p") pages A4, $(dc -e "$(wc -l < README) $(grep '^ ' < README | wc -l) - 50 / p") sans les exemples de code" - -> Pour éviter de devoir refaire le compte à chaque fois je laisse la commande -> telle quelle que vous pouvez évaluer vous même. Si vous lisez ce document -> dans vim vous pouvez faire positionner le curseur sur la ligne et taper "!!sh -> entrée". - -est également une démonstration que l'outil est **relativement** simple. Une -trentaine de page c'est beaucoup mais il faut garder en tête que cela inclu -*tout* le code et ce qui motive l'ajout de chacune des lignes. Un travail -similaire serait plus ou moins inconcevable pour une large part des logiciels -que l'on utilise aujourd'hui. - -Le but de Catium est de prendre les fichiers du dossier src et d'en faire un -site logeant dans root. Pour ce faire Catium mobilise plusieurs exécutables -ou scripts qui transforment les sources et placent les données là où il faut -dans les schémas de données. - -#### Le makefile - -Le makefile est le grand orchestrateur, il appelle les scripts sur les fichiers -sources pour construire le dossier root. Un makefile est un fichier décrivant -les règles permettant au programme make de générer les fichiers que l'on -souhaite. Make était initialement utilisé pour compiler des programmes mais il -peut générer n'importe quel type de projet. Pour chaque fichier que l'on -souhaite générer le makefile renseigne ses dépendances et comment le générer. - -Prenons le site de Katzele en exemple, en commençant par la génération des -pages html. La première chose que le makefile cherche à faire est de créer la -liste des pages à générer. Partons du principe que chaque fichier markdown doit -être converti en html et se trouve dans l'arborescence de src à l'endroit où il -doit se trouver dans l'arborescence de root. Autrement dit root est en quelque -sorte le miroir html de src. Pour générer la liste il nous faut recueillir la -liste des fichiers md de src : - - sources != find src -type f -name '*.md' - -Ici on demande à find de trouver dans le dossier `src` tous les fichiers -(`-type f`) dont le nom fini par l'extension `.md` et de renvoyer leurs chemins -relatifs depuis la racine du projet (là où make sera lancé). La syntaxe `!=` -demande à make d'instancier la variable à la première lecture du fichier. En -l'occurence je pense que mettre simplement `=` ne changerait rien pour le site -de Katzele. Pour en savoir plus lire le chapitre 3.7 du manuel : - -https://www.gnu.org/software/make/manual/make.html#Reading-Makefiles - -A l'instant où j'écris cette ligne le résultat de cette commande pour le site -de Katzele est : - - src/notes/220917/les_ui_convivialistes/index.md - src/notes/221019/interfaces_alternatives_youtube/index.md - src/index.md - -`sources` contient dorénavant le chemin, depuis la racine du projet, vers tous -les fichiers md. Il faut ensuite à partir de cette liste créer la liste des -chemins des fichiers html correspondants à générer : - - pages = ${sources:src/%.md=root/%.html} - -La syntaxe `${variable:tr%uc=bid%ule} est un raccourci pour la fonction -`$(patsubst pattern, replacement, text)` soit $(patsubst tr%uc, bid%ule, -variable). Cette fonction prend le contenu de la variable ou du texte, la ou le -découpe en morceaux séparés par du blanc ou une nouvelle ligne et remplace les -occurrences de ce qu'il y a avant le signe `=` par ce qu'il y a après. Le -symbole `%` est un joker et peut correspondre à n'importe quoi. Dans notre -exemple la fonction prendra le premier chemin dans sources : - - src/notes/220917/les_ui_convivialistes/index.md - -détectera le `src/` du début qu'elle transformera en `root/` et le `.md` de la -fin qu'elle transformera en `.html`. Elle "mettra" -`notes/220917/les_ui_convivialistes/` "dans" %, qu'elle repercutera dans le -résultat final. On a donc : - - src/notes/220917/les_ui_convivialistes/index.md - ---- --- - % - ----- ----- - root/notes/220917/les_ui_convivialistes/index.html - -à savoir le chemin du fichier html que l'on souhaite générer. Pour en savoir -plus lire le chapitre 8.2 du manuel : - -https://www.gnu.org/software/make/manual/make.html#Text-Functions - -Nous avons dorénavant la liste de tous les fichiers html à générer dans la -variable pages : - - ./root/notes/220917/les_ui_convivialistes/index.html - ./root/notes/221019/interfaces_alternatives_youtube/index.html - ./root/index.html - -Nous allons maintenant appeler les règles permettant de construire ces fichiers. Une règle a la syntaxe - - cible : prérequis ; recette - suite recette - -Pour en savoir plus sur la syntaxe des règles lire le chapitre X.X du manuel : - -https://www.gnu.org/software/make/manual/make.html#Rule-Syntax - -La règle permettant d'écrire la cible `root/index.html` ressemble donc à : - - root/index.html : src/index.md page; src/index.md | install -D /dev/stdin root/index.html - -`src/index.md` est le fichier source, c'est donc naturellement un prérequis à -pouvoir construire `src/index.html`. `page` est le script permettant de -transformer le markdown en html, également un prérequis à la construction de -l'html. On reparlera de lui par la suite.\ -Make va vérifier si ces prérequis existent. S'il n'existent pas ils cherchera -et exécutera les règles pour les construire. S'ils existent il exécutera -directement la commande permettant de générer le fichier cible. Cette commande -appelle le fichier `src/index.md` qui est en réalité un script dont la sortie -est son propre contenu en html, le pipera dans `install` qui est une commande -copiant des fichiers d'un endroit à un autre. Pensez à `cp`, `mkdir` et `chmod` -combinés en un seul outil fréquemment utilisé dans les scripts d'installation. - -TODO : expliquer comment make sait s'il faut régénérer une cible ou pas en fonction de ses prérequis. Là c'est pas clair/pas expliqué - -Si vous suivez bien vous vous dîtes "Oui mais on devait générer trois fichiers -html, on va tout de même pas ajouter à la main une nouvelle règle à chaque fois -que l'on ajoute un fichier ?". Il est possible d'écrire les règles de façon -plus génériques. Puisque les fichiers html sont tous générés de la même façon -et que l'on a accès au joker `%`, on peut n'écrire qu'une seule règle : - - root/%.html : src/%.md page; $< | ${mk} $@ - -Vous reconnaitrez le couple `src/%.md` et `root/%.html`. Si make rencontre par -exemple le chemin `./root/notes/220917/les_ui_convivialistes/index.html` il -cherchera une règle qui correspond. `root/%.html` match avec -`%=notes/220917/les_ui_convivialistes/index`. Si `%` est réutilisé dans les -prérequis, make le remplacera par sa valeur dérivée de la cible. Dans notre ca -make vérifiera donc qu'il existe bien le prérequis -`src/notes/220917/les_ui_convivialistes/index.md` et le script `page`. Une fois -tous les prérequis réunit, make exécutera la commande. `$<` est l'une des -variables "automatiques" que make recalcule à chaque règle. Elle contiendra -toujours le chemin du premier prérequis. Dans notre exemple elle contient donc -le chemin vers le fichier source md. `$@` en est une autre, elle contient le -chemin vers le fichier cible html. Finalement ${mk} est une variable créée à la -main par la ligne - - mk = install -D /dev/stdin - -qui permet simplement de ne pas avoir à taper la commande en entier à chaque -fois et peut-être faire de fautes de frappe. Si l'on "déploie" chaque variable -on retrouve exactement la commande écrite plus haut. Nous avons donc une règle -générique pour tous les fichiers html ! - -Pour en savoir plus sur les variables dîtes automatiques lire le chapitre -10.5.3 du manuel : - -https://www.gnu.org/software/make/manual/make.html#Automatic-Variables - -Reste à savoir comment les appeler. Par défaut make cherche à créer la première -cible qu'il rencontre dans le makefile. Cela est pratique quand on veut générer -un binaire à partir de tout plein de sources. On met la règle pour le binaire -en premier avec toutes les dépendances. Make va chercher à construire ces -dépendance en appelant d'autres règles et ainsi de suite. Dans notre cas nous -n'avons pas un seul et unique but, nous voulons générer une arborescence, pas -un seul fichier. De plus, make va chercher la première règle qui n'est pas -"générique". Dans notre cas make ne ferait donc rien. Il nous faut donc une -règle pour les gouverner toutes. Par convention on nomme la cible de cette -règle "all". On appelle les cibles qui ne sont pas réellement des fichiers à -construire des cibles "phony" (fausses, bidons, hypocrite). - -Pour en savoir plus sur les phony targets lire le chapitre 4.6 du manuel : - -https://www.gnu.org/software/make/manual/make.html#Phony-Targets - -Cette règle ressemblerait à ceci et se trouverait en premier dans le makefile : - - all: ${pages} - -Pour rappel `pages` est une variable qui contient la liste de tous les fichiers -html à générer. Cette règle indique donc à make que tous les fichiers html sont -des prérequis à la fausse cible "all". Make va donc chercher à les construire -et faire appel, autant de fois que nécessaire, à la règle qui a pour cible -`root/%.html` que l'on a écrite récemment. Attention, cela ne fonctionne que -parce que - - 1. c'est la première règle du fichier, - 2. parce qu'il n'y a pas de fichier nommé "all" dans le projet et - 3. parce que la règle n'a pas de recette qui créé un fichier "all" - -Ça n'est pas magique. - -Le makefile qui résulte de tout ce travail a pour contenu, commenté : - - # Pour copier les fichiers d'un endroit à un autre - mk = install -D /dev/stdin - - # Dans sources les md à transformer en html - sources != find src -type f -name '*.md' - - # On construit dynamiquement les règles à invoquer avec des substitutions de - # chaînes de caractères - # Ex: Pour pages on prend tous les chemins de fichiers récupérés dans sources - # On substitue src/ par root/ et l'extension md par html - # Le fichier source "src/truc/bidule.md" donnera donc - # "root/truc/bidule.html" - pages = ${sources:src/%.md=root/%.html} - - # On appelle toutes les règles pour produire tous les fichiers - # nécessaires - # Pour chacune make va tenter de trouver une règle correspondante dans la - # liste qui suit - all: ${pages} - - clean:; rm -r root/* - - # Règle pour générer l'html depuis les fichiers md - # Va matcher toutes les règles stockées dans la variable pages - # Chaque fichier html requiert sont équivalent md dans src et le script - # page - # Ce que % match dans la cible sera substitué à la place de % dans les - # dépendances - # La commande pour la compilation revient à exécuter le fichier md (qui - # est en fait un script) et piper le contenu dans la commande stockée - # dans la variable mk avec pour argument la cible - # make substitue la variable $@ avec le chemin de la cible - root/%.html : src/%.md page; $< | ${mk} $@ - -Avec une petite "phony target" supplémentaire qu'est `clean`, qui ne dépend de -rien (notez le `;` directement après le `:`) et qui supprime tout le contenu de -`root`. Puisqu'elle n'est pas listée en premier la seule commande `make` ne -l'exécutera pas et puisqu'elle n'a pas de prérequis la cible sera toujours -considérée comme à jour. Pour nettoyer le projet il convient donc de passer en -argument la cible à la commande en faisant `make clean`. - -Vous avez maintenant compris l'esprit général du makefile. Tous les fichiers -que vous voudriez générer le seront ici grâce à une suite d'inventaire des -sources, de construction des chemins cibles, d'appels à des règles et -d'exécutions des commandes appropriées.\ -Par exemple admettons que vous voulez, en plus de générer l'html, copier les -fichiers md tel quel dans `root` pour que les personnes puissent accéder aux -sources et vous soumettre des modifications. -Autrement dit on veut que le fichier - - src/truc/bidule/chouette.md - -se retrouve dans - - root/truc/bidule/chouette.md - -au côté de `chouette.html` - -Nous avons déjà la liste des fichiers md dans la variable `sources`. On reprend la construction de la variable `pages` que l'on adapte à notre besoin : - - rawrules = ${sources:src/%.md=root/%.md} - -et on ajoute tous ces chemins en prérequis à la cible `all` : - - all: ${pages} ${rawrules} - -Reste à construire la règle qui matchera avec ces chemins. En se basant sur la -règle pour les fichiers html : - - root/%.md : src/%.md; install -D $< $@ - -Cette fois-ci la recette ne contient que la commande install puisqu'il n'y a -pas de transformation à faire. Hop c'est fait ! +Il faudrait un readme diff --git a/USAGE b/USAGE @@ -1,8 +1,8 @@ # Comment utiliser Catium Ce document existe pour apprendre à utiliser Catium sans pour autant lire -toute la documentation se trouvant aujourd'hui dans le fichier CONSTRUIRE qui -explique également comment et pourquoi Catium fonctionne de la sorte. +toute la documentation se trouvant aujourd'hui dans [cet +article](construire.html). A noter, Catium est conçu pour être modifiable et même inciter à l'être. Ainsi ce document documente comment utiliser Catium dans sa version @@ -93,36 +93,35 @@ l'échaffaudage pour nos pages. Ce template devra se trouver dans le dossier Prenons celui-ci comme exemple : -layout() { -<<@@ cat -<!DOCTYPE html> -<html> -<head> - <title>${title?La page dont le chemin s'affiche au dessus nécessite un titre}</title> - ${STYLE:+<link rel="stylesheet" href=\"$STYLE\" />} - <meta charset="utf-8"> - <meta name="viewport" content="width=device-width,initial-scale=1.0"> - <meta name="description" content="$description" /> - <meta name="author" content="$author" /> -</head> -<body> - <main> - $(the main) - </main> - <footer> - $(the footer) - </footer> -</body> -</html> -@@ -} - -Les lignes `layout() <<@@ cat` et à la fin `@@` déclarent une fonction shell qui -contient un heredoc. Si vous voulez en savoir plus lisez le fichier CONSTRUIRE. -Vous pouvez faire abstraction sinon.\ + layout() { + <<@@ cat + <!DOCTYPE html> + <html> + <head> + <title>${title?La page dont le chemin s'affiche au dessus nécessite un titre}</title> + ${STYLE:+<link rel="stylesheet" href=\"$STYLE\" />} + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width,initial-scale=1.0"> + <meta name="description" content="$description" /> + <meta name="author" content="$author" /> + </head> + <body> + <main> + $(show main) + </main> + </body> + </html> + @@ + } + +Les lignes `layout() <<@@ cat` et à la fin `@@` déclarent une fonction shell +qui contient un heredoc. Si vous voulez en savoir plus lisez [cet +article](construire.html) ou lisez le manuel de dash. Vous pouvez faire +abstraction sinon. + Le contenu qui se trouve entre ces deux lignes est un mélange d'HTML pur, de variables shell et d'expansion de variables shell. Je ne vais pas les -expliciter ici. Ici ce template convient pour générer des pages très simples, +expliciter ici. Ce template convient pour générer des pages très simples, sans header ni footer, simplement le corps de la page que l'on écrit en markdown. Si cela vous convient vous pouvez ne pas y toucher. Par défaut la feuille de style qui sera utilisée est `./contents/style.css`. Elle contient le @@ -130,9 +129,10 @@ thème de Katzele, vous pouvez la modifier à votre guise. Pour d'éventuelles modifications du template ce qu'il faut à minima retenir est que vous pouvez ici ajouter de l'HTML comme bon vous semble et avoir recours à -la commande `the nom_de_section` pour ajouter des sections que vous +la commande `show nom_de_section` pour ajouter des sections que vous renseignerez en markdown dans vos fichiers sources. Si vous voulez des exemples -de modification voir plus loin dans ce document. +de modification voir plus loin dans ce document. Pour des exemples de sites +aboutis voir [la galerie](/#galerie). ### Fichier source markdown @@ -156,8 +156,8 @@ ensemble de métadonnée. En l'état Catium propose à savoir ce qui s'affichera comme contenu dans le résultat des moteurs de recherche par exemple. -On renseigne ces métadonnées en appelant, dans le fichier sh, les différentes "variables". -Par exemple pour une page d'accueil +On renseigne ces métadonnées en appelant, dans le fichier sh, les différentes +"variables". Par exemple pour une page d'accueil title: "Page d'accueil de mon site" author: moi @@ -168,8 +168,8 @@ Il faut ensuite écrire le contenu markdown. Pour cela faire appel à l'instruction `section:` marquant le début du markdown. Il faut mettre à la suite de cette instruction la section du template dans laquelle on veut que le contenu qui suive aille. Dans notre exemple de template il n'y a qu'une section -(marquée par la commande `$(the main)`) qui remplira bêtement la balise `main`, -unique balise du body. C'est le mot clef suivant `the` et non pas le nom de la +(marquée par la commande `$(show main)`) qui remplira bêtement la balise `main`, +unique balise du body. C'est le mot clef suivant `show` et non pas le nom de la balise HTML qu'il faut retenir et faire correspondre avec ce que l'on va écrire dans le fichier markdown. Il est naturel que la balise et le nom de la section soient identiques mais cela n'est pas nécessaire. Pour y mettre du contenu nous @@ -187,8 +187,8 @@ pouvons donc écrire : * second truc endsection -Il faut fermer l'instruction `section:` avec un `endsection`. Au final notre document -ressemble à : +Il faut fermer l'instruction `section:` avec un `endsection`. Au final notre +document ressemble à : #! /usr/bin/env ./page title: "Page d'accueil de mon site" @@ -210,38 +210,38 @@ ressemble à : Si ce fichier se nomme `index.sh` et se trouve à la racine du dossier `./contents` alors exécuter `make` génèrera ce `index.html` dans `./public` : -<!DOCTYPE html> -<html> -<head> - <title>Page d'accueil de mon site</title> - <link rel="stylesheet" href="style.css" /> - <meta charset="utf-8"> - <meta name="viewport" content="width=device-width,initial-scale=1.0"> - <meta name="description" content="Site de machin chose, bidule à chouette à truc muche" /> - <meta name="author" content="moi" /> -</head> -<body> - <main> - <h1>Le site de machin chose</h1> - <p>Salut !</p> - <h2>Ma vie mon oeuvre</h2> - <p>J'ai travaillé ici, là-bas et accompli cela</p> - <ul> - <li>premier truc</li> - <li>second truc</li> - </ul> - </main> -</body> -</html> - -Dernière astuce, en dehors des blocs `section: nom_de_section ... endsection` vous pouvez -exécuter du shell. Ainsi il est possible, avec votre langage préféré, de -générer du markdown. Cela peut être pratique quand l'on veut générer quelque -chose en fonction d'un contenu qui change souvent et dont on ne connaît pas, à -priori, la teneur. Par exemple un plan de site. Pour ce faire écrivez le code -que vous souhaitez et pipez le dans la commande `save_md` suivi du nom de la -section dans laquelle vous voulez que le contenu apparaisse. Ainsi, en reprenant -la fin du document : + <!DOCTYPE html> + <html> + <head> + <title>Page d'accueil de mon site</title> + <link rel="stylesheet" href="style.css" /> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width,initial-scale=1.0"> + <meta name="description" content="Site de machin chose, bidule à chouette à truc muche" /> + <meta name="author" content="moi" /> + </head> + <body> + <main> + <h1>Le site de machin chose</h1> + <p>Salut !</p> + <h2>Ma vie mon oeuvre</h2> + <p>J'ai travaillé ici, là-bas et accompli cela</p> + <ul> + <li>premier truc</li> + <li>second truc</li> + </ul> + </main> + </body> + </html> + +Dernière astuce, en dehors des blocs `section: nom_de_section ... endsection` +vous pouvez exécuter du shell. Ainsi il est possible, avec votre langage +préféré, de générer du markdown. Cela peut être pratique quand l'on veut +générer quelque chose en fonction d'un contenu qui change souvent et dont on ne +connaît pas, à priori, la teneur. Par exemple un plan de site. Pour ce faire +écrivez le code que vous souhaitez et pipez le dans la commande `save` suivi +du nom de la section dans laquelle vous voulez que le contenu apparaisse. +Ainsi, en reprenant la fin du document : J'ai travaillé ici, là-bas et accompli cela @@ -249,7 +249,7 @@ la fin du document : * second truc endsection - echo "[Un autre site cool](lien_vers_site_cool)" | save_md main + echo "[Un autre site cool](lien_vers_site_cool)" | save main Ajoutera un lien dans la section main @@ -271,10 +271,11 @@ Catium. Cela dit l'esprit de l'outil est qu'il est de nature "hackable" avec des compétences que l'on juge, dans le collectif, comme étant de bonnes candidates pour être des compétences "socles" dans l'informatique. -En dessous nous voyons quelques cas de modifications qui pourraient -vous intéresser ou vous mettre sur la bonne piste. +En dessous nous voyons quelques cas élémentaires de modifications qui +pourraient vous intéresser ou vous mettre sur la bonne piste. Pour des exemples +plus aboutis voir [la galerie](/#galerie). -## Modifier Catium +## Modifier catium Admettons que vous vouliez apporter les modifications suivantes à l'existant : @@ -314,13 +315,15 @@ mettre un petit filet pour nous assurer de ne pas oublier d'un déclarer un : Si la variable est vide (parce que nous aurions oublié de renseigner `lang:` dans un article) alors la génération du site va se terminer et le message d'erreur sera affiché. Alternativement il est possible de choisir une valeur par -défaut. Pour plus d'info lire le fichier CONSTRUIRE ou consulter le manuel de `sh`. +défaut comme ceci : + + <html lang="${lang:-fr}"> ### Ajouter une section au template Admettons que nous souhaitons ajouter un footer et un aside dont nous voulons maitriser le contenu. Rien de plus simple, il suffit de créer les balises -qui vont bien et d'appeler la commande `the` avec les noms des sections. +qui vont bien et d'appeler la commande `show` avec les noms des sections. layout() <<@@ cat <!DOCTYPE html> @@ -334,13 +337,13 @@ qui vont bien et d'appeler la commande `the` avec les noms des sections. </head> <body> <main id="main" class="main"> - $(the main) + $(show main) </main> <aside id="aside" class="aside"> - $(the aside) + $(show aside) </aside> <footer id="footer" class="footer"> - $(the footer) + $(show footer) <p>$author</p> </footer> </body> @@ -366,8 +369,10 @@ sections : endsection A noter, si vous en avez une utilité quelconque, il est possible d'ouvrir et de -fermer les `section:` à votre guise. Le contenu d'une section sera généré dans l'ordre -d'apparition dans le document mais les sections n'interfèrent pas entre elles.\ +fermer les `section:` à votre guise. Le contenu d'une section sera généré dans +l'ordre d'apparition dans le document mais les sections n'interfèrent pas entre +elles. + Il est donc possible d'écrire : section: main @@ -401,4 +406,4 @@ cela reviendrait à écrire truc endsection -Pareil avec les appels à la commande `save_md nom_de_section` suite à un pipe. +Pareil avec les appels à la commande `save nom_de_section` suite à un pipe.