Installation et utilisation d'OOo2sDbk

2002-12-29

Version 0.3 pour Ooo2sDbk-0.4.2

Eric Bellot

Email : <ebellot@laposte.net>

Copyright © 2002 Éric Bellot

Licence

Permission vous est donnée de copier, distribuer et/ou modifier ce document selon les termes de la Licence GNU Free Documentation License, Version 1.1 ou ultérieure publiée par la Free Software Foundation ;

Avec les sections inaltérables suivantes : - La section « Licence »

Avec le texte de première page de couverture suivant: - pas de texte de première page de couverture -

Avec le texte de dernière page de couverture suivant : - pas de texte de dernière page de couverture -

La licence officielle peut être consultée sur le Web à l'adresse suivante :

http://www.gnu.org/licenses/fdl.html

Table des matières

1. Présentation
1.1. Principe de fonctionnement d'OOo2sDbk
1.2. Le modèle et le fichier autotexte
2. Installation des scripts et des feuilles de styles
2.1. Programmes requis
2.2. Étapes d'installation pour Linux
2.3. Installation pour Windows
3. Utilisation d'OOo2sDbk
4. Utilisation pour les scripts en Python
4.1. Étapes
4.2. Syntaxe
4.3. Exemples de scripts
5. Fichier de configuration
5.1. xslt-command
5.2. xslt-stylesheet
5.3. images
6. Installation du modèle et du fichier d'autotexte

1. Présentation

OOo2sDbk est un ensemble de feuilles de styles XSLT qui permettent de convertir un document OpenOffice au format Docbook. Elles sont pilotées par une série de scripts Python qui automatisent le processus.

Pour pouvoir fonctionner Ooo2sDbk requiert Python et un processeur XSLT (Saxon, Xalan, xsltproc, etc.).

Les utilisateurs du filtre FlatXML peuvent se dispenser du recourt aux scripts Python. Le filtre FlatXML permet de produire directement un document OpenOffice au format XML. Il suffit donc d'un processeur XSLT et de la feuille ooo2sdbk.xsl pour réaliser la conversion.

1.1. Principe de fonctionnement d'OOo2sDbk

OOo2sDBK converti un document SXW en Docbook en 3 étapes :

  1. Décompression des fichiers XML du document OpenOffice-Writer[1] et, s'il y a lieu, extrraction des images in­corporées.

  2. Concaténation de ces différents fichiers en un gros document XML temporaire[2],

  3. Conversion du document temporaire au format Docbook simplifié par le processeur XSLT et la feuille de styles ooo2sdbk.xsl.

1.2. Le modèle et le fichier autotexte

Le modèle ooo2sdbk.stw facilite la rédaction de documents Docbook avec OpenOffice.

Il ajoute à OpenOffice toutes une série de styles de caractères et de paragraphes adaptés à la création de balises Docbook. Plus d'une cinquantaine de styles "spécial Docbook" a été ajoutés. On trouvera par exemple un style de paragraphe Abstract. Le paragraphe sur lequel on applique ce style sera encadré de balises <abstract> dans le document Docbook généré par Ooo2sDbk.

On trouvera une présentation détaillées des styles et de leur utilisation dans le guide Rédaction d'un document Docbook avec OpenOffice.

Le fichier d'autotexte ooo2sdbk.bau propose des exemples de pages de titre pour OpenOffice. Elles contribuent à générer des sections <infoarticle> correctes dans les documents Docbook.

[Note] Note

Ooo2sDbk peut parfaitement fonctionner sans le modèle, ni l'autotexte. Il est capable de convertir des documents OpenOffice standards. Toutefois, le modèle permet de réaliser des documents nettement meilleurs.

2. Installation des scripts et des feuilles de styles

2.1. Programmes requis

Pour qu'OOo2sDbk fonctionne, Python et un processeur XSLT doivent être fonctionnels. Ce document n'explique pas l'installation de ces différents logiciels. Reportez-vous à la documentation des fabricants.

Les processeurs XSLT suivants fonctionnent correctement avec Ooo2sDbk :

Saxon (recommandé sous Windows)

Il supporte très bien tous les standards (mieux que Xsltproc) mais est assez lent car il fonctionne sous Java.

