## La collaboration devrait s'articuler autour de la prochaine version de MaX. ##
## Prérequis
- Java
### Objectifs ###
## Dépendances
- BaseX
- Saxon
Fournir un environnement applicatif permettant l'affichage et la lecture de sources structurées en XML dans un environnement web.
Cet outil — moteur d'affichage XML — se composera :
Celles-ci sont automatiquement installées par la commande `make install`
- d'un cœur applicatif : @todo
- de modules : @todo
## Installation
### Exigences fonctionnelles ###
``
make help
``
L'outil doit :
## Fonctionnement général
- proposer des modules d'affichage pour les vocabulaires TEI et EAD ;
- faciliter la modification des comportements par défaut ;
- permettre l'intégration de nouvelles fonctionnalités sans modification du coeur applicatif ;
- proposer une solution de statification/pétrifications des contenus générés.
L'application est scindée en 2 blocs :
- le cœur : déclaration des routes/fonctionnalités de base, accès aux sources xml et à la configuration, système de templating, traduction etc.
- les bundles : chaque bundle ajoute une (ou des) fonctionnalité à MaX.
### Exigences techniques ###
Il existe actuellement 3 bundles en cours de développement :
- max-tei-bundle : bundle de gestion de l'affichage de sources encodées selon le vocabulaire XML-TEI.
- max-contents-html-bundle : affichage de fichiers statiques HTML stockés dans le répertoire `content_html`.
- max-autoroute-bundle : exécution d'une xquery dont la route correspond à un fichier du même nom.
- fonctionner sur un environnement Unix ;
- permettre la modification des comportements via les languages XQuery et XSL ;
- proposer un fonctionnement simplifié avec stockage des sources sur le système de fichier ;
- permettre un fonctionnement avancé avec utilisation d'une base de données XML BaseX ;
- proposer un code source facilitant l'utilisation d'autres systèmes de stockage des sources (SGBD par exemple) ;
- minimiser les dépendances logicielles ;
- proposer la solution la plus légère et écologique possible.
Les sources XML à afficher doivent être stockées dans une base nommée `max`.
### Pistes ###
## Bundle de vocabulaire
On s'inspire de Francium (makefile et le moins de technologies mobilisées possibles). On ajoute simplement un appel, ou des appels, saxon pour la transformation du corpus XML en HTML. L'appel aux XSLs devra être clarifié, mais il dépendra des modules installés et appelés. Il sera probablement indispensable de disposer d'un ou deux scénarios de transformations de base un peu "câblés" : un pour les données encodées en TEI et un pour les données encodées en EAD.
Un bundle de *vocabulaire* est spécialisé dans le rendu d'un vocabulaire XML. C'est le cas du `max-tei-bundle`.
Ce type de bundle doit contenir :
- une fonction xquery déclarée dans l'espace de nom du bundle et définie par `[ns]:doc-to-html($document as document-node(), $lang as xs:string)`
Cette fonction sera automatiquement appelée par le cœur pour la route `/{$lang=[a-z]{2}}/{$collection=.+}/{$doc=[a-zA-Z0-9_]+}.html`
- un dossier templates contenant les templates :
-`page.html` : template appliqué par défaut par le cœur pour les rendus des différentes pages
-`error.html` : template d'erreur appliqué par défaut par le cœur
- un fichier `expath-pkg.xml` définissant le module au format EXPath
- un dossier `autoroute` (optionnel) avec un fichier `[page].xq` pour chaque fonctionnalité servie sur la route `/{$lang=[a-z]{2}}/{$page=[a-zA-Z0-9_]+}.html`
- un dossier `webapp` (optionnel) contenant les routes (restxq) servies par le bundle
- un dossier `locales` (optionnel) avec un fichier `[codelang].json` par langues gérées
- un dossier `static` (optionnel) contenant les assets du bundle (fichiers js, css, images etc.)
Pas de solution de stockage par défaut : ce sont des fichiers stockés sur le système de fichiers qui seront transformés en HTML.
Il faudra que l'utilisateur exprime sa volonté d'utiliser une solution de stockage (BaseX ou SGBDR (PGSQL probablement?)) en intervenant dans le fichier de configuration directement. Cette solution permet de fixer le coût d'entrée technique : si l'utilisateur ne sait pas intervenir dans un script `sh`, pas la peine d'y mettre le nez plus avant… il devra se contenter d'utiliser la version de base du moteur qui devra proposer un résultat HTML minimal exploitable (façon TEIPublisher).
### Configuration
La modification du comportement des transformations (et des requêtes XQuery le cas échéant) se fera *via* un simple mécanisme de renommage des fichiers avec un suffixe, ou un préfixe, qui sera pris en charge préférentiellement dès qu'il existera (ie : tohtml_custom.xsl sera utilisé à la place de tohtml.xsl).
La configuration se fait dans le fichier `config.xml`.
L'ogranisation sera basée sur des modules. Les utilisateurs devront pouvoir ajouter des modules facilement. Certains modules seront "certifiés" par l'équipe de développement de MaX, garantissant ainsi leurs bon fonctionnement.
Afin d'opérer à un rendu, un bundle de vocabulaire doit être déclaré dans le fichier de configuration de MaX.
Intégration d'Heimdall (à discuter précisément avec Régis).
Exemple de configuration minimale :
Intégration de DTS. C'est une expérimentation à laquelle nous nous sommes engagée dans le cadre de Biblissima+. Lors des dernières journées du cluster 5b, il apparaît que DTS (dont une POC est développée en XQquery dans BaseX) pourrait être une solution élégante et efficace pour permettre de renvoyer côté données l'accès aux fragments (introduction, chapitre, section, etc.). En effet, en s'appuyant sur un élément TEI dédié (spécialement ajouté pour DTS) il est possible de faire l'association entre un type de partie de texte et un XPath directement dans une instance XML. Voir la définition de l'élément [citeStructure](https://tei-c.org/release/doc/tei-p5-doc/en/html/ref-citeStructure.html)
- serveur web (pour permettre l'affichage des pages HTML dans le cadre d'une utilisation de base). De cette manière le comportement du moteur sera toujours le même, quelle que soit la solution de stockage retenue.
### Modules XQuery
Le cœur et les bundles sont packagés puis déclarés comme modules XQUERY ([EXPath Packaging](https://docs.basex.org/12/Repository#expath_packaging)) auprès de BaseX afin de faciliter
le développement.
Proposition d'organisation des fichiers (avec probablement plein de problèmes à discuter…) :
## Organisation des sources
-`src` : toutes les sources
-`main` : sources applicatives
-`core`
-`bundles`
-`webapp`
-`resources` : ressources additionnelles
-`test` : source des tests
```
## Le dossier `.max`
.
├── app
├── content
├── data
├── modules
│ ├── actes
│ ├── dts
│ ├── ead
│ ├── heimdall
│ ├── inventaires
│ ├── pdf
│ └── tei
└── themes
├── css
├── js
└── templates
Il contient le serveur BaseX. C'est un dossier (caché) purement technique dans lequel l'utilisateur n'aura pas (et ne devra pas) intervenir.
```
## Liens symboliques dans un environnement de développement
- dossier `max` dans`.max/basex/webapp/max/` avec lien vers `src/main/webapp/routes.xqm` et les différents fichiers RestXQ des bundles `src/main/bundles/*/webapp/*.xqm`
- dossier max dans `.max/basex/repo` avec lien vers `src/main/core` et `expath-pkg.xml`
- liens depuis `.max/basex/repo` vers les différents bundles (`src/main/bundles`)
Ces liens sont automatiquement créé par la commande `make install`
*Note* :
Tous ces liens doivent être gérés par le CLI et/ou le Makefile, le développeur de MaX ou d'un Bundle n'édite que les fichiers dans `src/`.
L'utilisateur édite dans : `/templates`, `/autoroute`, `/content_html`.
Dans la version packagée, les liens symboliques seront remplacés par les fichiers (absence du dossier `src`)
## Les routes principales
### Du cœur
Elles sont déclarées dans le fichier `src/main/routes.xqm`
-`/{$lang=[a-z]{2}}/{$collection=.+}/{$doc=[a-zA-Z0-9_]+}.html` : version HTML du source XML nommé `$doc.xml` dans la collection `$collection`
-`/{$bundle}/static/{$filename}` : fichier statique d'un bundle (js, css, etc.)
-`/sources.zip` : archive zip contenant les sources XML
-`/max-infos.html` : affiche les informations de configuration et d'environnement. (disponible uniquement en mode `dev`)
### Des bundles
#### max-content-html-bundle
`/{$lang=[a-z]{2}}/pages/{$page=[a-zA-Z0-9_]+}.html` : rend la page HTML stockée dans `content_html/[$lang]/[$page].html`
