Skip to content

H
hdoc
Switch branch/tag
Find file Normal viewHistoryPermalink
README.md 3.3 KB
Newer Older
Fabien Boucaud's avatar
Update README.md adding product backlog, user story and credits  
Fabien Boucaud committed
1 
# Converter framapad_to_hdoc
qaomia's avatar
add documentation  
qaomia committed
2 3 4 5 6 

## License
License GPL3.0
http://www.gnu.org/licenses/gpl-3.0.txt
Jean Vintache's avatar
fix readmes  
Jean Vintache committed
7 
## Credits
Fabien Boucaud's avatar
Update README.md adding product backlog, user story and credits  
Fabien Boucaud committed
8 9 10 
- 2016
-   - Etienne Chognard
-   - Fabien Boucaud
Jean Vintache's avatar
change credits in readme  
Jean Vintache committed
11 12 13 14 15 16 
- 2015
    - Jean-Côme Douteau
    - Gabrielle Rit
    - Jean Vintache
- 2014
    - Fecherolle Cécile
qaomia's avatar
add documentation  
qaomia committed
17 18 19 20 21 22 

## Presentation
This module is able to convert several [etherpad](http://etherpad.org/) files (exported as html files) to the hdoc format.

## User documentation
Fabien Boucaud's avatar
Update README.md adding product backlog, user story and credits  
Fabien Boucaud committed
23 24 25 26 
## User Story

Vous êtes un utilisateur de framapad et en créez un pour un projet. Après avoir travaillé sur votre pad, vous souhaitez transformer ce document en un autre format que vous pourrez utiliser dans un nouveau contexte de travail. Pour ce faire, vous exportez le framapad au format HTML grâce au bouton « Import/Export ». Vous récupérez ensuite les fichiers nécessaires à la transformation framapad to hdoc sur le répertoire git du projet hdoc (voir http://hdoc.crzt.fr/). Il ne vous reste alors plus qu'à placer le fichier html précédemment récupéré dans le dossier « input » du dossier framapad_to_hdoc et à exécuter le /run.bat si vous êtes sur Windows ou le /run.sh si vous êtes sur Linux/Mac. Cela produira une archive .hdoc dont l'intérêt est de servir de format de passage pour une transformation d'un format à un autre, et ce pour une grande variété de format. Il vous restera ensuite à déterminer le nouveau format dans lequel vous voulez transformer votre hdoc et utiliser le convertisseur approprié s'il existe.
Jean Vintache's avatar
fix readmes  
Jean Vintache committed
27 28 29 30 31 
## Running etherpad_to_hdoc.ant
1. Create an etherpad document and export it as an html file.
2. please place your html files in the `/input` folder
3. run the `run.[bat|sh]` script of your choice depending on your OS
4. and retrieve the hdoc outputs in the `/output` folder
qaomia's avatar
add documentation  
qaomia committed
32 33 

## Unsupported
Jean Vintache's avatar
fix readmes  
Jean Vintache committed
34 35 36 37 
- Markdown
- Author paternity
- Etherpad timeline
- Chat
qaomia's avatar
add documentation  
qaomia committed
38 39 

## Known bugs
qaomia's avatar
documentation completed  
qaomia committed
40 
- Nested lists in lists are not supported
qaomia's avatar
documentation completed  
qaomia committed
41 42 43 44 45 46 47 48 49 50 
Example : 
`<ul>
	<li>
		<ul>
			<li>
			Never gonna give you up.
			</li>
		</ul>
	</li>
<ul>`
qaomia's avatar
documentation completed  
qaomia committed
51 
- As a consequence, etherpad indentation is not supported because it is coded as nested lists.
Jean Vintache's avatar
fix readmes  
Jean Vintache committed
52
Fabien Boucaud's avatar
Update README.md adding product backlog, user story and credits  
Fabien Boucaud committed
53 54 55 56 
## Product Backlog

Currently available on: https://framemo.org/framapad_to_opale
qaomia's avatar
add documentation  
qaomia committed
57 
## TODO
Jean Vintache's avatar
fix readmes  
Jean Vintache committed
58 
- Markdown
qaomia's avatar
add documentation  
qaomia committed
59 60 61 62 63 

## Technical notes
### Description of etherpad_to_hdoc.ant

#### Prelude
Jean Vintache's avatar
fix readmes  
Jean Vintache committed
64 65 
- Importation of necessary classes (antlib, htmlcleaner, jing)
- Creation of directories architecture tree
qaomia's avatar
add documentation  
qaomia committed
66 67 

#### Transformations
Jean Vintache's avatar
fix readmes  
Jean Vintache committed
68 69 70 71 72 73 
- Use of htmlcleaner to transform the input file from html to xhtml. For more info, see http://htmlcleaner.sourceforge.net/index.php.
- Apply html2xhtml.xsl : this xsl extracts the content into <body> tags
- 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
qaomia's avatar
add documentation  
qaomia committed
74 75 

#### Post-transformations actions
Jean Vintache's avatar
fix readmes  
Jean Vintache committed
76 77 78 
- Build hdoc structure
- Jing checks if the output file is validated with the right rng schema
- Zip the directory into hdoc archive
qaomia's avatar
add documentation  
qaomia committed
79
qaomia's avatar
documentation completed  
qaomia committed
80 
### Supported tags
Jean Vintache's avatar
fix readmes  
Jean Vintache committed
81 82 83 84 85 
- html tags -> hdoc tags
- u, s, em, strong -> em
- li -> li
- ol -> ol
- br -> p
qaomia's avatar
documentation completed  
qaomia committed
86 87 

## Capitalisation
jcomedouteau's avatar
Change readme etherpad to hdoc  
jcomedouteau committed
88 
Using regular expression with xsl is a good way to parse a non xml file.