commit 146cb20e3bdf1373d7f204edb820da49b02aa6cc
parent 422eb4cadc085b667c8c2463bac1af4118451803
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Thu, 6 Feb 2025 16:18:42 +0100
Complete rewriting of the README file
Make it more concise with only essential information
Diffstat:
| M | README.md | | | 130 | ++++++++++++++++++++++++++++++------------------------------------------------- |
1 file changed, 49 insertions(+), 81 deletions(-)
diff --git a/README.md b/README.md
@@ -1,101 +1,69 @@
# Meso-Web
-Meso-Web contient l'ensemble des ressources du site web de Meso-Star ainsi que
-la chaîne de génération automatique qui construit ledit site à partir de ces
-ressources. Les ressources en question regroupent non seulement du texte _HTML_
-et des images, mais aussi des archives, scripts et documents proposés au
+Meso-Web contient l'ensemble des ressources du site web de Meso-Star
+ainsi que la chaîne de génération automatique qui construit ledit site à
+partir de ces ressources.
+Les ressources en question regroupent non seulement du texte _HTML_ et
+des images, mais aussi des archives, scripts et documents proposés au
téléchargement.
-## Télécharger les sources de Meso-Web
-
-Meso-Web utilise _git_ et [git-fat](https://github.com/Jwink3101/git-fat) pour
-versionner, respectivement, ses fichiers textes et ses ressources binaires.
-Copier localement l'ensemble du contenu Meso-Web se ramène d'abord à cloner son
-dépôt _git_ avant d'utiliser _git-fat_ pour télécharger ses binaires. En
-assumant que _git_ et _git-fat_ sont installés et que Meso-Web est hébergé à
-l'adresse hôte "nastar" sous le dépôt "repo/meso-web.git", copier localement
-Meso-Web revient donc à entrer les commandes suivantes :
-
- ~ $ git clone nastar:meso-web.git
- ~ $ cd meso-web
- ~/meso-web $ git-fat init
- ~/meso-web $ git-fat pull
-
-## Générer le site web
-
-La chaîne de génération automatique de Meso-Web s'appuie sur des fichiers
-_Makefile_ et des scripts _shell_ qui, dans un souci de portabilité, suivent la
-norme _POSIX_. Pour construire le site web il faut donc au préalable installer
-une mise en oeuvre de la commande _make_ compatible _POSIX_ tel que, [GNU
-make](https://www.gnu.org/software/make/manual/make.html) ou
-[bmake](http://www.crufty.net/help/sjg/bmake.html), et un interpréteur de
-commande pour le _shell_ _POSIX_, comme
-[GNU Bash](https://www.gnu.org/software/bash/) ou [Z
-shell](https://zsh.sourceforge.io/). Au delà de _make_ et des commandes
-_shell_, d'autres programmes sont utilisés par la procédure de génération
-automatique de Meso-Web comme [GNU Privacy Guard](https://gnupg.org/) pour
-signer numériquement les archives proposées au téléchargement ou _rsync_
-utilisé pour déployer le site web. D'aucun pourra exécuter le script _shell_
-_configure.sh_ pour vérifier que l'ensemble de ces commandes additionnelles
-sont bien installées sur le système :
-
- ~/meso-web $ ./configure.sh
-
-En assumant que l'ensemble des pré-requis sus-cités sont bien remplis, générer
-le site web consiste simplement à invoquer la commande _make_ à la racine de
-Meso-Web :
-
- ~/meso-web $ make
+## Pré-requis
-## Vérifier la conformité des fichiers _HTML_ et des scripts _shell_
+- POSIX make
+- POSIX shell
+- envsubst
+- [git-fat](https://github.com/Jwink3101/git-fat)
+- [gpg](https://gnupg.org/)
+- gzip
+- man2html
+- [mandoc](https://mandoc.bsd.lv)
+- markdown
+- rsync
+- [shellcheck](https://www.shellcheck.net/) (optionel)
+- tar
+- [tidy](https://www.html-tidy.org/)
-La fichiers _Makefile_ proposent la cible _lint_ pour vérifier la conformité
-des fichiers _HTML_ générés. Son objet est de s'assurer que les pages ainsi
-construites s'afficheront correctement sur n'importe quel navigateur respectant
-la norme _HTML_. En plus de vérifier les pages web, la cible _lint_ vérifie
-également les sources des scripts _shell_ utilisés pour générer ces pages :
+## Générer et déployer le site WEB
- ~/meso-web $ make check
+Télécharger les resources du site et vérifier les pré-requis:
-## Supprimer les fichiers issus de la génération automatique
+ git-fat init
+ git-fat pull
+ ./configure.sh
-Deux cibles _Makefile_ permettent de supprimer les fichiers générés à
-l'invocation de la commande _make_. La cible _clean_ supprime essentiellement
-les fichiers _HTML_ générés :
+Modifier le fichier `config.mk` comme souhaité puis lancer la commande
+avant de le déployer :
- ~/meso-web $ make clean
+ make
+ make install
-La cible _distclean_ supprime en plus les fichiers qui ont été plus long à
-obtenir tels que les signatures numériques des archives binaires, ou encore des
-fichiers extraits de ces archives et utilisés comme sources lors de la
-génération des pages _HTML_. _distclean_ est en quelque sorte un _clean_
-renforcé qui, à la prochaine invocation de la commande _make_, force à rejouer
-entièrement la procédure de génération automatique :
+## Vérifier la conformité des fichiers _HTML_ et des scripts _shell_
- ~/meso-web $ make clean
+ make check
-## Déployer le site web
+## Supprimer les fichiers
-La cible _install_ des fichiers _Makefile_ permet de déployer le site web à
-l'addresse renseignée par la macro _PREFIX_ définie dans le fichier
-"config.mk". On prendra donc le soin de définir cette variable à l'adresse
-souhaitée avant d'appeler _make install_ ou de la redéfinir à l'invocation de
-cette commande. Par exemple, pour déployer localement le site web dans le
-répertoire _/tmp_, on entrera la commande suivante :
+Supprimer les fichiers _HTML_ générés :
- ~/meso-web $ make PREFIX=/tmp install
+ make clean
-## Licence
+Supprime les fichiers _HTML_ générées, les signatures numériques, et les
+fichiers extraits des archives pour générer les pages _HTML_ :
-Copyright © 2017-2024 |Méso|Star> (<contact@meso-star.com>)
+ make distclean
+
+## Licence
-Meso-Web est un logiciel libre ; vous pouvez le redistribuer ou le modifier
-suivant les termes de la GNU General Public License telle que publiée par la
-Free Software Foundation ; soit la version 3 de la licence, soit (à votre gré)
-toute version ultérieure. Ce programme est distribué dans l'espoir qu'il sera
-utile, mais SANS AUCUNE GARANTIE ; sans même la garantie tacite de QUALITÉ
-MARCHANDE ou d'ADÉQUATION à UN BUT PARTICULIER. Consultez la GNU General Public
-License pour plus de détails. Vous devez avoir reçu une copie de la GNU General
-Public License en même temps que ce programme ; si ce n'est pas le cas,
+Copyright © 2017-2025 |Méso|Star> (contact@meso-star.com)
+
+Meso-Web est un logiciel libre ; vous pouvez le redistribuer ou le
+modifier suivant les termes de la GNU General Public License telle que
+publiée par la Free Software Foundation ; soit la version 3 de la
+licence, soit (à votre gré) toute version ultérieure. Ce programme est
+distribué dans l'espoir qu'il sera utile, mais SANS AUCUNE GARANTIE ;
+sans même la garantie tacite de QUALITÉ MARCHANDE ou d'ADÉQUATION à UN
+BUT PARTICULIER. Consultez la GNU General Public License pour plus de
+détails. Vous devez avoir reçu une copie de la GNU General Public
+License en même temps que ce programme ; si ce n'est pas le cas,
consultez <http://www.gnu.org/licenses>.
