2002-12-03
Version 0.1 (draft) pour Ooo2sDbk-0.4
Copyright © 2002 Éric Bellot
Résumé
Ce document présente les modalités de conversion d'un document OpenOffice-Writer au format Docbook avec Ooo2sDbk. On y trouvera notamment la table de correspondance complète entre les styles et objets d'OpenOffice et le résultat de leur conversion.
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 :
Table des matières
OOo2sDbk se base sur les styles du document OpenOffice-Writer pour construire le document Docbook.
La plupart du temps, un style d'OpenOffice correspond à une balise de la Docbook. Par exemple, un texte sur lequel aura été appliqué le style Accentuation sera encadré par les balises <emphasis>texte</emphasis> dans le document Docbook.
Nous proposons en téléchargement un modèle de document OpenOffice destiné à la création de documents Docbook. On y trouvera un grand nombre de styles spécialement créés pour correspondre aux balises de la simplified Docbook.
Pour simplifier la correspondance entre les styles d'OpenOffice et les balises Docbook, nous avons systématiquement nommés les styles d'OpenOffice avec les mêmes noms que leur équivalent Docbook. Par exemple, le style de paragraphe Copyright sera rendu par la balise <copyright>.
De même, ce document suppose que les balises courantes de la simplified Docbook soient connues. N'hésitez pas à consulter The simplified Docbook definitive guide pour connaître la signification des balises et des styles OpenOffice correspondants.
Un document docbook est un document structuré. Les mises en formes sont donc perdues lors de la conversion car elles n'ont aucune signification pour un document Docbook :
Les formats de caractères sont perdus (souligné, police, taille de caractères, etc.)
Les formats de paragraphes sont perdus (alinéa, interligne, tabulations, etc.).
Cette perte n'est pas un inconvénient, en fait c'est même un avantage. Il possible de personnaliser les styles du document OpenOffice à votre convenance sans que cela interfère sur le document Docbook produit.
OpenOffice ne permet pas une imbrication des balises aussi subtile que celle d'un document Docbook "fait main". Il est, par exemple, impossible d'imbriquer deux styles de caractères dans OpenOffice.
Le fragment de code ci-dessous est en style Literal avec le nom de la commande "java" en style Command et les paramètres "-fo" et "-pdf" en style Option :
java org.apache.fop.apps.Fop -fo manuel.fo -pdf manuel.pdf
On obtiendra le code suivant :
<command>java</command><literal> org.apache.fop.apps.Fop </literal> <option>-fo</option><literal> manuel.fo </literal> <option>-pdf</option><literal> manuel.pdf</literal> |
et pas (ce qu'on aurait souhaité) :
<literal><command>java</command> org.apache.fop.apps.Fop <option>-fo</option>manuel.fo <option>-pdf</option> manuel.pdf</literal> |
Les styles sont juxtaposés au lieux d'être imbriqués. Ce problème ne vient pas d'OOo2sDbk, mais du code XML d'OpenOffice qui n'imbrique pas les styles.
Ooo2sDbk est encore loin d'être finalisé. Un certain nombre de styles de la simplified Docbook ne sont pas encore supportés :
Les images flottantes ancrées à la page sont perdues. En général, elle permettent de décorer les documents et n'ont donc pas à être transmisent au document Docbook.
Les exemples (<example>).
Les objets audio et video (<audioobject> et <videoobject>).
L'historique des révisions (<revhistory>)[1]
Les métadonnées de section (<sectioninfo>)
Les informations sur les objets (<objectinfo>). OpenOffice ne propose rien qui puisse servir de support à cette balise et aux informations qu'elle contient.
Les sidebar (<sidebar>), c'est à dire les notes de marges.
La DTD simplified Docbook est une version allégée de la DTD Docbook standard. Elle ne contient qu'une centaine de balises au lieu des 600 de la version complète. On ne doit donc pas espérer atteindre toute la subtilité qu'offre la Docbook standard.
La simplified Docbook est destinée aux document courts (les "articles" au sens de la Docbook).
La DTD simplified Docbook n'est pas encore finalisée, seule la Candidate Release 3.0 de la version 1.0 est disponible au moment de l'écriture de ces lignes.
C'est pour cette raison que, par défaut, qu'Ooo2sDbk attribue aux documents générés la déclaration de type de document de la Docbook 4.1.2.
Les sections et titres des sections du Docbook sont construits à partir des niveaux de chapitres du document OpenOffice (menu Outils > Numérotation des chapitres).
S'il comporte des chapitres, le 1er chapitre doit être un chapitre de niveau 1.
Les chapîtres doivent être correctement imbriqués : pas de chapitre 3 sous un chapitre 1 sans chapitre 2 intermédiaire.
Le document peut ne pas comporter de chapitre, dans ce cas, aucune section n'est générée.
Par défaut, OpenOffice associe les styles Titres 1, Titre 2... aux numérotations de chapitre. Il est possible de changer les styles associés aux chapitres sans que cela pose de problème de conversion. Par contre, un style Titre 1 qui ne serait pas associé à un niveau de chapitre ne permettrait pas de générer une section.
Les métadonnées sont certainement la partie d'un document la plus délicate à construire. Elle suppose une imbrication subtile de styles pour que le convertisseur puisse produire une section infoarticle correcte.
Afin de faciliter la saisie des métadonnées, vous trouverez deux modèles dans l'Autotexte un modèle de métadonnées complet un autre plus court.
Le convertisseur respecte l'ordre dans lequel les éléments sont insérés. Tous les éléments décrits dans cette rubrique seront placés entre les balises <infoarticle> du document Docbook.
Les styles décrits dans cette section ne doivent être utilisés que pour les métadonnées.
Les styles de paragraphe Titre principal et Sous-titre sont convertis en <title> et <subtitle>
Utiliser le style de paragraphe Pubdate.
Il est recommandé de présenter la date sous la forme aaaa-mm-jj (année-mois-jour).
Les styles de paragraphes Author, Editor et Othercredit seront convertis respectivement en <author>, <editor> et <othercredit>.
Note | |
---|---|
Par défaut, les XSL-stylesheets pour Docbook de Norman Walsh ne convertissent pas la balise <editor> dans les articles. Présente dans le document Docbook, elle disparaît dans les documents HTML, XHTML et FO. |
Chacun d'eux peux contenir les styles de caractères suivants :
Honorific (titre, civilité) => <honorific>
Firstname (prénom) => <firstname>
Surname (nom de famille) => <surname>
Lineage. Reservé aux noms anglo-saxons : Jr (Junior), Sr (Senior) => <lineage>
Othername. Autre nom en cas de besoin (pour les français cela peut-être un surnom). => <othername>
Jobtitle (fonction, emploi) => <jobtitle>
Orgname (organisme, entreprise, institution) => <orgname>.
Bien qu'insérés directement dans un paragraphe comme Author, les textes stylés en Jobtitle et Orgname seront correctement encadrés par les balises <affiliation>...</affiliation>.
Note | |
---|---|
Contrairement au habitudes de la Docbook standard, dans la simplified Docbook, il est interdit d'insérer l'email dans la balise <author>. Voir la section Email pour plus de détails |
Par souci de clarté, on peut insérer des retours de ligne dans un paragraphe Author, Editor ou Othercredit.
On peut faire suivre un paragraphe de style Author, Editor ou Othercredit d'un paragraphe Authorblurb. Il est destiné à contenir une courte présentation de l'auteur.
Note | |
---|---|
Pour être corectement traité par OOo2sDbk, le paragraphe Authorblurb doit suivre immédiatement l'auteur auquel il réfère. |
Le style de caractère Email est converti en <email>.
L'insertion de l'email du ou des auteur d'un document est très problématique dans la simplified Docbook. Dans la Docbook standard, l'email peut être placé entre les balises author ou adress. Impossible avec la simplified Docbook qui ne le permet pas dans author ; quant à la balise adress, elle fait partie des balises éliminées de la simplified Docbook.
Il faut donc se résoudre à le placer dans Authorblurb s'il y a plusieurs auteurs, voire Bibliomisc s'il n'y en a qu'un. Aucune de ces solutions n'est très satisfaisante car authorblurb et bibliomisc ne sont pas très bien suportés par les convertisseurs de document Docbook.
Un paragraphe Bibliomisc est converti en <bibliomisc>.
Note | |
---|---|
Par défaut, les XSL-stylesheets pour Docbook de Norman Walsh ne convertissent pas la balise <bibliomisc>. Présente dans le document Docbook, elle disparaît dans les document HTML, XHTML et FO. |
Ils doivent être saisis dans les propriétés du document par le menu Fichier > Propriétés > onglet Description.
Les mots-clefs doivent être séparés par des virgules pour être correctement traités :
keyword1, keyword2, keyword3
Les sujets doivent appartenir à un vocabulaire référencé. Ils seront saisis de la façon suivante :
subject-sheme:subject-terme1,subject-terme2,subject-terme3
Il se rédige en style Abstract.
Le résumé ne doit comporter qu'un paragraphe (les paragraphes suivants seront convertis en texte standard). Toutefois, il est possible d'insérer des retours de lignes. Les phrases séparées par des retours de ligne formeront des paragraphes dans le document Docbook.
On peut donné un titre au résumé. Le titre doit précéder immédiatement le paragraphe de résumé et être de style Titre.
Il se rédige en style Copyright et sera converti en <copyright>.
Un paragraphe Copyright doit contenir une ou plusieurs années en style de caractères Year suivi d'un ou plusieurs détenteurs des droits en style Holder (détenteur des droits). Seuls le contenu des éléments stylés en Year et en Holder sont transmis au document Docbook.
Par exemple, le paragraphe de copyright rédigé de la façon suivante :
Copyright©2002 Eric Bellot.
Dans ce paragraphe, « 2002 » est en style Year et « Eric Bellot » en style Holder. Une fois converti, il deviendra :
<copyright><year>2002</year><holder>Eric bellot</holder></copyright>
On remarque que la partie « Copyright© » a disparue. C'est normal, elle sera reconstruite lors de la conversion ultérieure du document Docbook. Il ne faut pas inclure « Copyright© » dans Year.
Les éléments de paragraphe séparés par des retours de lignes formeront des paragraphes à part entière dans le document Docbook.
C'est particulièrement intéressant pour les citations (style Blockquote) et les listes.
Cette fonctionnalité ne s'applique pas aux paragraphes de styles Programlisting, Texte préformatté et Literallayout où les retours de ligne sont transmis tels quels au document Docbook.
Ils sont convertis en <programlisting>Les retours de ligne, espaces et tabulations sont préservés (les tabulations sont converties en 4 espaces).
Les lignes de codes peuvent être commentées grâce au style de caractère Lineannotation.
Le paragraphe de style Literallayout est converti en <literallayout>.
Les retours de ligne, espaces et tabulations sont préservés (les tabulations sont converties en 4 espaces).
Les paragraphes en style Citation ou Blockquote sont convertis en <blockquote>.
Un paragraphe en style Epigraph est converti en <epigraph>.
Une Citation, un Blockquote ou une Epigraph ne peut comporter qu'un seul paragraphe. Toutefois, les éléments du paragraphe séparés par des retours de lignes formeront des paragraphes à part entière dans le document Docbook.
Un paragraphe Citation, Blockquote ou Epigraph peut être suivi d'un paragraphe Attribution (référence du document). Le paragraphe Attribution doit suivre immédiatement le paragraphe.
Les paragraphe en style Note sont convertis en <note>.
Une note peut recevoir un titre ("Remarque", "Important", "Attention"). Il s'agit d'un paragraphe en style Titre qui doit précéder immédiatement le paragraphe de note.
Une note ne peut comporter qu'un seul paragraphe. Toutefois, les éléments du paragraphe séparés par des retours de lignes formeront des paragraphes à part entière dans le document Docbook.
Elles sont supportées avec les limites suivantes :
La Docbook ne distingue pas les notes de bas de page et les notes de fin de document. Les deux types de notes sont donc convertis en <footnote> sans distinction.
Les appels de notes par caractères spéciaux sont supportés par OOo2sDBK mais ne sont pas rendues lors des conversions avec les Docbook XSL stylesheets. Ces appels de notes sont inclus dans la numérotation automatique.
Il est possible de faire plusieurs appels pour une même note. La premier appel est réalisé au moment de la création de la note. Les autres doivent être insérés dans la document en faisant le menu Insertion > Renvois > onglet Référence > item Note de bas de page puis en choisissant la note voulue dans la rubrique Sélection. Les notes ainsi construites sont converties en <xref>.
Les tableaux OpenOffice sont intégralement supportés (tailles de cellules, fusions horizontales, fusions verticales, etc.) à l'exception des styles de bordures qui sont perdus.
Par exemple, les bordures de cellules transparentes dans OpenOffice seront visibles dans le document Docbook.
Note | |
---|---|
Les tailles de cellules sont supportées. Toutefois, le Docbook produit ne sera correctement converti par Saxon et Xalan qu'en utilisant les extensions fournies par Norman Walsh avec ses Docbook XSL stylesheets. Xsltproc les supporte nativement. |
Les tableaux légendés seront convertis en <table> et les tableaux sans légende en <informaltable>. Le contenu d'une légende sera encadré par une balise <title>.
Une cellule de tableau peut contenir n'importe quel type de paragraphe, de liste, d'image, etc. Les titres de sections ne doivent jamais apparaître dans un tableau.
Elles sont complètement supportées à l'exceptions des styles de puces qui ne sont pas rendus. C'est le style par défaut qui sera rendu dans le document Docbook (en général, par le petit cercle des puces standards).
Les retours de lignes produiront des paragraphes correctement imbriqués dans les items de listes dans le document Docbook.
Note | |
---|---|
Les listes à puces peuvent être imbriquées avec des listes numérotées. |
Elles sont complètement supportées y compris les types de numérotation utilisées (chiffres arabes, chiffres romains, listes alphabétiques).
Les retours de lignes produiront des paragraphes correctement imbriqués dans les items de listes dans le document Docbook.
Note | |
---|---|
Les listes à puces peuvent être imbriquées avec des listes numérotées. |
Elles sont supportées mais pour un seul niveau. Il n'est pas possible de faire de sous-listes de termes.
Le terme doit être un paragraphe en style Term. Il doit être suivi d'un seul paragraphe de style Definition.
Les retours de lignes dans un paragraphe de définition produiront des paragraphes correctement imbriqués dans le document Docbook.
La plupart des fonctionnalités hypertextes sont supportées.
Les hyperliens d'OOo sont convertis en <ulink>.
L'attribut Frame des hyperliens d'OOo est converti en attribut Type dans le Docbook. Il permet de passer les valeurs de Target (_parent, _blank, etc.).
Seules les images ancrées comme caractères supportent les hyperliens (règle de la Docbook).
Par conséquent, les hyperliens sur images flottantes sont perdus (ancrage au paragraphe ou au caractère).
Les images ancrées à la page sont perdues.
Les images ancrées comme caractère sont converties en <inlinemediaobject>.
Les images ancrées au paragraphe ou au caractère sont converties <mediaobject>.
L'attribut texte facultatif d'une image est converti en <textObject> (texte de remplacement en cas d'affichage textuel).
On accède à cette attribut en sélectionnant l'image et en faisant :
Les dimensions d'affichage des images sont supportées.
Les images légendées (menu Insertion > Légende...) sont converties en <figure>.
OOo2sDbk supporte les images liées et incorporées.
Les images incorporées sont extraites du fichier SXW et rassemblées dans un répertoire images créé dans le même répertoire que le document Docbook :
Les images sont nommées img001.xxx, img002.xxx, etc. La numérotation suit l'ordre d'apparition des images dans le document.
Les images ne subissent aucune conversion.
Il est possible de modifier le nom du répertoire images et le radical "img" des images dans le fichier de configuration config.xml.
La liaison vers une image liées est transmise telle quelle au document Docbook :
les liens sont passés au document Docbook sans modification.
Note | |
---|---|
A propos du convertisseur Flat XML. La feuille de styles d'OOo2sDbk est incapable d'extraire les images incorporées dans un document OpenOffice-XML généré par le filtre Flat XML. L'opération est réalisée par les scripts en Python. |
OpenOffice permet un placement subtil des images flottantes. Il est impossible à rendre dans le Docbook.:
L'alignement horizontal des images flottantes est perdu. A ma connaissance, le Docbook ne supporte pas cette fonction.
Les images flottantes alignées en haut, au milieu ou d'en haut dans OOo seront placées au-dessus du paragraphe d'ancrage dans le Docbook.
Les images flottantes positionnées en bas seront placées à la suite du paragraphe d'ancrage dans le Docbook.
La commande Légende appliquée à une image créée un cadre qui incorpore l'image et le texte de la légende.
La légende est converti en <title> dans <figure>.
OOo2sDbk n'est pas capable de gérer les cadres ancrés comme caractère. Au cas où cela se produirait, les cadres seraient placés au dessus du paragraphe de référence.
Les styles ou les objets d'OpenOffice qui ne sont pas présents dans ce tableau ne sont pas supportés par le convertisseur. Dans la plupart des cas, le contenu est préservé. Par exemple, un paragraphe en style Alinéa sera tout simplement converti en un paragraphe standard.
OpenOffice.org |
Remarques |
Simplified Docbook |
||
---|---|---|---|---|
Style ou objet |
Type |
Balise |
Type |
|
Abstract |
Par. |
Voir Résumé |
<abstract> |
Block |
Accentuation |
Car. |
<emphasis> |
Inline |
|
Accentuation forte |
Car |
<emphasis role="strong"> |
Inline |
|
Acronym |
Car |
<acronym> |
Inline |
|
Attribution |
Par. |
Doit être placé immédiatement après un paragraphe Citation, Blockquote ou Epigraph. |
<attribution> |
Block |
Author |
Par |
<author> |
Block |
|
Authorblurb |
Par |
Doit être placé immédiatement après un paragraphe Author, Editor ou Othercredit. |
<authorblurb> |
|
Bibliomisc |
Par |
Voir Bibliomisc |
<bibliomisc> |
Block |
Blockquote |
Par |
Peut-être suivi d'un paragraphe Attribution. |
<blockquote> |
Block |
Citation |
Car |
<quote> |
Inline |
|
Citation |
Par |
Peut-être suivi d'un paragraphe Attribution. |
<blockquote> |
Block |
Citetitle |
Car |
<citetitle> |
Inline |
|
Command |
Car |
<command> |
Inline |
|
Contenu de tableau |
Par |
<para> |
Block |
|
Copyright |
Par |
Seuls les années en style Year et le détenteur des droits en style Holder sont convertis. Voir Copyright |
<copyright> |
|
Corpauthor |
Par |
Voir Corpauthor |
<corpauthor> |
|
Corps de texte |
Par |
Voir Paragraphes |
<para> |
Block |
Definition |
Par |
Doit être précédé d'un paragraphe Term sinon le paragraphe est converti en <para> . Voir Listes de termes (varlist) et Les retours de lignes dans les paragraphes |
<definition> |
Block |
Car |
Voir Email (pose problème dans la simplified Docbook) |
<email> |
Inline |
|
Filename |
Car |
<filename> |
Inline |
|
Firstname |
Car |
Doit être placé dans un paragraphe Author, Editor ou Othercredit. |
<firstname> |
Inline |
Holder |
Car |
Doit être placé dans un paragraphe Copyright (plusieurs fois s'il y a plusieurs détenteurs des droits). Voir Copyright |
<holder> |
Inline |
Honorific |
Car |
Doit être placé dans après un paragraphe Author, Editor ou Othercredit. |
<honorific> |
Inline |
Image ancrée "comme caractère" |
Objet |
Voir Images et figures |
<inlinemediaobject> |
Inline |
Image flottante |
Objet |
Voir Images et figures |
<mediaobject> |
Bloc |
Image flottante légendée |
Objet |
<figure> |
Block |
|
Jobtitle |
Car |
Doit être placé dans un paragraphe Author, Editor ou Othercredit. |
<affiliation><jobtitle> |
Inline |
Legalnotice |
Par |
<legalnotice> |
Block |
|
Légende |
Par |
Le style Légende ne doit pas être inséré manuellement, il doit être inséré avec la commande Insertion > Légende. Seules les légendes des tableaux et des images sont supportées. Voir la section Tableaux et la section Images et figures |
<title> |
Block |
Lien internet |
Attention. Ce n'est pas le style Lien internet qui est converti mais bien la présence d'un lien hypertexte. Voir la section URLs |
<ulink> |
Inline |
|
Lineage |
Car |
Doit être placé dans un paragraphe Author, Editor ou Othercredit. |
<lineage> |
Inline |
Lineannotation |
Car |
Doit être placé dans un paragraphe Programlisting ou Texte préformatté. |
<lineannotation> |
Inline |
Liste de termes |
Il s'agit d'une succession de paragraphes Term suivi chacun d'un paragraphe Definition (un seul). |
<varlist> |
Block |
|
Liste numérotées |
Par |
Les listes numérotées peuvent avoir plusieurs niveaux d'imbrication. Les types de numérotation sont convertis (numérique, alphabétiques et romains) Voir Liste numérotées |
<ordoredlist> |
Block |
Listes à puces |
Par |
Les listes à puces peuvent avoir plusieurs niveaux d'imbrications Voir Listes à puces |
<itemizedlist> |
Block |
Note |
Par |
Elle peuvent être précédées d'un paragraphe de titre rédigé en style Titre. Voir Notes |
<note> |
|
Note de fin et de bas de page |
Par |
Les notes de bas de pages et de fin de document ne sont pas distinguées. Le label utilisé pour l'appel de note est converti. |
<footnote> |
Block |
Option |
Car |
<option> |
Inline |
|
Orgname |
Car |
Doit être placé dans un paragraphe Author, Editor ou Othercredit. |
<orgname> |
Inline |
Othername |
Car |
Doit être placé dans un paragraphe Author, Editor ou Othercredit. |
<othername> |
Inline |
Programlisting |
Par |
Les espaces, les retours de lignes et les tabulations sont préservées. Les tabulations sont converties en 4 espaces. |
<programlisting> |
Bloc |
Pubdate |
Par |
Voir Date de publication |
<pubdate> |
Block |
Référence à une note |
Inline |
Référence à une note déjà existante (Insertion > Renvoi >Références > Notes de bas de page) |
<footnotref> |
Inline |
Releaseinfo |
Par. |
Uniquement dans les métadonnées Voir Version du document |
<releaseinfo> |
Block |
Replaceable |
Car |
<replaceable> |
Inline |
|
Saisie de l'utilisateur |
Car |
Identique au style Userinput |
<userinput> |
Inline |
Sous-titre |
Par. |
Uniquement dans les métadonnées. |
<subtitle> |
Block |
Standard |
Par. |
Voir Paragraphes |
<para> |
Block |
Surname |
Car |
Doit être placé dans un paragraphe Author, Editor ou Othercredit. |
<surname> |
Inline |
Tableau avec légende |
Objet |
Voir Tableaux |
<table> |
Block |
Tableau sans légende |
Objet |
Voir Tableaux |
<informaltable> |
Block |
Term |
Par. |
<term> |
Block |
|
Texte non proportionnel |
Car |
Identique au style Literal |
<literal> |
Inline |
Texte préformatté |
Par. |
Identique à programlisting Les espaces, les retours de lignes et les tabulations sont préservées. Les tabulations sont converties en 4 espaces. |
<programlisting> |
Block |
Texte source |
Car |
Identique au style Literal |
<literal> |
Inline |
Titre |
Par. |
Il ne sera converti en <title> que s'il précède des paragraphes susceptibles de recevoir un titre :
|
<title> |
Block |
Titre 1...9 |
Par |
Voir Titres et sections |
<section><title> |
Block |
Titre principal |
Par |
Titre du document |
<title> |
Block |
Variable |
Car |
Le texte est transmit sans balise car le tag correspondant dans la Docbook (<varname>) n'est pas implémenté dans la DTD simplified Docbook. |
||
Year |
Car |
Doit être placé dans un paragraphe Copyright (plusieurs fois s'il y a plusieurs détenteurs des droits). Voir Copyright |
<year> |
Inline |
[1] OpenOffice propose un gestionnaire de version de document. Toutefois, le fichier XML qui conserve cet historique se trouve dans une partie séparée des fichiers XML standards d'OpenOffice et n'est pas intégré dans la DTD. Il ne faut donc pas espérer un support rapide.