Xsltproc (recommandé sous Linux)

Il est très rapide mais semble moins fiable que Saxon, en particulier sous Windows. Les dernières versions semblent toutefois excellentes même sur Windows.

Logiciels

Versions testées

Python 2.1 ou +

http://www.python.org

  • Python 2.1 et 2.2 sur Windows 95c, 98 et 2000,

  • Python 2.2 sur Linux-Mandrake 8.2 et 9.0.

Saxon 6.5.2

http://saxon.sourceforge.net

Saxon requiert une plateforme JAVA2 pour fonctionner

http://java.sun.com/j2se/1.3/download.html

Saxon 6.5.2

Plateformes JAVA testées :

  • J2RE 1.3.1_02, 1.4 et 1.4.1 de Sun sur Windows 95c et 2000,

  • J2RE 1.4 et Kaffe sur Linux-Mandrake 8.2.

    J2RE 1.4.1 sur Linux-Mandrake 9.0

Xsltproc (fourni avec LibXSL)

Requiert :

  • LibXML2

  • LibXSL

http://xmlsoft.org/downloads.html

Sous Linux et Windows

  • LibXML2 2.4.22 => 2.4.28

  • LibXSL 1.0.18 => 1.0.23

LibXML et LibXSL s'améliorent constamment. Choisissez toujours la version la plus récente.

2.2. Étapes d'installation pour Linux

  1. Téléchargez la dernière version d'OOo2sDBK.

  2. Décompressez ooo2sbk-all-xxx.zip. Vous trouverez une série de répertoires.

  3. Copiez le répertoire ooo2sbk dans <python-dir>/site-packages ou n'importe quel emplacement référencé dans la variable d'environnement PYTHONPATH.

  4. Copiez le fichier ooo2sbk/sitecustomize.py dans /usr/lib/Python2.2.

    Il permet à Python de travailler en UTF-8 au lieu de l'ASCII. L'encodage UTF-8 est requit pour le XML.

  5. Copiez le fichier shell-linux/ooo2sdbk dans /usr/bin ou n'importe quel emplacement référencé dans la variable d'environnement PATH.

  6. Le script est opérationnel

2.3. Installation pour Windows

  1. Téléchargez la dernière version d'OOo2sDBK.

  2. Décompressez ooo2sbk-all-xxx.zip. Vous trouverez une série de répertoires.

  3. Copiez le répertoire ooo2sbk dans <python-dir>/Lib/site-packages ou n'importe quel emplacement référencé dans la variable d'environnement PYTHONPATH.

  4. Copiez le fichier shell-windows/ooo2sdbk.bat dans emplacement référencé dans la variable d'environnement PATH.

  5. Editez ooo2sdbk.bat et vérifiez que la variable OOO2SDBK contienne bien le chemin d'accès au script ooo2sdbk.py. Par défaut, il pointe vers :

    C:\Python22\Lib\site-packages\ooo2sdbk\ooo2sdbk.py.

  6. Le script est opérationnel

3. Utilisation d'OOo2sDbk

Elle est identique sous Linux et Windows.

Syntaxe :

ooo2sdbk [ OPTIONS ] openoffice-writer-filename

<openoffice-writer-filename>

Chemin d'accès relatif ou absolu vers un fichier *.sxw (Writer d'OpenOffice)

Ce paramètre est obligatoire.

-d, --dbkfile <docbook-filename>

Nom du fichier Docbook en sortie. Si ce paramètre et omis, le fichier Docbook reçoit le même nom que le document OpenOffice ; l'extension *.sxw est remplacée par l'extension *.xml.

Par exemple, mydoc.sxw => mydoc.xml.

-c , --cmdxsl <command-name>

Nom de la conversion XSL utilisée. Les commandes disponibles sont répertoriées dans ooo2sdbk/config.xml. Deux sont prédéfinies : xsltproc et saxon. Il est possible d'en ajouter (voir section 5 Fichier de configuration).

Si ce paramètre est omis, XSLTproc est utilisé par défaut.

-f, --flatxml

Permet de conserver le fichier OpenOffice au format XML. Ce fichier est la concaténation de tous les fichiers XML du document OpenOffice. Il sert de base à la conversion. Surtout utile pour le développement.

