commit ae4b84140d800c76efc941a27f324b98bd91cf5b
parent 3bc5c3d1399407b6fc6355908ae0fdcf7a96ec12
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Mon, 1 Sep 2025 13:35:26 +0200
Rewrite the README
Use English rather than French, as the reference document will be
published shortly and will be aimed at a wider audience than just French
speakers. In addition, the web content archived in the repository is in
English by default, with only some of the content translated into
French.
Add a general overview of the website structure and the logic behind its
generation. In reality, the toolchain used to generate the website
should be external to the repository, which should only contain the
website data. This will make it easy to use for other sites. In
addition, the toolchain will provide its own documentation,
independently of the site to be generated. The README file will
therefore not have to describe the syntax of the input file expected by
the toolchain and can simply refer to its reference documentation. In
any case, until the data and the processing tool are effectively
separated, the README file is the only place where this information can
be recorded.
Diffstat:
| M | README.md | | | 134 | ++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------------- |
1 file changed, 88 insertions(+), 46 deletions(-)
diff --git a/README.md b/README.md
@@ -1,69 +1,111 @@
# 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
-téléchargement.
+Sources for the Meso-Star website and toolchain for automatically
+generating it.
-## Pré-requis
+## Requirments
- POSIX make
- POSIX shell
-- envsubst
-- [git-fat](https://github.com/Jwink3101/git-fat)
+- git-wad
- [gpg](https://gnupg.org/)
- gzip
- man2html
- [mandoc](https://mandoc.bsd.lv)
-- markdown
+- md2html
- rsync
-- [shellcheck](https://www.shellcheck.net/) (optionel)
- tar
- [tidy](https://www.html-tidy.org/)
+- [shellcheck](https://www.shellcheck.net/) (optionnal)
-## Générer et déployer le site WEB
+## Quick Start
-Télécharger les resources du site et vérifier les pré-requis:
+Download resources not directly managed by git:
- git-fat init
- git-fat pull
- ./configure.sh
+ git wad init
+ git wad pull -1
-Modifier le fichier `config.mk` comme souhaité puis lancer la commande
-avant de le déployer :
+Edit the config.mk as needed, then run:
make
- make install
-
-## Vérifier la conformité des fichiers _HTML_ et des scripts _shell_
-
- make check
-
-## Supprimer les fichiers
-
-Supprimer les fichiers _HTML_ générés :
-
- make clean
-
-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_ :
-
- make distclean
-
-## Licence
+ make install # Deploy the website
+
+## Overview
+
+### Structure
+
+The website consists of a set of *sections*.
+The sections are listed in the `menu.tsv` file at the root of the
+repository.
+This is a TSV (Tab Separated Value) file in which each line first
+defines the section label as it will appear in the menu, followed by the
+targeted content.
+
+The sections indexed in the menu can be an external http[s] URL, a
+remote directory managed elsewhere, or, more commonly, a subdirectory of
+the repository.
+In this case, this subdirectory must contain an `index.tsv` file that
+lists the content indexed in the second-level menu.
+As with the `menu.tsv` file, this index is a Tab Separated Value file in
+which each line first defines the submenu label, followed by its target,
+i.e. local content (such as an HTML page) or an http[s] URL.
+This target can be multilingual by using the `@LANG@` macro in its name.
+It will be replaced by one of the languages listed in the third field of
+the line.
+For example, for content available in French and English, the third
+field will have the value `fr:en`.
+This last field is only mandatory in the case of multilingual content.
+Refer to the `misc/index.tsv` file for an example of multilingual
+indexing.
+
+### Content
+
+The website content is defined by section.
+Regular pages are written in
+[Markdown](https://daringfireball.net/projects/markdown/syntax).
+Each .md file in the section's directory is automatically considered
+website content and therefore converted to HTML during automatic website
+generation.
+
+Shell scripts are also automatically detected as site content.
+They are supposed to dynamically generate a Markdown file converted to
+HTML by the build system.
+The resulting file name is that of the script, with the `.sh` extension
+simply replaced by `.html`.
+
+### Additional Resources
+
+The other resources in the section can be stored in three subdirectories
+specific to the section.
+
+- `images` for storing full-size images;
+- `thumbs` for storing thumbnails of images, providing a preview while
+ limiting bandwidth and speeding up web page loading;
+- `downloads` for storing other downloadable content, such as archives,
+ PDFs, etc.
+
+### Hooks
+
+The `hooks` subdirectory of each section contains shell scripts to be
+executed before the section content is generated.
+Their names must begin with a two-digit priority number that defines
+their order of execution, followed by the character '-'.
+If necessary, they display on standard output the additional files that
+must be deployed with the rest of the site.
+
+Hooks can be used, for example, to convert manual pages to HTML, extract
+the contents of an archive used by section scripts to dynamically
+generate the content of a web page, etc.
+It is ultimately a very versatile mechanism that can be used in many
+ways.
+
+## Licences
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>.
+Generated content is licensed under
+[CC BY-ND 4.0](http://creativecommons.org/licenses/by-nd/4.0/)
+The toolchain is free software released under GPL v3+ license: GNU GPL
+version 3 or later. You are welcome to redistribute it under certain
+conditions; refer to the COPYING file for details.
