Skip to content
  Kermeta  
 

Building documentation for Kermeta

Document Actions

This page describe how to contribute to Kermeta documentation.

In order to obtain a nice looking a good quality for our documents, we use a special process to write the documentation of Kermeta.


Get the documentation sources from the CVS

The sources of the documentation is in CVS into kermeta_projects/fr.irisa.triskell.kermeta.documentation

Please refer to the developer guide wich describes how to connect to the CVS.

In the src folder, you'll find :

  • a set of ant script (*_build.xml) that automates all the build process
  • some code used to build automatically some documents (ex: html, java, templates are used to build the framework documentation)
  • the OpenOffice files corresponding to the various document.


Get and configure the transformation scripts

In order to transform those OpenOffice documents we use several scripts. (you should run them from the provided ant scripts)

OpenOffice 2 docbook (OOo2dbk)

The first step is to translate the OpenOffice files into docbook files.

It uses the OOo2dbk tool. Note that it currently (06/2006) only supports the 1.x version of OpenOffice (*.sxw), so you'll have to use "save as" if you want to use openOffice2.0.

This script works better if there is xsltproc in the user classpath.

Note: Member of Triskell team can use a preinstalled version of both xsltproc and OOo2dbk in the team disk.

Docbook 2 final formats

The second step is to write the document in the supported formats. We use some templates and additional xslt transformation to build all the format we need. (the most important for us are HTML, Eclipse help and PDF)

Those scripts and templates are available in the CVS : docbook_projects/ant-docbook-styler

This a customized version of the original ant docbook styler.


Writting rules

Ok, now you are ready to rebuild  existing documents, just run the ant scripts

If you want to update a document you need to apply the following rules. Many of them are due to limitations of the script.

  1. Be sure to retreive the latest version of the OO document. Then, notify us via the kermeta-developers@gforge.inria.fr that you are modifying a document. This is needed because, CVS is not able help in case of conflicting changes in OO document. CVS is used only for versionning here. So we really need to avoid conflicts on those files.
  2. Images must be insterted as link. Even if OOo2dbk allows to export embedded images, that a little bit complex (needs to start OO in server mode so the script can call it) and our current scripts don't use this feature. The best is to put all the images in the dedicated directory ( DocName_figures) and link it.
  3. The legend of the images must be "Illustration" the other kind of legends doesn't to tranlate correctly
  4. Use supported styles. Various styles are supportes :  all the classic "title x", +some more specialized like "ProgramListing" that keeps the indentation, or "Tip", "Warning", "Note", "Caution". For all those paragraph styles, if you want to use cariage return in the same paragraph, you need to use the "<shift>+<return>". (Tip: a simple macro that goes to the end of the line, remove the current cariage return and insert the <shift>+<return> is very useful to fix a code that was copied from your favorite editor)
  5. Variables ("Champs") Some variables are used for the global metadate of the docbook document.... ( TODO : Explain that a little more)
  6. Internal link are allowed, however, some seem to work better than other. The prefered way is to : insert a "repère de texte" (sorry I have a French version and I've no clue how it's translated in the english one "Text tag" ?) at the location where you want to point to and name it. It is better to not select a section tittle, but add a simple white space on the on the end of the title line. Then, you are free to use the link insertion to those text tags in your document.