Il a le même nom que le fichier OpenOffice suivi de "_oo.xml".

Exemple : mydoc.sxw => mydoc_oo.xml.

-h, -?, --help

Affiche l'aide

Exemples de commandes :

  1. ooo2sdbk mydoc.sxw

  2. ooo2sdbk -d mydoc-dbk.xml mydoc.sxw

  3. ooo2sdbk -c saxon mydoc.sxw

  4. ooo2sdbk -d mydoc.dbk -c saxon -f mydoc.sxw

4. Utilisation pour les scripts en Python

OOo2sDBK exporte une méthode convert qui permet de réaliser la conversion d'un document OpenOffice-Writer grâce à un script Python.

4.1. Étapes

  1. Avec un éditeur de texte, rédigez le script qui appellera la méthode convert du module ooo2sbk (voir 4.2 Syntaxe pour plus de détails). Par exemple, pour convertir le document myDoc.sxw en un document Docbook appelé myDocbook.xml avec le processeur Saxon, on rédigera le script suivant :

import ooo2sdbk
ooo2sdbk.convert("myDoc.sxw",docbook="myDocbook.xml", \
command="saxon")

  1. Enregistrez le script avec l'extension *.py (par exemple : conversion.py) dans le même répertoire que le document OpenOffice

  2. Ouvrez un shell sous Linux ou une session DOS sous Windows :

    1. Placez-vous dans le dossier ou se trouve votre script avec la commande cd

    2. Saisissez la commande : python conversion.py

  3. Après quelques instants, la conversion est faite (la durée dépend de la taille du document OpenOffice, de la rapidité du processeur XSLT et, bien sûr, de celle de la CPU).

4.2. Syntaxe

convert(openoffice-filename, command=commandName, \
[docbook=docbook-filename], [imagesrew=0|1] [deltemp=0|1])
OpenOffice-filename

Option obligatoire

Chemin d'accès (relatif ou absolu) au fichier OpenOffice-Writer à convertir

command= commandName

Option obligatoire.

commandName est le nom de la commande utilisée pour la conversion.

La liste des commandes disponibles se trouve le fichier de configuration config.xml. Le fichier contient 2 commandes préconfigurées : xsltproc et saxon (Voir section 5 Fichier de configuration).

docbook= Docbook-filename

Option facultative.

Chemin d'accès (relatif ou absolu) au fichier Docbook produit.

Si ce paramètre est omit, le fichier Docbook aura le même nom que le fichier OpenOffice et l'extension *.xml à la place de *.sxw. Il sera enregistré dans le même répertoire.

Par exemple : myDoc.sxw => myDoc.xml

imagesrew= 0|1

Images Rewriting.

Option facultative (1 par défaut).

Ne concerne que les images incorporées au document OpenOffice.

Si la valeur est 1, les images incorporées au document OpenOffice écrasent les images ayant le même nom dans le répertoire de destination.

Si la valeur est 0, les images déjà présentes dans le répertoire de destination ne sont pas réécrites.

deltemp= 0|1

Delete temporary file.

Cette option est facultative.

Si deltemp est 0, le fichier temporaire global.xml est préservé. Par défaut, il est détruit à la fin de la conversion (deltemp=1).

Le fichier global.xml est la concaténation de tous les fichiers XML du document OpenOffice. Il sert de base à la conversion. Surtout utile pour le développement. Par défaut, deltemp=1.

4.3. Exemples de scripts

4.3.1. Exemple 1 (Windows)

Les fichiers sont ici indiqués avec de chemins absolus, on utilise le processeur Saxon.

import ooo2sbk
ooo2sbk.convert("C:\monDocumentOOo.sxw", \
docbook="C:\monDocbook.xml", command="saxon")

4.3.2. Exemple 2 (Windows ou Linux)

Les chemins d'accès aux fichiers sont relatifs, cela suppose, ici, que le script se trouve dans le même répertoire que les fichiers. Le fichier Docbook produit sera : monDocumentOOo.xml 

import ooo2sbk
ooo2sbk.convert("monDocumentOOo.sxw", command="saxon")

4.3.3. Exemple 3 (Linux)

