Commit c3f52d35 authored by Jerome Chauveau's avatar Jerome Chauveau
Browse files

Merge branch 'pdn/doc' into 'dev' 

Pdn/doc

See merge request pdn-certic/MaX!57
parents c00b0108 62d4bd59

documentation/docs/config.md

+22 −32
Original line number Diff line number Diff line 
# Configuration



## Configuration générale de MaX



## Fichiers de configuration

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.



### Configuration générale de MaX

Le fichier *configuration/configuration.xml* 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 : demo_lorem et mon_edition-->

<!-- 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/demo_lorem/demo_lorem_config_inc.xml"/>

    <xi:include href="../editions/mon_edition/mon_edition_config_inc.xml"/>

    <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>



````



### Configuration d'une édition

Chaque nouvelle édition implémentée avec l’outil *max.sh* ajoute un élément ``<xi:include>``.



L'édition *my_edition* sera configurée dans le fichier *editions/mon_edition/mon_edition_config_inc.xml*.

Quand une édition déjà préparée est récupérée, cette ligne peut être ajoutée manuellement.



```

<!-- Exemple de fichier de configuration par défaut, sans option ni surcharge si plugin-->

## Configuration d’une édition



<edition xml:id="mon_edition" dbpath="moneditiondb" env="tei">

</edition>

```

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-->



* @xml:id : identifiant de l'édition. Toutes les urls de consultation commencent par cet id

* @dbpath : Nom de la base de données contenant les sources consultables

* @env    : Grammaire XML de l'édition

<edition xml:id="mon-edition" dbpath="moneditiondb" env="tei" prettyName="Mon Édition">

</edition>

````





Ce fichier contiendra si nécessaire, la [configuration des options de lecture](../reading_options), l'activation et le paramètrage de

[l'alignement](../alignment) et des [plugins](../plugins).

* ``@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.



#### La variable baseURI



Pour un site déployé sur une URL autre que la racine de l'hôte, la variable *baseURI* doit être renseignée dans le fichier

*configuration/configuration.xml*. Par exemple, pour un site publié à l'adresse https://site.domain.ext/app/ :

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).

```

<?xml version="1.0"?>

<configuration xmlns:xi="http://www.w3.org/2001/XInclude">

  <baseURI>/app/</baseURI>

  [...]  

</configuration>

```
 
 No newline at end of file

documentation/docs/css/mermaid.css

0 → 100644
+352 −0
Original line number Diff line number Diff line 
/* 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

documentation/docs/css/test.css

0 → 100644
+95 −0
Original line number Diff line number Diff line 
        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

documentation/docs/docker.md

+10 −11
Original line number Diff line number Diff line 
# Docker

# [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 !).

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 !).



* 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* :

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

* Création de l’édition de démonstration



```

$ ./tools/max.sh -i && ./tools/max.sh -d



./tools/max.sh -i && ./tools/max.sh -d

```



Ajout des droits sur les données de la base pour le container :

* Ajout des droits sur les données de la base pour le container :



```

$ sudo chown -R 1984 /opt/basex/data/max_demo_lorem

$ sudo chown -R 1984 /opt/basex/data/max_TEI_demo

```



Création de l'image de l'édition puis lancement du container :

* Création de l’image de l’édition puis lancement du container :



```

 $ sudo docker build -t unicaen/max_demo_lorem .

 $ sudo docker run -d -p 9999:8984 --volume /opt/basex/data/max_demo_lorem:/srv/basex/data/max_demo_lorem unicaen/max_demo_lorem

 $ 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

```

documentation/docs/features.md

+48 −14
Original line number Diff line number Diff line 
# Fonctionnalités et URLs associées

# Fonctionnement 



## Fonctionnalités et adresses URL associées



* `/[edition]/accueil.html` Page d'accueil d'une édition

* `/[edition]/sommaire.html` Sommaire d'une édition (liste des documents XML consultables)

* `/[edition]/sommaire/[document].html` Sommaire d'un document d'une édition

* `/[edition]/[document].xml/[id].html` Consultation d'un fragment identifié, d'un document d'une édition

* `/[edition]/doc/[document].xml/[id].html` Consultation d'un document d'une édition

* `/[edition]/[page].html` Consultation d'un contenu html statique

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).



# Chaîne de traitement

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).



Lors de la consultation d'un sommaire, d'un document ou d'un fragment, MaX effectue les opérations suivantes :

Les principales URLs de consultation sont les suivantes :



1. requêtage XQUERY pour récupération des données (liste de document, 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) 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 Javascript au sein du navigateur
 
* 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