:memo: Explain how to make files from source

src/projets/pandoc_site/content.src.md

@@ -102,6 +102,8 @@ Le résultat est celui attendu : pandoc réalise fidèlement son travail de conv
 
 La syntaxe comprise par pandoc est un sur-ensemble du markdown, dont la description est disponible sur la [documentation officielle](https://pandoc.org/MANUAL.html#pandocs-markdown).
 
+Si vous souhaitez désactiver le retour à la ligne automatique, vous pouvez utilisez l'option `--wrap=none`.
+
 ##### HTML indépendant
 
 L'exemple précédent produit un document HTML trop simple pour constituer une page web. On voudrait en effet entourer notre contenu avec des éléments de navigation, comme un menu d'en-tête et un pied de page. L'idéal serait également de pouvoir styliser le contenu avec du CSS et d'ajouter des métadonnées pour caractériser notre contenu.
@@ -249,9 +251,31 @@ Je fais un usage avancé des métadonnées pour ce nouveau site, ce qui sera dé
 
 #### GNU Make
 
+Comment orchestrer la génération successive des fichiers pour aboutir à un site entier ?
+
+##### La philosophie de Make
+
+GNU make est un utilitaire d'aide à la compilation qui fonctionne à partir d'un `makefile`, un document de recettes qui décrit chaque fichier, comment le construire et quelles sont ses dépendances.
+
+Si Make est nouveau pour vous, n'hésitez pas à consulter [cette courte introduction](https://dev.to/woile/digesting-make-and-makefiles-394m) qui vous permettra de vous familiariser rapidement avec le concept de base.
+
+Les prochaines parties vous renseigneront en même temps sur la structure de mon projet et sur mon usage de make.
+
 ##### Convertir un fichier source
 
-Les fichiers sources sont dans le dossier `src` et possèdent la particule `src` dans leur nom. J'ai écrit une recette pour appliquer pandoc sur ces fichiers :
+Tous les fichiers sources du projet sont dans le dossier `src`. Les fichiers qui portent le contenu texte au format source possèdent la particule `src` dans leur nom.
+
+Exemples de fichier de contenu :
+
+```txt
+src/index.src.html
+src/cv/content.src.html
+src/projets/pandoc_site/content.src.md
+```
+
+Peu importe le radical du fichier, mais je comme mon arborescence est suffisamment fine, je peux me permettre de les appeler tous `content`.
+
+J'ai donc écrit une recette pour appliquer pandoc sur ces fichiers source, en décidant d'utiliser le suffixe `.gen.html` pour les fichiers produits.
 
 ```make
 PANDOC_GEN := pandoc --standalone --wrap=none --template src/templates/main.html --metadata-file src/meta.yml
@@ -263,24 +287,72 @@ PANDOC_GEN := pandoc --standalone --wrap=none --template src/templates/main.html
     $(PANDOC_GEN) --output $@ $<
 ```
 
-Ce qui donne :
+Ce qui donne en pratique :
 
 ```shell
-➤ make src/cv/content.gen.html -n
+➤ make src/cv/content.gen.html
 ```
 
 ```out
 pandoc --standalone --wrap=none --template src/templates/main.html --metadata-file src/meta.yml --output src/cv/content.gen.html src/cv/content.src.html
 ```
 
-On obtient donc les sorties générées des fichiers sources.
+On obtient donc les sorties dérivées des fichiers sources.
 
 - `content.src.md` -> `content.gen.html`
 - `content.src.html` -> `content.gen.html`
 
 ##### Produire tous les fichiers sources
 
-Et nettoyage.
+Maintenant que Make connaît la relation entre un fichier source et sa version compilée, je vais créer une recette permettant de générer tous les fichiers avec une instruction `build`.
+
+```make
+.PHONY: build
+build: $(GEN_CONTENT_FILES)
+    $(info HTML generated)
+```
+
+Que je pourrai appeler de la manière suivante pour compiler toutes mes sources :
+
+```sh
+make build
+```
+
+```make
+SRC_HTMLS := $(shell find src -name '*.src.html')
+SRC_MDS := $(shell find src -name '*.src.md')
+
+GEN_HTMLS := $(SRC_HTMLS:%.src.html=%.gen.html)
+GEN_MDS := $(SRC_MDS:%.src.md=%.gen.html)
+GEN_CONTENT_FILES := $(GEN_HTMLS) $(GEN_MDS)
+```
+
+J'utilise la commande shell `find` pour trouver les fichiers source et la mécanique de translation de nom native à *GNU Make* pour en déduire la liste des noms à générer. Ce que va comprendre `Make` sera :
+
+```make
+SRC_HTMLS := src/index.src.html src/cv/content.src.html
+SRC_MDS := src/projets/pandoc_site/content.src.md
+
+GEN_HTMLS := src/index.gen.html src/cv/content.gen.html
+GEN_MDS := src/projets/pandoc_site/content.gen.html
+GEN_CONTENT_FILES := src/index.gen.html src/cv/content.gen.html src/projets/pandoc_site/content.gen.html
+```
+
+La cible `build` a donc en dépendance tous les fichiers `.gen.html` qui peuvent être construits, et utilisera les deux recettes présentées dans la partie précédent pour les générer s'ils sont absents ou si la source est plus récente que le fichier généré.
+
+J'ai également créé une recette pour pouvoir nettoyer mon répertoire :
+
+```make
+.PHONY: clean
+clean:
+    rm -f $(GEN_FILES)
+```
+
+Et j'ai rajouté les fichiers produits dans mon `.gitignore` pour éviter de les versionner.
+
+```gitignore
+*.gen.html
+```
 
 ##### Produire un dossier distribuable