Technical documentation

Introduction

The goal of my project is to convert the dokiel format to the Hdoc format.

The project contains :

  • Dokiel_to_hdoc.ant : Ant file

  • "src" directory : which contains all source files

    • assemble.xsl : assemble all data in the scar in one xml file (exclude all the images files for the copy)

    • conversion.xsl : convert the generated file with "assemble.xsl" to the hdoc format

    • move_ressource_file.xsl : copy alll the ressource in specified directory

    • container.xsl : add a namespace to the file container.xml

  • "hdoc/dokiel.hdoc" : the result hdoc

  • "tmp","scar" and "regrouper" directories : temporal directories only use for the transformation

All the source codes (Ant file, assemble.xsl and conversion.xsl) are commented.

Dokiel_to_hdoc.ant

I use this Ant which executes different tasks :

  • "init" : create directories for the unzip of the scar , for the hdoc format before the compression and for the xml file which contains all data.

  • "clean" : delete old directories created by an previous execution of the same Ant

  • "construct_hdoc" : create the hdoc structure, by creating META-INF and images directories, then mimetype and container files.

  • "fill_container" : fill the container with the root files information path

  • "namespace" : add the namespace to the container

  • "assemble" : launch the xslt conversion using assemble.xsl

  • "verify" : check if the scar contains only one main file, if not an error message is sent

  • "copy_ressource" : copy all ressource of the scar to the ressource directory of the hdoc

  • "convert" : launch xslt conversion with conversion.xsl

assemble.xsl

This file will allow to have all the scar data in one xml file.

In this xsl, I copy all nodes of the root File in intermediare.xml file and when I find a "refUri" attribute, I copy all data from the appropriate file.

The refUri attribute in the dokiel format means that the document call an external source like a section or a picture.

All the picutures are excludes for the copy.

container.xsl

Add a namespace container01.xml created in the ant.

move_ressource_file.xsl

Prepare a ant for copying the ressource. This ant handle relative path as far as we have th absolute path in & directory.

DokielHdoc.xsl

This xsl is applied to all .ref file. And it convert it to bibtex format,it's coming from bibtex project.

conversion.xsl

This file converts the file generated by assemble.xsl to the hdoc format.

The xsl do :

  • create all meta data in the header of the html- except version, editor and copyright which are not covered by html-.

  • put <div> for all the blocks (like information, warning, ...). Also an attribute "data-hdoc-type" is added for advice, warning, exemple and complement blocks.

  • conversion of tables, lists and inlines.

  • conversion of pictures. "src" and "alt" attributes are initialized with path and the name of the picture.

  • conversion of video "src" is initialized with path .

  • conversion of .ref (reference) .

  • conversion of other ressource "src" is initialized with path .

  • conversion of part. A part is a special block which contains other blocks, so a part becomes a <section>.

The Dokiel format have three fondamental items, all treated by the xsl :

  • procedure : it allows to describe an action with a list of steps. I chose to create a <section> for each step of the procedure. For each part of one step which is "detailled description"," complement" and "result", I also create a <section>. There is also a <section> for each altenative procedure in the procedure.

  • concept : it enables to explain a term or a concept with definition and description. There is a <section> for each concept and also for each description.

  • screen : it allows to give a detailed description of a screenshot by using graphically defined areas. The xsl create a <section> for each screen and notification area.

Error messages

One error is managed by the Ant file :

  • "you have too many rootfiles (${count.pub})." : this error means that you have more than one root file in scar file root. To correct this error, you have to reexport your scar by following Demo user guide.