Commit 6ad9e412 authored by Marie Bisson's avatar Marie Bisson
Browse files

maj doc spéciale PDN

parent 75740e08
# MaX
Le Moteur d'Affichage XML est une interface de lecture de sources XML développé par l'[Université de Caen Normandie](http://www.unicaen.fr) ([Pôle Document Numérique](http://www.unicaen.fr/recherche/mrsh/document_numerique) / [CERTIC](https://www.certic.unicaen.fr)) notamment dans le cadre de l'Equipex [Biblissima](http://www.biblissima-condorcet.fr/)
Le Moteur dAffichage XML est une interface de lecture de sources XML développé par l[Université de Caen Normandie](http://www.unicaen.fr) ([Pôle Document Numérique](http://www.unicaen.fr/recherche/mrsh/document_numerique) / [CERTIC](https://www.certic.unicaen.fr)) notamment dans le cadre de lEquipex [Biblissima](http://www.biblissima-condorcet.fr/)
## Licence
......@@ -25,34 +25,111 @@ Vous pouvez nous contacter via [contact.certic@unicaen.fr](mailto:contact.certic
- xmllint
- BaseX 9.2+
### Installation BaseX (et éventuels changements de ports)
## Installation
- vous pouvez télécharger BaseX (.zip) à cette adresse : [http://www.basex.org/download/](http://www.basex.org/download/).
- vous pouvez le renommer (ex. : maxTest) et l’installer où vous le souhaitez
ex. Documents/PDN/Standalone/maxTest
#### Modifications des ports
- Lancer une instance du serveur Jetty avec la commande basexhttp (afin de générer le fichier .basex) :
- dans le terminal se placer dans le dossier bin du BaseX (maxLight)
```bash
$ cd tools && ./max.sh --init
# change dir to your basex app folder
$ cd </path/to/basex>/webapp
# create a symlink on your MaX instance
$ sudo ln -s /path/to/max .
# run basex http
$ cd </path/to/basex>/bin
$ ./basexhttp
# then check your install at: http://localhost:8984/max: 'MaX' should be displayed.
```
$ cd PATH/Documents/PDN/Standalone/maxTest/bin
$ ./basexhttp &
```
Il est fortement recommandé d'utiliser saxon9 comme moteur de transformation XSLT. Il faut alors l'ajouter aux librairies chargées par BaseX :
- Arrêter l’application BaseX avec le terminal (toujours dans le dossier bin) pour changer les ports
```
$ ./basexhttpstop
```
- Changer les ports (par défaut 1984 / 8984) dans les fichiers :
- .basex (fichier caché à la racine du dossier) :
- PORT (l. 13) port du server (ex. : 14070) ;
- SERVERPORT (l.14) port du server (ex. : 14070) ;
- STOPPORT (l. 34) port d’arrêt (ex. : 14071)
- jetty.xml (fichier dans webapp > WEB-INF ) :
- Set @name="port" (l. 11) port du server d’application (ex : 14072).
> NOTA BENE : c’est le port configuré dans ce fichier jetty.xml qui va servir pour l’URL
```
<Configure id="Server" class="org.eclipse.jetty.server.Server">
<Call name="addConnector">
<Arg>
<New class="org.eclipse.jetty.server.nio.SelectChannelConnector">
<Set name="host">0.0.0.0</Set>
<Set name="port">14072</Set>
<Set name="maxIdleTime">60000</Set>
<Set name="reuseAddress">true</Set>
<Set name="Acceptors">2</Set>
</New>
</Arg>
</Call>
</Configure>
```
- Relancer une instance du jetty (`./basexhttp &`) et vérifier que tout se passe bien dans le navigateur à l’adresse : http://localhost:14072 (la page "BaseX HTTP Services" doit s’afficher)
Il est fortement recommandé d’utiliser saxon9 comme moteur de transformation XSLT. Il faut alors l’ajouter aux librairies chargées par BaseX dans le dossier `lib` de l’instance baseX.
```bash
$ cp </path/to/saxon/>saxon9.jar </path/to/basex>/lib
```
## Installation
### Récupérer MaX
Récupérer MaX sur le git d’unicaen (git.unicaen.fr/pdn-certic) et l’installer dans le dossier webapp du baseX
- soit en le téléchargeant ;
- soit en ligne de commande (pour pouvoir faire les mises à jour)
```
$ cd Document/PDN/Standalone/maxTest/webapp/
$ git clone git@git.unicaen.fr:pdn-certic/MaX.git
```
Il existe plusieurs branches de max que vous pouvez rapatrier
```
$ cd MaX
$ git fetch
$ git checkout dev
```
### Récupérer toutes les fonctionnalités de MaX
Il faut se placer dans le dossier tools et lancer une première fois le script `max.sh`
> N. B. : Si vous avez changé les ports de BaseX, il faut modifier le script max.sh en modifiant la ligne 4 du script `PORT=1984` en `PORT=`*`port_du_serveur`*
```bash
# lancer le script
$ cd </path/to/basex>/webapp/MaX/tools
$ ./max.sh --init
# démarrer basex http si ce n’est pas fait
$ cd </path/to/basex>/bin
$ ./basexhttp
```
Vous pouvez vérifier si Max est bien installé sur votre navigateur à l’adresse : http://localhost:8984/max. MaX doit s’afficher dans votre navigateur.
> N. B. : Si vous avez changé les ports de BaseX, il faut chager 8984 par le port défini dans le fichiers `jetty.xml`.
### Édition de démonstration
Pour installer la version démo, il faut à nouveau utiliser le script max.sh
```bash
$ cd tools
# set the env var $BASEX_PATH only if the basexclient command is not in your PATH. Useless
# if basex was install with your system package manager
# The basex dir must contains the bin subfolder
......@@ -65,50 +142,133 @@ Modifier si nécessaire le numéro de port (*1984* par défaut) de votre serveur
$ ./max.sh --install-demo
```
L'édition de démonstration est consultable à **http://localhost:8984/demo_lorem**
Le terminal demande les identifiants et mots de passe (par défaut admin / admin).
L’édition de démonstration est consultable à **http://localhost:8984/demo_lorem**
> N. B. : Si vous avez changé les ports de BaseX, il faut chager 8984 par le port défini dans le fichiers `jetty.xml`. Ex. ci-dessus http://localhost:14072/demo_lorem
## Paramétrages - todo
### Ajouter une édition
Pour ajouter une édition on peut utiliser à nouveau le script max.sh
```
#Se positionner en ligne de commande dans le dossier tools
$ cd path
#executer le script
$ ./max.sh --new-edition
```
Plusieurs questions vont être posées :
1. Identifiant du projet ?
Il faut écrire le nom de site, sans espace ni caractères spéciaux. Exemple : pouille
2. Chemin de la collection XML?
**Il s’agit du nom de la base de données XML**. Nous donnons souvent le même nom de base que le nom du projet ou le nom du maxiprojet suivi du nom du projet. Exemple : norecrit/pouille
3. Vocabulaire XML du projet (tei, ead, ...)?
tei
4. Dossier des sources XML à charger ?
Il s’agit de renseigner le chemin complet vers le dossier où se trouvent les fichiers XML. Exemple : /Users/marie/Documents/fichiersBaseX/pouille
5. Please type your BaseX login/password :
Par défaut admin / admin
- Username: admin
- Password: admin
Vous pouvez enfin vous connecter en local à l’adresse :
`http://localhost:PORT_DECLARE_DANS_JETTY/NOM_PROJET `
Exemple : http://127.0.0.1:14072/pouille
todo: explication script max.sh --new-edition
### Fichiers de configuration
#### Configuration globale
Le fichier *configuration/configuration.xml* se contente d'inclure les fichiers de configuration des différentes éditions hébergées par l'instance de MaX.
Le fichier *configuration/configuration.xml* se contente dinclure les fichiers de configuration des différentes éditions hébergées par linstance de MaX.
Chaque édition *myedition* existe de par la présence d'un dossier *editions/myedition*.
Chaque édition *myedition* existe de par la présence dun dossier *editions/myedition*.
*Exemple d'inclusion de configuration de l'édition demo dans configuration/configuration.xml :*
*Exemple dinclusion de configuration de lédition demo dans configuration/configuration.xml :*
```xquery
<!--inclusion de la configuration de l'édition demo au sein de la configuration de MaX-->
<!--inclusion de la configuration de lédition demo au sein de la configuration de MaX-->
<xi:include href="../editions/demo/demo_config_inc.xml"/>
```
Ces opérations de création et d'inclusion de fichier sont effectuées automatiquement par le script d'ajout d'édition *max.sh --new-edition*.
Ces opérations de création et dinclusion de fichier sont effectuées automatiquement par le script dajout dédition *max.sh --new-edition*.
### Page d'accueil
### Page daccueil
Affiche le fragment HTML stocké dans **editions/[project]/fragments/accueil.frag.html** à l'url
Affiche le fragment HTML stocké dans **editions/[project]/fragments/accueil.frag.html** à lurl
**http://[host]:[port]/[project]/accueil**
### Table des matières d'une édition
### Menu
Le menu d'une édition **myedition** se configure dans un fichier **editions/myedition/menu.xml** décrivant au maximum deux niveaux de menu . Pour une entrée de menu (<entry>), il est nécessaire de renseigner son identifiant(<id>) ainsi que sa cible (<target>). Dans l'exemple ci-contre, le menu généré contiendra deux entrées principales (attribut type='main'): home et parcours.
L'entrée home pointera vers l'URL **http://{...}/myedition/accueil** et contiendra deux sous-entrées presentation et contacts pointants respectivement vers **http://{...}/myedition/presentation** et **http://{...}/myedition/contact**.
```xml
<menu>
<entry type="main" default="true">
<id>home</id>
<target>accueil</target>
<!--home sub entries-->
<entry>
<id>presentation</id>
<target>presentation</target>
</entry>
<entry>
<id>contacts</id>
<target>contacts</target>
</entry>
</entry>
<entry type="main">
<id>sommaire</id>
<target>sommaire</target>
</entry>
</menu>
```
**@todo** : les noeuds *id* sont-ils indispensables ?
#### Modification de la mise en forme du menu
Le menu HTML est le résultat de la transformation du fichiers **myedition/menu.xml** par la feuille XSL par défaut placée dans **MAX/ui/menu.xsl**.
Une feuille de transformation placée dans **myedition/ui/xsl/menu.xsl** remplacera celle par défaut. 3 paramètres sont disponibles dans cette XSL :
* **projectId** : identifiant du projet
* **baseURI** : baseURI du projet
* **selectedEntry**: entrée de menu courante (valeur d'un des attributs @target)
### Table des matières d’une édition
La table des matières d'une édition est disponible à l'URL **http://[host]:[port]/[project]/sommaire**
La table des matières dune édition est disponible à lURL **http://[host]:[port]/[project]/sommaire**
#### Fonctionnement par défaut
Par défaut, la page de sommaire liste les documents présents dans la collection:
* Pour la TEI, les élements **TEI/tei:teiHeader/tei:fileDesc//tei:title//text()**
* Pour l'EAD, les éléments **ead/ead:archdesc/ead:did/ead:unittitle//text()**
* Pour lEAD, les éléments **ead/ead:archdesc/ead:did/ead:unittitle//text()**
## Surchage du comportement
La modification du comportement par défaut se fait par l'ajout d'un fichier XQUERY **toc.xq**, dans le répertoire **editions/[projectId]/xq/**.
#### Surchage du comportement
La modification du comportement par défaut se fait par lajout dun fichier XQUERY **toc.xq**, dans le répertoire **editions/[projectId]/xq/**.
Ce fichier doit à minima déclarer les variables qui lui sont automatiquement passées en paramètres par MAX :
```
......@@ -121,20 +281,20 @@ declare variable $project external;
</div>
```
### Sommaire d'un document
### Sommaire dun document
Le sommaire d'un document est accessible à l'URL **http://[host]:[port]/[project]/sommaire/[document_path].xml**
Le sommaire dun document est accessible à lURL **http://[host]:[port]/[project]/sommaire/[document_path].xml**
#### Fonctionnement par défaut
Actuellement, seule la TEI est dotée d'un comportement par défaut : le sommaire d'un document liste le contenu des balises
Actuellement, seule la TEI est dotée dun comportement par défaut : le sommaire dun document liste le contenu des balises
```
div[@type='chapitre']/tei:head//text()
```
#### Surcharge
Le concept est identique à celui du sommaire de l'édition avec un fichier **document_toc.xq** dans **editions/[projectId]/xq/**.
#### Surcharge du comportement
Le concept est identique à celui du sommaire de lédition avec un fichier **document_toc.xq** dans **editions/[projectId]/xq/**.
Une variable supplémentaire est disponible dans la xquery (celle contenant le nom du document) :
```
......@@ -167,7 +327,7 @@ declare variable $doc external;
#### Apparat critique
#### Fil d'ariane (Breadcrumb)
#### Fil dariane (Breadcrumb)
#### Correction
......@@ -185,21 +345,21 @@ declare variable $doc external;
Certains plugins ont des dépendances vers des librairies js (ex : *img_viewer* requiert *OpenSeadragon*).
Ces librairies sont automatiquement copiées à l'installation du plugin pour une édition à la lecture
Ces librairies sont automatiquement copiées à linstallation du plugin pour une édition à la lecture
du fichier *plugins/<plugin_name>/resources.json*.
Ex : l'édition de démo fonctionnant avec les plugins *img_viewer* et *equations*, les librairies *Mathjax* et *Openseadragon* sont
automatiquement copiées lors de l'installation de l'édition (lecture de *equations/dependencies.json* et *img_viewer/resources.json*).
Ex : lédition de démo fonctionnant avec les plugins *img_viewer* et *equations*, les librairies *Mathjax* et *Openseadragon* sont
automatiquement copiées lors de linstallation de lédition (lecture de *equations/dependencies.json* et *img_viewer/resources.json*).
## Exécution d'une édition dans un container Docker
## Exécution dune édition dans un container Docker
* L'image ne peut être créée que si une édition existe (la création d'une image à partir d'un MaX vide est impossible, et inutile !).
* Limage ne peut être créée que si une édition existe (la création dune image à partir dun MaX vide est impossible, et inutile !).
* Création de l'image de l'édition (exemple avec l'édition de démonstration) puis lancement du container accessible sur le port 9999 (base XML du projet stockée dans */opt/basex/data/max_demo_lorem* :
* Création de limage de lédition (exemple avec lédition de démonstration) puis lancement du container accessible sur le port 9999 (base XML du projet stockée dans */opt/basex/data/max_demo_lorem* :
Création de l'édition de démonstration
Création de lédition de démonstration
```
$ ./tools/max.sh --init && ./tools/max.sh --install-demo
......@@ -212,7 +372,7 @@ Ajout des droits sur les données de la base pour le container :
$ sudo chown -R 1984 /opt/basex/data/max_demo_lorem
```
Création de l'image de l'édition puis lancement du container :
Création de limage de lédition puis lancement du container :
```
$ sudo docker build -t unicaen/max_demo_lorem .
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment