Tous les documents disponibles à l'adresse (http://www.csquad.org), sont écrit à l'aide du language DocBook, cette methode permet de séparer fond du document de sa mise en forme et anisi publier le document dans plusieurs formats (HTML, PDF, Texte, etc...). Cette possiblité forte interessante, est devenus au fils du temps un handicape. Car la moindre modification d'un document nécessite la régénération des differents formats d'export. J'ai donc cherché à simplifié et automatisé la procedure de publication. La résultat de ce travail est décrit dans ce document.

DocBook est un langage de balisage conçu à l'origine pour la documentation technique informatique (matériel et logiciel). Il à été développé par l'éditeur O'Reilly pour les besoins de l'édition technique et plus particulièrement informatique.

La grande force de ce langage est d'être un format XML totalement orienté sémantique, il n'inclut en effet aucune information de mise en forme ce qui permet d'utiliser ensuite la documentation ainsi structurée par tout type de support / lecteur.

Un ensemble de feuilles de styles XSLT est disponible pour transformer des documents vers de nombreux formats tels que le HTML, XHTML, PDF, RTF, Texte, Microsoft WordML, OpenDocument, etc...

Apache Cocoon est une plate-forme de développement d'applications web fondée sur la séparation des domaines techniques et l'assemblage de composants.

Cocoon implémente ces concepts par la notion de "pipelines de composants", chaque composant du pipeline étant dédié à une fonction particulière.

Cela permet d'utiliser une approche du type "Lego" pour la construction d'applications web, en assemblant des chaînes de composants, sans nécessiter de programmation.

L'objectif de mon installation est de mettre en place un système de publication de contenu fonctionnant de la manière suivante :

L'auteur édite un document à l'aide d'un éditeur XML (VIM, Emacs ou bien oXygen^[1]) en respectant le format Docbook.

Une fois le document terminé, il l'envoi vers le serveur de publication de contenu à l'aide de Subversion.

Lorsque'un utilisateur désire obtenir la version imprimable du document au format PDF, le clique sur un lien. A partir de celui-ci Cocoon, réalise la transformation du document XML à l'aide de la feuille de style XSLT et l'envoi à l'utilisateur.

Les logiciels suivants sont nécessaires pour mettre en place le système :

Vous pouvez installer l'ensemble des paquets Debian à l'aide des commandes apt :

# apt-get install sun-java5-jdk apache2  \
tomcat5 libapache2-mod-jk \
libapache2-mod-svn docbook-xsl unzip subversion

Regrouper les fichiers dans un répertoire commun :

$ cd cocoon_files/
$ wget http://apache.fastorama.com/dist/cocoon/cocoon-latest-src.zip
$ unzip cocoon-2.1.9-src.zip
$ ls
cocoon-2.1.10          
cocoon-latest-src.zip  

Il faut compiler Cocoon pour obtenir une application Tomcat. Le système de compilation de Cocoon est modulaire, il faut donc préciser les composants à compiler à l'aide du fichier de configuration local.build.properties.

$ cd cocoon-2.1.10/
$ cp build.properties local.build.properties
$ vim local.build.properties

Pour lancer la compilation de Cocoon, il suffit de taper la commande suivante :

$ sh build.sh war
...
Building jar: /home/cscm/cocoon_files/cocoon-2.1.10/build/cocoon/cocoon.war

BUILD SUCCESSFUL
Total time: 7 minutes 11 seconds

Vous avez largement le temps de vous faire un bon café.

On désactive le Java security manager, qui est activé par default mais qui empeche de déploiement de l'application.

            TOMCAT5_SECURITY=no
        

Ce n'est pas la bonne méthode, mais c'est la plus rapide, car la description de la configuration du Security Manger dépasse le cadre de ce document, une fois votre installation finalisée, je vous invite vivement à lire la documentation disponible à cette addresse :

The Apache Tomcat Security Manager HOWTO

Il suffit de copier le fichier war dans le répertoire des webapps de Tomcat :

# cp build/cocoon/cocoon.war /var/lib/tomcat5/webapps/ 

Pour vérifier le bon fonctionnement, il suffit de se connecter à l'adresse suivante : http://localhost:8080/cocoon

# mkdir /var/local/svn # svnadmin create /var/local/svn/cocoon # chown -R www-data: /var/local/svn/cocoon

Il faut activer le module Subversion pour Apache

# a2enmod dav_svn
Enabling dav as a dependency
This module is already enabled!
Module dav_svn installed; run /etc/init.d/apache2 force-reload to enable.
# /etc/init.d/apache2 force-reload 
        

Il faut ensuite créer un fichier de configuration pour votre site web dans le répertoire des sites disponibles dans apache2 : /etc/apache2/sites-available/svn

<VirtualHost *:80>
  ServerName svn.csquad.org

  ErrorLog /var/log/apache2/svn.csquad.org/error.log
  CustomLog /var/log/apache2/svn.csquad.org/access.log common

  DocumentRoot /var/www

  <Location />
        DAV svn

        SVNParentPath /var/local/svn/
  </Location>

</VirtualHost>

Puis activer, cette configuration :

# a2ensite svn
Site svn installed; run /etc/init.d/apache2 reload to enable.
# /etc/init.d/apache2

Vous pouvez tester le fonctionnement de votre depôt :

$ svn co http://svn.csquad.org/cocoon
Révision 0 extraite.

Je vous propose d'utilisé l'organisation suivante pour votre dêpot :

cocoon
|-- branches
|-- tags
|   `-- public
|       |-- article
|            `-- article.xml
`-- trunk
    |-- article
        `-- article.xml

Les documents qui se trouvent dans le répertoire tags/public, sont accessible publiquement et ceux du répertoire trunk sont les dernières versions et les documents en cours de rédaction. Cette organisation permet de simuler un simple système de pré-publication et de "versionner" l'ensemble de vos documents.

Le module JK permet d'interfacer le serveur Web Apache avec le serveur d'application Tomcat. L'objectif est de rendre Cocoon accessible depuis votre site web à une adresse de type : http://votre_site_web/cocoon

Pour cela, il faut :

Une fois l'ensemble installé, il faut configurer Cocoon de manière à transformer les fichiers qui se trouvent dans le dépôt Subversion en documents accessibles via le site Web dans différents formats. Pour cela nous allons modifier la section map:pipelines du fichier de configuration sitemap.xmap qui se trouve dans le répertoire : /var/lib/tomcat5/webapps/cocoon

<map:pipeline>

...

<!--+
    | Subversion Content
    +-->

<!-- Images -->
<map:match pattern="**.png">
        <map:read mime-type="image/png" src="http://svn.csquad.org/cocoon/{0}"/>
</map:match>

<map:match pattern="**.jpg">
        <map:read mime-type="image/jpeg" src="http://svn.csquad.org/cocoon/{0}"/>
</map:match>

<!-- Acces direct au document au format XML -->
 <map:match pattern="**.xml">
 	<map:generate src="http://svn.csquad.org/cocoon/{0}"/>
     	<map:serialize type="xml"/>
 </map:match>

<!-- Transformation des documents XML en HTML a l'aide des feuilles de style de Norman Waslh-->
<map:match pattern="**.html">
        <map:generate src="http://svn.csquad.org/cocoon/{1}.xml"/>
        <map:transform 
            src="/usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl"/>
        <map:serialize type="html"/>
</map:match>

<!-- Transformation des documents XML en xHTML a l'aide des feuilles de style de Norman Waslh-->
<map:match pattern="**.xhtml">
        <map:generate src="http://svn.csquad.org/cocoon/{1}.xml"/>
        <map:transform 
            src="/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl"/>
        <map:serialize type="xhtml"/>
</map:match>

<!-- Transformation des documents XML en PS a l'aide des feuilles de style de Norman Waslh et de FOP -->
<map:match pattern="**.ps">
        <map:generate src="http://svn.csquad.org/cocoon/{1}.xml"/>
        <map:transform
            src="/usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl"/>
        <map:serialize type="fo2ps"/>
</map:match>

<!-- Transformation des documents XML en PDF a l'aide des feuilles de style de Norman Waslh et de FOP -->
<map:match pattern="**.pdf">
        <map:generate src="http://svn.csquad.org/cocoon/{1}.xml"/>
        <map:transform 
            src="/usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl"/>
        <map:serialize type="fo2pdf"/>
</map:match>

<!-- Transformation des documents XML en RTF a l'aide des feuilles de style de Norman Waslh et de FOP -->
<map:match pattern="**.rtf">
        <map:generate src="http://svn.csquad.org/cocoon/{1}.xml"/>
        <map:transform
            src="/usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl"/>
        <map:serialize type="fo2rtf"/>
</map:match>

...

<map:pipelines>

Cette configuration permet de transformer le contenu de votre dêpot dynamiquement, et se base sur l'extension du fichier pour déterminer l'action à réaliser :

Par exemple pour le document que vous êtes en train de lire, il n'existe qu'une seule version au format XML :

http://www.csquad.org/cocoon/tags/public/cocoon/cocoon.xml

le document originale se trouve dans le dépôt Subversion :

http://svn.csquad.org/cocoon/tags/public/cocoon/cocoon.xml

Cette version est transformée dynamiquement dans plusieurs formats :

OpenDocument est un format ouvert de données pour les applications bureautiques : traitements de texte, tableurs, présentations, diagrammes, dessins et base de données bureautique. OpenDocument est la désignation d'usage d'un standard dont l'appellation officielle est OASIS Open Document Format for Office Applications, également abrégée par le sigle ODF.

Un projet de feuille de style est en cours de réalisation (docbook2odf), celui-ci permet de transformet un fichier docbook au format OpenDocument.

Puis l'installer, à l'aide des commandes suivantes :

# cd /usr/src
# svn co http://svn.comsultia.com/docbook2odf/trunk docbook2odf
# cd  docbook2odf
# make install

Depuis la version 2007 d'Office, Microsoft essaye d'introduire un nouveau format de fichier pour sa suite bureautique. Ce format à l'avantage d'être basé sur XML et d'être probablement documenté.

Pour lire ce format avec les anciennes version de Micrsoft Office (XP, 2003, etc...), il faut installer le Microsoft Office Compatibility Pack.

Il est possible de produire des documents au format WordML à l'aide des feuilles de style Docbook, pour cela il faut modifier la configuration de Cocoon et ajoutés les lignes suivantes dans votre fichier de configuration sitemap.xmap :

<!-- Définition du serialiser -->
<map:serializers>
...
	<map:serializer name="docx" 
		mime-type="application/vnd.openxmlformats-officedocument.wordprocessingml.document" 
		src="org.apache.cocoon.components.serializers.XMLSerializer"/>
...
</map:serializers>

<!-- Transformation des documents XML en WordML a l'aide des feuilles de style de Norman Waslh -->
<map:match pattern="**.docx">
        <map:generate src="http://svn.csquad.org/cocoon/{1}.xml"/>
        <map:transform src="/usr/share/xml/docbook/stylesheet/nwalsh/wordml/docbook.xsl">
                <map:parameter name="wordml.template" value="/usr/share/xml/docbook/stylesheet/nwalsh/wordml/template.xml"/>
        </map:transform>
        <map:serialize type="docx"/>
</map:match>

Pour un document simple, cela fonctionne parfaitement, en revenche pour un document un peu plus complexe (tableaux, images, etc ...), le résultat final n'est pas garantie.

Les feuilles de style XSLT de Norman Waslh, disposent de nombreuses options permettant de contrôler la mise en forme des documents : http://www.sagehill.net/docbookxsl/OptionsPart.html. Pour utiliser ces options, il est possible de procéder de plusieurs manières :

<map:transform src="...xsl">
    <map:parameter name='nom1' value='valuer1'/>
    <map:parameter name='nom2' value='valuer2'/>
    <map:parameter name='nom3' value='valuer3'/>
    ...
</map:transform>

Au niveau de la sécurité du système, il faut protéger principalement l'accès au dépôt subversion.

Pour cela, il suffit de protéger l'accès par mot de passe et de le limiter à votre réseau en modifiant le fichier de configuration du site Web :

  AuthType Basic
  AuthName "Subversion Repository"
  AuthUserFile /etc/apache2/svn.htpasswd

  # Authorise l'accès seulement au réseau local (pour la publication) 
  # et à la machine locale (pour les transformations avec cocoon)

  Order deny,allow
  Deny from all
  Allow from 127.0.0.1
  Allow from 192.168.0.0/24

  # Demande l'authentification que pour les opérations d'écriture
  <LimitExcept GET PROPFIND OPTIONS REPORT>
    Require valid-user
  </LimitExcept>

Puis créer le fichier de mot de passe pour vos utilisateurs :

# htpasswd -c /etc/apache2/svn.htpasswd user
New password:
Re-type new password:
Adding password for user user

Pour configurer la gestion de la mémoire, il faut éditer la variable CATALINA_OPTS du fichier /etc/default/tomcat5.

Il faut choisir la bonne configuration en fonction de la quantité de mémoire disponible sur votre serveur. Pour vous aider, je vous invite à vous consulter le document suivant : Java Tuning White Paper

Il y'a plusieurs options interessantes dans le fichier cocoon.xconf qui se trouve dans le répertoire /var/lib/tomcat5/webapps/cocoon/WEB-INF

La récupèration du fichier source XML à partir du dépôt est une opération récurrente, qu'il est possible d'optimiser à l'aide de la gestion du cache.

Pour cela, il faut modifié la déclaration de la source est ajouté le préfix cached, comme ceux-ci :

	<map:generate src="cached:http://svn.csquad.org/cocoon/{1}.xml"/>

Voici la sortie de logiciel Apache Benchmark :

$ab -n 100 -c 5 http://www.csquad.org/cocoon/trunk/cocoon/cocoon.html
This is ApacheBench, Version 2.0.40-dev <$Revision: 1.146 $> apache-2.0
Copyright 1996 Adam Twiss, Zeus Technology Ltd, http://www.zeustech.net/
Copyright 2006 The Apache Software Foundation, http://www.apache.org/

Benchmarking www.csquad.org (be patient).....done


Server Software:        Apache/2.2.3
Server Hostname:        www.csquad.org
Server Port:            80

Document Path:          /cocoon/trunk/cocoon/cocoon.html
Document Length:        47673 bytes

Concurrency Level:      5
Time taken for tests:   5.586575 seconds
Complete requests:      100
Failed requests:        0
Write errors:           0
Total transferred:      4806200 bytes
HTML transferred:       4767300 bytes
Requests per second:    17.90 [#/sec] (mean)
Time per request:       279.329 [ms] (mean)
Time per request:       55.866 [ms] (mean, across all concurrent requests)
Transfer rate:          840.05 [Kbytes/sec] received

Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        0    0   0.2      0       1
Processing:    69  187 533.3    111    5426
Waiting:       45  155 534.6     79    5412
Total:         69  187 533.3    111    5426

Percentage of the requests served within a certain time (ms)
  50%    111
  66%    126
  75%    145
  80%    154
  90%    216
  95%    341
  98%    426
  99%   5426
 100%   5426 (longest request)

Comme on peux le voir, la 1ère requête, qui n'est pas mise en cache, est assez longue (5500 ms) et les autres requêtes sont bien plus rapides.

Le système de gestion d'événements ("Hooks") de Subversion permet d'exécuter des actions sur le serveur lorsqu'une opération est réalisée sur le dépôt. Via ce système, il est possible de valider le contenu des fichiers XML par rapport à la DTD Docbook et de refuser automatiquement les fichiers qui ne sont pas formatés correctement.

Docbook permet de décrire, l'historique des révisions d'un document à l'aide du tag revhistory. Ces informations sont directement disponibles dans le dêpot Subversion, il serait intérressant de les exploiter automatiquement.