Chemins d'accès absolus et utilisation de xsltproc.

import ooo2sbk
ooo2sbk.convert("/home/Documents/doc.sxw",\
docbook="/home/Documents/monDocbook.xml", command="xsltproc")

5. Fichier de configuration

Le fichier de configuration config.xml se trouve à la racine du répertoire ooo2sdbk. Il permet notamment de configurer les modèles de commandes des processeurs XSLT disponibles 

<config>
     <xslt-command
         name="xsltproc"
         command="xsltproc -o %o %s %i"/>
     <xslt-command
         name="saxon"
         command="java com.icl.saxon.StyleSheet -o %o %i %s"/>
     <xslt-stylesheet
         stylesheetPath="docbook.xsl"/>
     <images
         imageNameRoot="img"
         imagesRelativeDirectory="images"/>
</config>

5.1. xslt-command

Permet de définir un modèle de commande pour le processeur XSLT

name

Nom du modèle de commande. Il sera appelé dans le script Python.

command

Commande de conversion du processeur XSL. Trois variables sont disponibles :

%o

output, le nom du fichier XML produit

%i

input, le nom du fichier XML entrant

%s

stylesheet, le nom de la feuille de style XSL

Voici quelques exemple de commandes utilisables. Elles sont à adapter à votre système :

java com.icl.saxon.StyleSheet %i %s > %o
java -jar /usr/java/classes/saxon/saxon.jar -o %o %i %s (Linux)
java -cp C:\saxon\saxon.jar com.icl.saxon.StyleSheet %i %s > %o (Windows)

5.2. xslt-stylesheet

Permet de définir le chemin d'accès vers la feuille de style ooo2sdbk.xsl

stylesheetPath

Chemin relatif vers la feuille de style XSL à partir du fichier ooo2sdbk.py.

5.3. images

Permet de configurer l'extraction des images incorporées au document OpenOffice.

ImageNameRoot

Radical du nom attribué aux images extraites du document OpenOffice.

Le radical "img" produira des images ayant pour nom : img001.png, img002.jpg, etc.

Le radical "pix" produira des images ayant pour nom : pix001.png, pix003.jpg, etc.

Les images sont numérotées selon leur ordre d'apparition dans le document.

imagesRelativeDirectory

Nom du répertoire qui accueille les images extraites du document OpenOffice. Ce répertoire est généré automatiquement dans le même répertoire que le document Docbook.

6. Installation du modèle et du fichier d'autotexte

  1. Fermez OpenOffice et, s'il y lieu, le démarrage rapide.

  2. Décompressez ooo2sbk-all-xxx.zip. Vous trouverez une série de répertoires.

  3. Dans le répertoire template vous trouverez deux fichiers :

    • ooo2sdbk.stw. C'est le modèle de document

    • ooo2sdbk.bau. C'est le fichier d'autotexte

  4. Placez le fichier ooo2sdbk.stw dans votre répertoire des modèles.

    • Sous Linux : ~/.OpenOffice.org1.0.1/user/template

    • Sous Windows :

      C:\Documents and settings\[user]\OpenOffice.org1.0.1\user\template

      ou C:\Program files\OpenOffice.org1.0.1\user\template

  5. Placez le fichier ooo2sdbk.bau dans votre répertoire autotexte.

    • Sous Linux : ~/.OpenOffice.org1.0.1/user/autotext

    • Sous Windows :

      C:\Documents and settings\[user]\OpenOffice.org1.0.1\user\autotext

      ou C:\Program files\OpenOffice.org1.0.1\user\autotext

  6. Dorénavant, vous pourrez créer de nouveaux documents orientés Docbook en faisant Fichier > Nouveau > Modèles et documents > Default et en choisissant ooo2sdbk.

  7. Vous pourrez créer rapidement des pages de titre en faisant Edition > Autotexte et en choisissant un des textes de la rubrique ooo2sdbk.


[1] Un document OpenOffice est une collection de documents XML compressés au format Zip.

[2] Ce document XML est compatible avec la DTD officielle d'OpenOffice.


Copyright©2002 Eric Bellot
http://www.chez.com/ebellot
Miroir : http://membres.lycos.fr/ebellot