Commit 8b0d72ab authored by Jerome Chauveau's avatar Jerome Chauveau
Browse files

suppression répertoire documentation. Celle-ci est externalisée ici :...

suppression répertoire documentation. Celle-ci est externalisée ici : https://git.unicaen.fr/pdn-certic/max-documentation #136
parent adcb642f
# Documentation Max
## Édition
* Nécessite d'installer [Mkdocs](https://www.mkdocs.org)
* Lancer la commande `mkdocs serve`
## Déploiement
Statification + mise en ligne :
```
$ mkdocs build
$ scp -r ./site user@host:/path/to/server
```
## Version en ligne
Documentation en cours de rédaction disponible [ici](https://www.certic.unicaen.fr/documentations/max/)
\ No newline at end of file
# Configuration
## Configuration générale de MaX
Le fichier <span class="fichier">configuration.xml</span> (dans le dossier <span class="dossier">configuration</span>) inclut les fichiers de configuration des différentes éditions gérées par MaX.
````xml
<!-- Exemple de fichier de configuration de MaX incluant 2 éditions :
max-tei-demo et mon-edition -->
<?xml version="1.0"?>
<configuration xmlns:xi="http://www.w3.org/2001/XInclude">
<baseURI/>
<editions>
<xi:include href="../editions/max_tei_demo/max_tei_demo_config_inc.xml"/>
<xi:include href="../editions/mon-edition/mon-edition_config_inc.xml"/>
[...]
</editions>
</configuration>
````
Chaque nouvelle édition implémentée avec l’outil *max.sh* ajoute un élément ``<xi:include>``.
Quand une édition déjà préparée est récupérée, cette ligne peut être ajoutée manuellement.
## Configuration d’une édition
L’édition **mon-edition** sera configurée dans le fichier <span class="dossier">editions</span> > <span class="dossier">mon-edition</span> > <span class="fichier">mon-edition_config_inc.xml</span>.
````
<!-- Exemple de fichier de configuration par défaut, sans option, ni surcharge, ni plugin-->
<edition xml:id="mon-edition" dbpath="moneditiondb" env="tei" prettyName="Mon Édition">
</edition>
````
* ``@xml:id`` : identifiant de l’édition. Toutes les URLs de consultation commencent par cet identifiant,
* ``@dbpath`` : nom de la base de données contenant les sources XML consultables,
* ``@env`` : grammaire XML de l’édition (tei ou ead),
* ``@prettyName`` : titre de l’édition qui pourra être récupéré sous forme de variable et affiché à divers endroits du site.
Ce fichier contiendra si nécessaire, la [configuration des options de lecture](../text/#options-de-lecture), l’activation et le paramètrage de [l’alignement](../text/#alignement) et des [plugins](../plugins).
/* Flowchart variables */
/* Sequence Diagram variables */
/* Gantt chart variables */
.mermaid .label {
color: #274868;
text-align: center;
}
.node rect,
.node circle,
.node ellipse,
.node polygon {
color: #274868;
fill: #FFF;
stroke: #274868;
stroke-width: 1px;
}
.edgePath .path {
stroke: #333333;
}
.edgeLabel {
background-color: #e8e8e8;
}
.cluster rect {
fill: #ffffde !important;
rx: 4 !important;
stroke: #aaaa33 !important;
stroke-width: 1px !important;
}
.cluster text {
fill: #333;
}
.actor {
stroke: #CCCCFF;
fill: #ECECFF;
}
text.actor {
fill: black;
stroke: none;
}
.actor-line {
stroke: grey;
}
.messageLine0 {
stroke-width: 1.5;
stroke-dasharray: "2 2";
marker-end: "url(#arrowhead)";
stroke: #333;
}
.messageLine1 {
stroke-width: 1.5;
stroke-dasharray: "2 2";
stroke: #333;
}
#arrowhead {
fill: #333;
}
#crosshead path {
fill: #333 !important;
stroke: #333 !important;
}
.messageText {
fill: #333;
stroke: none;
}
.labelBox {
stroke: #CCCCFF;
fill: #ECECFF;
}
.labelText {
fill: black;
stroke: none;
}
.loopText {
fill: black;
stroke: none;
}
.loopLine {
stroke-width: 2;
stroke-dasharray: "2 2";
marker-end: "url(#arrowhead)";
stroke: #CCCCFF;
}
.note {
stroke: #aaaa33;
fill: #fff5ad;
}
.noteText {
fill: black;
stroke: none;
font-family: 'trebuchet ms', verdana, arial;
font-size: 14px;
}
/** Section styling */
.section {
stroke: none;
/* below commented out because it conflicts with the readthedocs theme */
/* opacity: 0.2; */
}
.section0 {
fill: rgba(102, 102, 255, 0.49);
}
.section2 {
fill: #fff400;
}
.section1,
.section3 {
fill: white;
opacity: 0.2;
}
.sectionTitle0 {
fill: #333;
}
.sectionTitle1 {
fill: #333;
}
.sectionTitle2 {
fill: #333;
}
.sectionTitle3 {
fill: #333;
}
.sectionTitle {
text-anchor: start;
font-size: 11px;
text-height: 14px;
}
/* Grid and axis */
.grid .tick {
stroke: lightgrey;
opacity: 0.3;
shape-rendering: crispEdges;
}
.grid path {
stroke-width: 0;
}
/* Today line */
.today {
fill: none;
stroke: red;
stroke-width: 2px;
}
/* Task styling */
/* Default task */
.task {
stroke-width: 2;
}
.taskText {
text-anchor: middle;
font-size: 11px;
}
.taskTextOutsideRight {
fill: black;
text-anchor: start;
font-size: 11px;
}
.taskTextOutsideLeft {
fill: black;
text-anchor: end;
font-size: 11px;
}
/* Specific task settings for the sections*/
.taskText0,
.taskText1,
.taskText2,
.taskText3 {
fill: white;
}
.task0,
.task1,
.task2,
.task3 {
fill: #8a90dd;
stroke: #534fbc;
}
.taskTextOutside0,
.taskTextOutside2 {
fill: black;
}
.taskTextOutside1,
.taskTextOutside3 {
fill: black;
}
/* Active task */
.active0,
.active1,
.active2,
.active3 {
fill: #bfc7ff;
stroke: #534fbc;
}
.activeText0,
.activeText1,
.activeText2,
.activeText3 {
fill: black !important;
}
/* Completed task */
.done0,
.done1,
.done2,
.done3 {
stroke: grey;
fill: lightgrey;
stroke-width: 2;
}
.doneText0,
.doneText1,
.doneText2,
.doneText3 {
fill: black !important;
}
/* Tasks on the critical line */
.crit0,
.crit1,
.crit2,
.crit3 {
stroke: #ff8888;
fill: red;
stroke-width: 2;
}
.activeCrit0,
.activeCrit1,
.activeCrit2,
.activeCrit3 {
stroke: #ff8888;
fill: #bfc7ff;
stroke-width: 2;
}
.doneCrit0,
.doneCrit1,
.doneCrit2,
.doneCrit3 {
stroke: #ff8888;
fill: lightgrey;
stroke-width: 2;
cursor: pointer;
shape-rendering: crispEdges;
}
.doneCritText0,
.doneCritText1,
.doneCritText2,
.doneCritText3 {
fill: black !important;
}
.activeCritText0,
.activeCritText1,
.activeCritText2,
.activeCritText3 {
fill: black !important;
}
.titleText {
text-anchor: middle;
font-size: 18px;
fill: black;
}
/*
*/
.node text {
font-family: 'trebuchet ms', verdana, arial;
font-size: 14px;
}
div.mermaidTooltip {
position: absolute;
text-align: center;
max-width: 200px;
padding: 2px;
font-family: 'trebuchet ms', verdana, arial;
font-size: 12px;
background: #ffffde;
border: 1px solid #aaaa33;
border-radius: 2px;
pointer-events: none;
z-index: 100;
}
\ No newline at end of file
div.wy-side-nav-search {
z-index: 200;
background-color: #93A9BE;
text-align: center;
padding: 0.809em;
display: block;
color: #fcfcfc;
margin-bottom: 0.809em;
}
body {
font-family: "Lato", "proxima-nova", "Helvetica Neue", Arial, sans-serif;
font-weight: normal;
background-color: #274868;
}
body.wy-body-for-nav {
background-color: #274868;
}
nav.wy-nav-side {
position: absolute;
top: 0;
left: 0;
width: 300px;
overflow: hidden;
overflow-y: hidden;
min-height: 100%;
background: #274868;
z-index: 200;
}
.rst-versions {
background: #274868;
}
.rst-versions .rst-current-version {
padding: 12px;
background-color: #274868;
display: block;
text-align: right;
font-size: 90%;
cursor: pointer;
color: #27AE60;
*zoom: 1;
}
.wy-menu-vertical li.current {
background-color: #97AABD;
}
li.current>a.current {
background: #6F8199;
}
.wy-menu-vertical a {
display: inline-block;
line-height: 18px;
padding: 0.4045em 1.618em;
display: block;
position: relative;
font-size: 90%;
color: #fff;
}
code,
.rst-content tt {
white-space: nowrap;
max-width: 100%;
background: #fff;
border: solid 1px #e1e4e5;
font-size: 75%;
padding: 0 5px;
font-family: Consolas, "Andale Mono WT", "Andale Mono", "Lucida Console", "Lucida Sans Typewriter", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Liberation Mono", "Nimbus Mono L", Monaco, "Courier New", Courier, monospace;
color: #0096FF;
overflow-x: auto;
}
.fichier {
color: #5F9EA0;
}
.dossier {
color: #5F9EA0;
font-weight: bold;
}
.projet {
font-style: italic;
}
span.voc {
color: #274868;
font-weight: bold;
}
\ No newline at end of file
# [Docker*](../glossary/#d)
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 !).
Voici la procédure pour la création de l’image d’une édition (exemple avec l’édition de démonstration TEI) et le lancement du [container*](../glossary/#c) accessible sur le port 9999 (base XML du projet stockée dans /<span class="dossier">opt</class>/<span class="dossier">basex</class>/<span class="dossier">data</class>/<span class="dossier">max_TEI_demo</span> :
* Création de l’édition de démonstration
```
./tools/max.sh -i && ./tools/max.sh -d
```
* Ajout des droits sur les données de la base pour le container :
```
$ sudo chown -R 1984 /opt/basex/data/max_TEI_demo
```
* Création de l’image de l’édition puis lancement du container :
```
$ sudo docker build -t unicaen/max_TEI_demo .
$ sudo docker run -d -p 9999:8984 --volume /opt/basex/data/max_TEI_demo:/srv/basex/data/max_TEI_demo unicaen/max_TEI_demo
```
# Fonctionnement
## Fonctionnalités et adresses URL associées
Lors de la consultation d’une page d’une édition, MaX se base sur l’URL interrogée. C’est cette URL qui va permettre de déclencher un ensemble de traitements (de l’affichage d’une page HTML simple, au requêtage de la base de données XML pour générer une nouvelle page HTML *via* une transformation XSL).
L’URL contient systématiquement l’identifiant de l’édition consultée. Cet identifiant, en plus d’autres paramètres optionnels, permettent de construire le document adéquat, en s’appuyant également sur le fichier de configuration de l’édition (pour les options d’affichage ou l’utilisation des plugins par exemple).
Les principales URLs de consultation sont les suivantes :
* Page d’accueil d’une édition ([plus d’info](../home_page)) :
`http://[host]:[port]/[edition]/accueil.html`
* Sommaire d’une édition (liste des documents XML consultables) ([plus d’info](../toc/#sommaire-dune-edition)) :
`http://[host]:[port]/[edition]/sommaire.html`
* Sommaire d’un document d’une édition ([plus d’info](../toc/#sommaire-dun-document)) :
`http://[host]:[port]/[edition]/sommaire/[document].html`
* Consultation d’un document d’une édition ([plus d’info](../text)) :
`http://[host]:[port]/[edition]/doc/[document].html`
* Consultation d’un fragment identifié (xml:id) d’une édition ([plus d’info](../text)) :
`http://[host]:[port]/[edition]/[document].xml/[id].html`
* Consultation d’un [contenu html statique*](../glossary/#c) ([plus d’info](../static_pages)) :
`http://[host]:[port]/[edition]/[page].html`
## Chaîne de traitement
Lors de la consultation d’un sommaire, d’un document ou d’un fragment, MaX effectue les opérations suivantes :
1. Requêtage XQUERY pour la récupération des données (liste de documents, document complet, fragment identifié, etc.).
2. Transformation de ces données en un contenu HTML par application de templates XSLT.
3. Création d’une page HTML complète (à partir d’un template HTML) contenant les données transformées, les blocs de navigation, menu, etc. ainsi que les imports CSS et Javascript nécessaires.
4. Exécution des éventuels plugins au sein du navigateur.
<div class="mermaid">
graph LR;
XML--"Requêtes xquery"-->XQ
XQ--"transformations"-->XSL
XSL--"template + CSS + JS"-->HTML
HTML--"plugins"-->HTML2
XML(("Base de données<br/>fichiers(s) XML"))
XQ["XQ"]
HTML("HTML")
HTML2("HTML<br/>augmenté")
</div>
\ No newline at end of file
# Organisation des dossiers et des fichiers
## Le dossier projet-MaX
L’application MaX s’organise selon l’arborescence suivante :
<div class="mermaid">
graph LR;
classDef default color:#274868, fill:#fff, stroke:#274868;
max-->A
max-->B
max-->C
max-->D
max-->E
max-->F
max-->G
max-->H
max-->I
max-->J
A-->A1
C-.->C1
H-->H1
H-->H2
H-->H3
H-->H4
H-->H5
H-->H6
H-->H7
H-->H8
</