Commit 0047b7c3 authored by Etienne Chognard's avatar Etienne Chognard

Update Readme

parents de61bee1 9746a5fc
......@@ -16,7 +16,7 @@ http://www.gnu.org/licenses/gpl-3.0.txt
- Fecherolle Cécile
## Presentation
This module is able to convert several [framad](https://framapad.org/) files (exported as html files) to the hdoc format.
This module is able to convert several [framapad](https://framapad.org/) files (exported as html files) to the hdoc format.
## User documentation
......@@ -32,14 +32,15 @@ Vous êtes un utilisateur de framapad et en créez un pour un projet. Après avo
## Product Backlog
Currently available on: https://framemo.org/framapad_to_opale
Currently (january 2017) available on: https://framemo.org/framapad_to_opale
See also : https://bimestriel.framapad.org/p/nf29_framapad_to_opale for the full documentation of our working process.
## TODO
- Implémenter la gestion du code
- Gerer parfaitement les indentations
- (Possibilité d'utiliser des tags pour typer les sections)
- Code tags
- Markdown
- Tags for typing the structure
## Technical notes
### Description of framapad_to_hdoc.ant
......@@ -54,7 +55,9 @@ See also : https://bimestriel.framapad.org/p/nf29_framapad_to_opale for the full
- Apply html2xhtmlv1.xsl : this xsl is used as a fix and adds br tag at the end of lists (ul and ol)
- Apply html2xhtmlv2.xsl : this xsl surround text line with p tags and transforms non-hdoc tags into hdoc tags as s, u, strong tags.
- Apply html2xhtml3.xsl : this xsl is used as a fix, it deletes p tags when its child is ul or ol
- Apply xhtml2hdoc.xsl : this xsl transforms the content into hdoc structure
- Apply html2hdocstruct1 to 6 : those xsl files are dedicated to building the hdoc structure based on the titles h1 to h6
- Apply html2hdocstructdivsection: this xsl completes the sections created in the previous xsl with <div> around the actual content of each level
- Apply xhtml2hdoc.xsl : this xsl transforms the content into hdoc structure and changes the namespace
#### Post-transformations actions
- Build hdoc structure
......@@ -63,16 +66,20 @@ See also : https://bimestriel.framapad.org/p/nf29_framapad_to_opale for the full
### Supported tags
- html tags -> hdoc tags
- u, s, em, strong -> em
- u, s, em, strong, color -> em
- sub -> sub
- sup -> sup
- li -> li
- ol -> ol
- br -> p
- title tags (h1 to h6) -> section or division or ...
- span color -> em
- code -> p with a message to say that it's code
###Titles
- If it's h1 -> new section
- If following title is not h1 -> new division in the section
- If following title is at the same level -> new division at the same level
- If following title is at a lower level -> new division in the previous division
## Capitalisation
Using regular expression with xsl is a good way to parse a non xml file.
We can note about the creation of the hdoc's structure with the titles h1 to h6 that XSLT is probably not the best tool for these specific transformations. Something like SAX, which actually explore the XML files sequentially, would probably be more efficient and easier to use for these kinds of transformations.
......@@ -42,6 +42,9 @@ Filepaths in this document are relative to this readme file.
- Apply html2xhtmlv1.xsl : this xsl is used as a fix and adds br tag at the end of lists (ul and ol)
- Apply html2xhtmlv2.xsl : this xsl surround text line with p tags and transforms non-hdoc tags into hdoc tags as s, u, strong tags.
- Apply html2xhtml3.xsl : this xsl is used as a fix, it deletes p tags when its child is ul or ol
- Apply html2hdocstruct1 to 6 : those xsl files are dedicated to building the hdoc structure based on the titles h1 to h6
- Apply html2hdocstructdivsection: this xsl completes the sections created in the previous xsl with
around the actual content of each level
- Apply xhtml2hdoc.xsl : this xsl transforms the content into hdoc structure
#### Post-transformations actions
......
......@@ -95,6 +95,10 @@
</xsl:if>
</xsl:template>
<!-- Résolution du pb ajouté lors d'une modif de opale_to_cano... -->
<xsl:template match="h:body/h:section[@data-hdoc-type = 'references']"/>
<!-- if Section have only a dev (no sub section), we create a short activty to print text into a seance -->
<xsl:template match="h:body/h:section/h:div">
<sp:shortActivity>
......
......@@ -23,4 +23,30 @@ No depedencies
Pour utiliser ce convertisseur, veuillez suivre les étapes suivantes :
1 - Placer le(s) fichier(s) hdoc que vous souhaitez convertir dans le dossier input (des exemples sont fournis dans le dossier sample).
2 - Lancer l'un des executable run.bat ou run.sh en fonction du système d'exploitation de votre ordinateur.
3 - Récupérer le(s) résultat(s) dans le dossier output.
\ No newline at end of file
3 - Récupérer le(s) résultat(s) au format .json dans le dossier output.
##Conversion
------------
Ce module permet :
- L'extraction des données du header
- Titre
- Auteurs
- Mots clés
- Droits
- L'extraction des exercices conformément aux attentes de Kibana :
- Récupération des exercices et affectation d'un ID unique.
- Association des questions aux exercices grâce aux ID générés précédemment.
##TODO
------
- Prendre en compte les futures modification de la conversion opale_to_hdoc pour les exercices.
- Ajouter la gestion des sections sachant que Kibana ne considère pas les tableaux d'objets JSON. Pour cela, la solution que nous avons retenu :
- Générer des ID via la function generate-id() pour produire une clé de la forme section_ID.
- Ajouter une références vers l'id de la section mère dans chacun des fils. (Ex : "parent" : "section_ID")
##Technical notes
-----------------
Les tabulations lors de la conversion en JSON sont déconseillés car cela pose problème avec Kibana.
\ No newline at end of file
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xpath-default-namespace="http://www.utc.fr/ics/hdoc/xhtml"
exclude-result-prefixes="xs"
version="2.0">
<xsl:output omit-xml-declaration="yes"
encoding="UTF-8">
<!-- Encodage UTF-8 pour caractères spéciaux (accents...) -->
</xsl:output>
<!-- On remplace les quotes dans le texte pour éviter les problèmes de JSON -->
<xsl:param name="pPattern">"</xsl:param>
<xsl:param name="pReplacement">\\"</xsl:param>
<!-- -->
<xsl:template match="/" >
{
<xsl:apply-templates select="html"/>
}
</xsl:template>
<!-- Extraction des informations du head -->
<xsl:template match="head">
"title" : "<xsl:value-of select="title/text()"/>",
"keywords" : [
<xsl:for-each select="meta[@name='keywords']">
"<xsl:value-of select="@content"/>"<xsl:if test="position() != last()">,</xsl:if>
</xsl:for-each>
],
<xsl:apply-templates select="meta"/>
</xsl:template>
<!-- Extraction des informations du body -->
<xsl:template match="body">
<!-- Extraction des sections -->
<xsl:apply-templates select="*/section[@data-hdoc-type='exercise']"/>
</xsl:template>
<xsl:template match="meta[@name='author']">
"author" : "<xsl:value-of select="@content"/>",
</xsl:template>
<xsl:template match="meta[@name='date']">
"date" : "<xsl:value-of select="@content"/>",
</xsl:template>
<xsl:template match="meta[@name='rights']">
"rights" : "<xsl:value-of select="@content"/>",
</xsl:template>
<!-- Traitement des sections -->
<xsl:template match="section[not(@data-hdoc-type='exercise')]"/>
<xsl:template match="section[@data-hdoc-type='exercise']">
"exercice_<xsl:value-of select="generate-id()"/>" : {
"titre" : "<xsl:value-of select="normalize-space(replace(header/h1/text(),$pPattern,$pReplacement))"/>",
<xsl:apply-templates select="div[@data-hdoc-type='description']"/>
} <xsl:if test=". != (//section[@data-hdoc-type='exercise'])[last()] or div[@data-hdoc-type='question']">,</xsl:if>
<!-- On test si c'est le dernier exercice et qu'il n'a pas de question -->
<xsl:apply-templates select="div[@data-hdoc-type='question']">
<xsl:with-param name="prev_id" select="generate-id()"/>
<xsl:with-param name="is_not_last" select=". != (//section[@data-hdoc-type='exercise'])[last()]"/>
</xsl:apply-templates>
</xsl:template>
<!-- Traitement des question -->
<xsl:template match="div[@data-hdoc-type='question']">
<xsl:param name="prev_id"/>
<xsl:param name="is_not_last"/>
"question_<xsl:value-of select="generate-id()"/>" : {
"parent" : "exercice_<xsl:value-of select="$prev_id"/>",
<xsl:apply-templates select="div[@data-hdoc-type='description']"/>
<xsl:apply-templates select="div[@data-hdoc-type='solution']"/>
}<xsl:if test="((position() != last()) or $is_not_last)">,</xsl:if>
<!-- On test si c'est le dernier exercice et la dernière question -->
</xsl:template>
<!-- Traitement de l'élément description -->
<xsl:template match="div[@data-hdoc-type='description']">
"description" : "<xsl:value-of select="normalize-space(replace(./text(),$pPattern,$pReplacement))"/>"
</xsl:template>
<!-- Traitement de l'élément solution -->
<xsl:template match="div[@data-hdoc-type='solution']">
,"solution" : "<xsl:value-of select="normalize-space(replace(./text(),$pPattern,$pReplacement))"/>"
</xsl:template>
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xpath-default-namespace="http://www.utc.fr/ics/hdoc/xhtml"
exclude-result-prefixes="xs"
version="2.0">
<xsl:output omit-xml-declaration="yes"
encoding="UTF-8">
<!-- Encodage UTF-8 pour caractères spéciaux (accents...) -->
</xsl:output>
<!-- On remplace les quotes dans le texte pour éviter les problèmes de JSON -->
<xsl:param name="pPattern">"</xsl:param>
<xsl:param name="pReplacement">\\"</xsl:param>
<!-- -->
<xsl:template match="/" >
{
<xsl:apply-templates select="html"/>
}
</xsl:template>
<!-- Extraction des informations du head -->
<xsl:template match="head">
"title" : "<xsl:value-of select="normalize-space(title/text())"/>",
"keywords" : [
<xsl:for-each select="meta[@name='keywords']">
"<xsl:value-of select="@content"/>"<xsl:if test="position() != last()">,</xsl:if>
</xsl:for-each>
],
<xsl:apply-templates select="meta"/>
</xsl:template>
<!-- Extraction des informations du body -->
<xsl:template match="body">
<!-- Extraction des sections -->
<xsl:apply-templates select="*/section[@data-hdoc-type='exercise']"/>
</xsl:template>
<xsl:template match="meta[@name='author']">
"author" : "<xsl:value-of select="normalize-space(@content)"/>",
</xsl:template>
<xsl:template match="meta[@name='date']">
"date" : "<xsl:value-of select="normalize-space(@content)"/>",
</xsl:template>
<xsl:template match="meta[@name='rights']">
"rights" : "<xsl:value-of select="normalize-space(@content)"/>",
</xsl:template>
<!-- Traitement des sections -->
<xsl:template match="section[not(@data-hdoc-type='exercise')]"/>
<xsl:template match="section[@data-hdoc-type='exercise']">
"exercice_<xsl:value-of select="generate-id()"/>" : {
"titre" : "<xsl:value-of select="normalize-space(replace(header/h1/text(),$pPattern,$pReplacement))"/>",
<xsl:apply-templates select="div[@data-hdoc-type='description']"/>
} <xsl:if test=". != (//section[@data-hdoc-type='exercise'])[last()] or div[@data-hdoc-type='question']">,</xsl:if>
<!-- On test si c'est le dernier exercice et qu'il n'a pas de question -->
<xsl:apply-templates select="div[@data-hdoc-type='question']">
<xsl:with-param name="prev_id" select="generate-id()"/>
<xsl:with-param name="is_not_last" select=". != (//section[@data-hdoc-type='exercise'])[last()]"/>
</xsl:apply-templates>
</xsl:template>
<!-- Traitement des question -->
<xsl:template match="div[@data-hdoc-type='question']">
<xsl:param name="prev_id"/>
<xsl:param name="is_not_last"/>
"question_<xsl:value-of select="generate-id()"/>" : {
"parent" : "exercice_<xsl:value-of select="$prev_id"/>",
<xsl:apply-templates select="div[@data-hdoc-type='description']"/>
<xsl:apply-templates select="div[@data-hdoc-type='solution']"/>
}<xsl:if test="((position() != last()) or $is_not_last)">,</xsl:if>
<!-- On test si c'est le dernier exercice et la dernière question -->
</xsl:template>
<!-- Traitement de l'élément description -->
<xsl:template match="div[@data-hdoc-type='description']">
"description" : "<xsl:value-of select="normalize-space(replace(./text(),$pPattern,$pReplacement))"/>"
</xsl:template>
<!-- Traitement de l'élément solution -->
<xsl:template match="div[@data-hdoc-type='solution']">
,"solution" : "<xsl:value-of select="normalize-space(replace(./text(),$pPattern,$pReplacement))"/>"
</xsl:template>
</xsl:stylesheet>
\ No newline at end of file
......@@ -101,6 +101,7 @@ Ce qui n'est pas implémenté dans la conversion opale_to_hdoc c'est-à-dire :
Known bugs
----------
data-hdoc-type="references" : liste à puce inversé (<li><ul></ul><ul></ul></li>)
Todo list
---------
......
......@@ -53,3 +53,13 @@ Etapes :
- Vous devriez voir un dashboard et des objets dans "vizualisation" s'ajouter à votre liste de saved objects
- Allez dans Dashboard, cliquez sur "Open" et sélectionnez le dashboard ajouté (Normalement "NF29_DATA_DASHBOARD")
- Vous pouvez cliquez sur les différents éléments des graphiques pour filtrer les informations, les graphiques s'actualiseront en fonction.
##Bugs connus
-------------
- Logstash ne prend pas toujours en compte tout de suite le fichier une fois ajouté au dossier, il faut parfois l'éteindre/le relancer
- Kibana ne reconnait pas les champs JSON si une/des tabulations se retrouvent devant le nom du champ.
##Idée d'amélioration
-------------
- Maintenant que hdoc_to_elasticSearch permet la gestion des exercices / questions, ajouter des graphiques utiles à l'analyse de ceux-ci
- Former un dossier de requête REST pré-formulées pour pouvoir récupérer facilement les informations qui nous intéressent après filtrage des données grâce aux graphiques Kibana
......@@ -99,6 +99,7 @@ Ce qui n'est pas implémenté dans la conversion opale_to_hdoc c'est-à-dire :
Known bugs
----------
bug conversion opale_to_hdoc => data-hdoc-type="references" : liste à puce inversé (<li><ul></ul><ul></ul></li>)
Todo list
---------
......
......@@ -308,7 +308,7 @@
<!-- content Information : no microformat -->
<xsl:template match="sp:pb/op:pb/sp:info">
<div>
<div data-hdoc-type="information">
<xsl:apply-templates select="./op:pbTi/sp:title"/>
<xsl:apply-templates select="op:res/*"/>
</div>
......@@ -355,7 +355,7 @@
<xsl:apply-templates select="op:res/*"/>
</div>
</xsl:template>
<!-- content method : advice -->
<!-- content method : method -->
<xsl:template match="sp:pb/op:pb/sp:meth">
<div data-hdoc-type="advice">
<xsl:apply-templates select="./op:pbTi/sp:title"/>
......@@ -376,21 +376,21 @@
<xsl:apply-templates select="op:res/*"/>
</div>
</xsl:template>
<!-- content syntax : no microformat (we lose this information) -->
<!-- content syntax : complement -->
<xsl:template match="sp:pb/op:pb/sp:syntax">
<div>
<div data-hdoc-type="information">
<xsl:apply-templates select="./op:pbTi/sp:title"/>
<xsl:apply-templates select="op:res/*"/>
</div>
</xsl:template>
<!-- content legal : no microformat (we lose this information) -->
<!-- content legal : complement -->
<xsl:template match="sp:pb/op:pb/sp:legal">
<div>
<div data-hdoc-type="information">
<xsl:apply-templates select="./op:pbTi/sp:title"/>
<xsl:apply-templates select="op:res/*"/>
</div>
</xsl:template>
<!-- content simulation : no microformat (we lose this information) -->
<xsl:template match="sp:pb/op:pb/sp:simul">
<div>
......
......@@ -51,6 +51,7 @@
<value>advice</value>
<value>remind</value>
<value>method</value>
<value>information</value>
<!-- quiz management -->
<value>question</value>
<value>singlechoicequestion</value>
......
Markdown is supported
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