Introduction à Docbook

Cet éditeur est l'un des meilleurs disponibles, et il présente l'avantage d'être distribué gratuitement. Il permet d'éditer le document en mode WYSIWYG, avec balises visibles (simples ou encadrant leur contenu), en mode source (pas d'auto-complètement cependant).

Il est possible de sélectionner un mot dans une liste importante en tapant ses premières lettres, ce qui facilite grandement l'écriture lors de l'insertion d'éléments par des raccourcis clavier. L'insertion d'entités est par contre plutôt fastidieuse.

Il est possible d'éditer les tableaux et d'afficher les images JPEG et GIF lors de l'édition.

Un éditeur de page de style (CSS) est aussi disponible, ainsi qu'un fichier CSS pour DocBook ; ce dernier nécessite cependant quelques modifications pour être véritablement utilisable, comme par exemple pour permettre l'affichage des JPEG.

Un correcteur orthographique est disponible, mais seul un dictionnaire américain est fourni. On peut trouver un dictionnaire français là : http://www.macromedia.com/support/dictionaries/

setenv LC_ALL fr_FR

export LC_ALL=fr_FR

Lien : http://www.morphon.com/

Morphon XML Editor

Il s'agit là aussi d'un des meilleurs éditeurs disponible. Édition possible en mode WYSIWYG et arbre simultanément.

Correcteur orthographique.

Interface très pratique.

Lien : http://www.xmlmind.com/xmleditor/index.html

XXE

Cet éditeur est spécialisé dans le mode source où il offre une possibilité d'auto-complètement des balises au fur et à mesure qu'on les tape. Il existe aussi un mode arbre, mais qui est malheureusement affiché dans une fenêtre différente.

Configuration de la conversion du document XML vers un autre format intégré à l'interface.

Correcteur orthographique intégré.

Lien : http://www.oxygenxml.com/index.html

oXygen

Le mode d'édition principale est avec balises simples. Il est possible d'éditer le source avec peu de fonctionnalités.

Ne gère pas les URL du type file://localhost/...!!!

Lien : http://www.epcedit.com/

epcEdit

Petit éditeur, simple mais complet, avec la liste des balises possibles accessible facilement. Mode d'édition unique avec balises simples ou sur une ligne.

Aucun raccourci clavier! Argl!

Rendu HTML accessible depuis l'interface.

Correcteur orthographique.

Lien : http://jaxe.sourceforge.net/Jaxe.html

Jaxe

Lyx est un éditeur WYSIWYG conçu initialement pour fonctionner avec LaTeX. Il est capable dans ses dernières versions d'exporter un fichier au format DocBook, mais la rédaction du document se fait selon la structure propre à Lyx et non selon celle d'un document DocBook. Il n'est d'ailleurs pas possible d'ouvrir directement un fichier au format DocBook.

Lien http://www.lyx.org/

Lyx

Unique mode d'édition par arbre.

Interface sous Linux peu esthétique.

Impossible de changer de DTD sans relancer l'application.

Lien : http://www.alphaworks.ibm.com/tech/xeenal

Xeena

Éditeur permettant la rédaction en mode source avec auto-complètement, ainsi qu'en mode arbre.

Gestion de projet.

Lien : http://www.cladonia.com/products.htm.

Exchanger XML Editor

Cet éditeur propose la rédaction de document sous forme d'arbre ou en mode source basique.

Trouve des erreurs dans le DTD DocBook officiel!

Un éditeur de Schema/DTD est aussi intégré

Lien : http://www.tibco.com/solutions/products/extensibility/turbo_xml.jsp

TurboXML

Cet éditeur, bien que présenté pour la rédaction en XML, présente plutôt des fonctionnalités dignes d'un bon éditeur classique... mais sans rien apporter de particulier pour l'édition du DocBook, à part la coloration syntaxique. Le mode source est le seul mode d'édition proposé, et il n'y a pas d'auto-complètement des balises, ni de boîtes de dialogues.

Il possède cependant des fonctions originales pour dialoguer d'un éditeur à un autre dans un réseau.

Lien : http://www.topologi.com/products/tme/

Collaborative Markup Editor

Cet éditeur, dont la dernière version stable date de juin 2002, est plutôt limité. Il ne permet que l'édition en mode arbre, et n'est pas vraiment conçu pour être utilisé avec DocBook et ses centaines de balises.

D'après sa documentation, il serait plutôt étudié, grâce à une API adequate, pour pouvoir utiliser des plugins rendant l'édition plus facile ou plus spécifique aux besoins de l'utilisateurs. Le nombre de plugins disponible semble cependant assez limité...

Lien : http://www.xerlin.org/

Xerlin

Enfin un éditeur XML sous Linux écrit en C... mais toujours en beta version, et malheureusement inutilisable à cause de ses plantages fréquents...

Il propose un mode d'édition assez esthétique, avec des balises visibles encadrant leur contenu

Lien : http://www.conglomerate.org

Conglomerate

Cet éditeur possède l'interface et les principales fonctionnalités d'Emacs, tout en restant très petit. Il possède d'autres fonctionnalités intéressantes, comme par example l'édition simultanée en mode source ou en mode WYSIWYG. Il ne se limite pas à DocBook et est aussi conçu pour d'autres langages.

Il manque cependant encore de maturité et ne propose pas de fonctions spécifiques à DocBook comme l'auto-complètement, la validation, la conversion...

Lien : http://qemacs.org/

Qemacs

Ce petit éditeur est en fait un composant Java qu'il est possible d'intégrer dans d'autres applications. Il propose l'édition en mode source avec colorisation syntaxique et une vue sous forme d'arbre.

Lien : http://www.japisoft.com/xmlpad/

Je ne présenterais pas cet éditeur... Sachez juste qu'il existe des packages lui permettant de gérer le DocBook, comme PSGML ou DocBook IDE.

Lien Emacs : http://www.gnu.org/software/emacs/emacs.html

Lien PSGML : http://www.lysator.liu.se/~lenst/about_psgml/

Lien DocBook IDE : http://nwalsh.com/emacs/docbookide/

Éditeur en développement (depuis un moment d'ailleurs), que je n'ai pas réussi à compiler.

Lien : http://idx-getox.idealx.org/

Cet éditeur est une application web tournant en partie sur le serveur, en partie chez le client sous forme de Javascript. Il faut cependant le serveur adéquat pour l'installer...

Lien : http://www.lucid-it.com/en/tech-zone/editor/

Impossible de le compiler sous Linux, d'autre part les fonctionnalités semblent très pauvres et le projet abandonné...

Lien : http://www.cogsci.ed.ac.uk/~ht/xed.html

La version d'évaluation plantant au démarrage, on ne saura pas ce que vaut cet éditeur qui n'a pas l'air bien différent des autres...

Lien : http://www.vervet.com/xmlpro.html

Développement figé depuis décembre 1999, d'autre part ne fonctionne qu'avec JDK1.1.8.

Lien : http://www.cogsci.ed.ac.uk/~ht/xed.html

Lien : http://www.iol.ie/~pxe/index.html

Lien : http://xml.cooktop.com

Lien : http://www.elfdata.com/xmleditor/

Lien : http://www.xmlspy.com/

Projet en phase initiale, consistant à utiliser Thot Editor ou la Thot Lib pour éditer du DocBook.

Lien Thot Editor : http://opera.inrialpes.fr/Thot/index.html

Lien Thot Book : http://www.nongnu.org/thotbook/

Ces éléments vont contenir l'ensemble du document. Il s'agit des éléments racines les plus usuels et choisir l'un ou l'autre va dépendre de la taille du document et de ce qu'il doit contenir.

<article> est le plus simple : il ne pourra pas contenir de composants comme une préface ou des chapitres. Il contient généralement un <title>, puis il doit obligatoirement contenir au moins une section ou un élément bloc comme <para>, <table>, <mediaobject>... cependant l'ordre des éléments importe : un paragraphe peut précéder une section, l'inverse n'étant pas vrai! Un <article> peut aussi contenir des composants comme <appendix>, <toc> (table of content) ou <bibliography>, mais ils obéissent à des règles assez strictes.

<article>
   <title>L'article de la mort (qui tue)</title>
   <para>Rentrons dans le vif  du sujet!</para>
   <section>
      ...
   </section>
</article>

L'élément <book>, en plus d'un <title>, peut contenir les composants : <toc>, <lot>, <preface>, <chapter>, <appendix>, <glossary>, <bibliography>, <index> qui peuvent aussi être regroupés en parties (<part>).

<book>
   <title>Livre Ognerie</title>
   <toc/>
   <preface>
      <title>Introduction</title>
      <para> Blablabla... </para>
   </preface>
   <part>
      <title> 1ère partie </title>
      <chapter>
         <title>Chapitre eurie</title>
         <para> Et patati et patata... </para>
      </chapter>
   </part>
   <index>
      ...
   </index>
</book>

Un autre élément racine ou composant pouvant se révéler utile est <reference>, qui contient un ensemble de pages de référence (comme les manpage sous unix).

L'élément <title> est utilisé, comme nous venons de le voir, pour les <book> et <article>, mais aussi pour les composants et les éléments blocs qui en exigent fréquemment un. Certains éléments peuvent en être dispensés, à condition de commencer par <informal>, comme <informaltable>.

Il peut être suivi des éléments <subtitle> et <titleabbrev>.

Les sections se trouvent généralement dans les <article> ou les <chapter>. Elles existent sous la forme recursive <section> ou absolue <sect1>, <sect2>... Il existe aussi <simplesect> qui est le dernier niveau d'imbrication de section, ainsi que <bridgehead> qui est une fausse section sans contenu.

Les paragraphes (<para>) sont les éléments bloc les plus utilisés. Ils existent aussi sous la forme <formalpara> et contiennent un <title> et un <para> normal, ainsi que sous la forme <simpara>, où ils ne peuvent pas contenir d'éléments bloc.

Tous les éléments <book>, divisions, composants, sections et bloc possèdent un élément optionel de meta-informations où peuvent être placer différentes informations (auteur, version, copyright...) qui n'apparaiteront pas forcement dans le document final. En voici quelques uns (la liste est longue!) : <bookinfo>, <articleinfo>, <sectioninfo>, <blockinfo> (ce dernier correspond à n'importe quel élément bloc).

Les informations les plus courantes sont les suivantes (j'ai indiqué la manière dont elles s'imbriquent les unes dans les autres par des retraits par rapport au début de la ligne) :

<title>              titre du document
<author>             nom de l'auteur
   <honorific> (M., Mme, Dr), <firstname>, <surname>, <lineage> (Junior, Senior...), <othername>
   affiliation   l'organisation auquelle appartient un individu
      <jobtitle>     la profession au sein de l'organisation
      <orgname>      le nom de l'organisation
      <orgdiv>       le nom d'une division
   <address>         l'adresse d'un individu
      <street>, <pob> (boîte postale), <postcode>, <citystate>, <country>, <phone>, <fax>, <email>, <otheraddr>
<copyright>          copyright, avec année(s) et détenteur
   <year>, <holder>
<date>               date de publication ou de révision
<releaseinfo>        informations sur la distribution actuelle
<revhistory>         historique des révisions
   <revision>        entrée décrivant une révision
      <revnumber>    numéro de révision
      <revremark>    commentaire associé
<legalnotice>        informations légales
<keywordset>         ensemble de mots-clefs correspondants au document
   <keyword>         entrée correspondant à un mot-clef

<abbrev>          abréviation
<acronym>         acronyme (abréviation se prononçant comme un mot normal)
<citetitle>       titre d'une oeuvre
<emphasis>        italique
<foreignphrase>   expression étrangère
<personname>      nom d'une personne
<replaceable>     partie à remplacer par l'utilisateur (comme <sectn> à la place de <sect1>, <sect2>...)
<quote>           citation
<subscript>       indice (example)
<superscript>     exposant (example)
<markup>          expression à représenter tel quel
<productname>     nom d'un produit
<trademark>       marque déposée

Certains éléments inline cités dans la section Méta-informations peuvent aussi servir dans un bloc normal comme <address> ou <email>. De plus, la section Termes informatiques traite de tous les éléments ayant trait à l'informatique.

<simplelist>         liste simple, peut être définie horizontale ou verticale grâce à l'attribut type,
   <member>          entrée, contient directement le texte,

<itemizedlist>       liste avec puce,
   <listitem>        entrée, doit contenir un élément bloc comme <para,>

<orderedlist>        liste ordonnée,
   <listitem>        entrée (cf. au dessus),

<variablelist>       liste dont chaque entrée associe un terme à une description,
   <varlistentry>    entrée,
      <term>         terme à décrire,
      <listitem>     description (cf. au dessus),
   
<segmentedlist>      liste comprenant plusieurs titres, et dont chaque entrée possède une sous-entrée pour chaque titre,
   <segtitle>        titre, contient directement le texte,
   <seglistitem>     entrée, (doit contenir autant de <seg> qu'il y a de <segtitle> en début de liste),
      <seg>          sous-entrée, contient le texte directement.

DocBook utilise les tableaux de type CALS de XML, qui offrent beaucoup de possibilités. Là encore, il est conseillé de se reporter à la documentation officielle pour leur utilisation exacte (notamment la liste des attributs et les exemples).

<informaltable>           tableau sans titre
<table>                   tableau avec titre
   <tgroup>               contient le tableau et spécifie le nombre de colonnes dans l'attribut cols
      <spanspec>          associe un nom à un étalement sur plusieurs colonnes (optionnel)
      <colspec>           formate une colonne (optionnel)
      <thead>             première(s) rangée(s) du tableau, généralement l'en-tête (optionnel)
      <tfoot>             dernière(s) rangée(s) du tableau (optionnel)
      <tbody>             corps du tableau, contient les rangées sans formatage particulier
         <row>            contient une rangée
            <entry>       cellule du tableau (pouvant s'étaler sur plusieurs colonnes ou rangées)
            <entrytbl>    cellule contenant un sous tableau

Il est possible grâce à l'élément <mediaobject> d'insérer dans un document des images, des vidéos ou du son. On ne s'intéressera ici qu'aux images ; il est possible de donner une description textuelle de l'objet, dans le cas où l'image ne peut s'afficher.

<mediaobject>         insère un objet en mode bloc
<inlinemediaobject>   insère un objet en mode inline (permet de l'inclure dans un <ulink>)
   <caption>          titre de l'objet
   <imageobject>      image correspondant à l'objet
      <imagedata>     fichier ou entité contenant l'image

   <textobject>       texte correspondant à l'objet, contient <textdata> ou un autre élément bloc (comme <para>)
      <textdata>      fichier ou entité contenant le texte

On précise les noms de fichiers ou d'entités dans l'élément <imagedata> (ainsi que <textdata>) grâce aux attributs fileref ou entityref (voir section sur les entités). La taille de l'objet peut être est spécifiée à différents niveaux :

On peut aussi préciser le format de l'image avec format ; cela permet de proposer plusieurs formats et de laisser l'application traitant le document choisir celui qu'elle préfère.

DocBook est particulièrement bien pourvu pour la documentation informatique. Il possède un très grand nombre d'éléments identifiant le type de données et de termes. Voici la liste des éléments blocs :

<screen>              texte sur un écran, reproduit le contenu tel quel (existe aussi avec callouts),
<programlisting>      listing, reproduit le contenu tel quel (existe aussi avec callouts),
<synopsis>            décrit la syntaxe d'une commande ou fonction (beaucoup d'éléments associés : se référer à la doc!),
   <lineannotation>   ligne de commentaire pour un des 3 éléments in extenso ci dessus,

<screenshot>          copie d'écran, contient un <mediaobject>,

Les éléments inline étant très nombreux, la liste suivante n'est pas exhaustive :

<computeroutput>   texte généré par l'ordinateur,
<userinput>        texte tapé par 'utilisateur,

<application>      nom d'un logiciel,
<command>          nom d'un executable,
<filename>         nom d'un fichier
<systemitem>       terme relatif à un système (comme le nom d'un OS ou d'une ressource),
<hardware>         composant hardware
<sgmltag>          balise SGML ou XML,
<constant>         nom d'une constante,
<errortext>        message d'erreur,
<envar>            variable d'environnement,
<variable>         variable
<prompt>           invite au début d'une ligne de commande,
<property>         propriété,
<guibutton>        nom d'un bouton dans une GUI (interface graphique utilisateur),
<guimenu>          nom d'un menu dans une GUI,
<guimenuitem>      nom d'une entrée dans un menu,
   <accel>         lettre raccourci clavier dans un menu (comme F dans Fichier,)
<shortcut>         raccourci clavier
   <keycombo>      combinaison de touches
      <keycap>     nom d'une touche

<literallayout>       texte reproduit in extenso (tel quel/verbatim)
   <lineannotation>   commentaire
<example>             exemple avec un titre
<informalexample>     exemple sans titre
<figure>              figure avec un titre pouvant être flottante (attribut <float> à 1)
<informalfigure>      figure sans titre pouvant être flottante
<blockquote>          citation
   <attribution>      auteur d'une citation
<abstract>            résumé
<highlights>          point principaux
<caution>, <important>  admonitions
<warning>, <note>, <tip>
<remark>

<qandaset>            ensemble de questions/réponses
   <qandadiv>         titre d'une division de l'ensemble
   <qandaentry>       entrée comprenant une question et (optionnel) une ou plusieurs réponses
      <question>      question (le "Q :" par défaut peut être changer par <label>)
      <answer>        réponse (le "A :" par défaut peut être changé par <label>)
         <label>      change le label d'une question ou réponse

<sidebar>             bloc séparé du reste du texte normal du document

<procedure>           description d'une procédure, d'un algorithme
   <step>             étape dans la procédure
      <substeps>      sous-étape

DocBook possède encore plusieurs familles d'éléments intéressantes qui ne seront pas détaillées ici. Il s'agit d'éléments permettant l'écriture de bibliographies (élément racine : <bibliography>), de glossaires (<glossary>), de tables des matières (<toc>, souvent générées automatiquement), d'index (<index>), de pages de référence (<reference>) et des modules EBNF, HTML Form, SVG et MathML.

Il s'agit de mot-clés permettant par exemple de remplacer une expression souvent employée. Elles sont définies ainsi en début de document (à la fin du tag DOCTYPE, entre crochets) : <!ENTITY entité "expression"> puis elles sont instanciées par &entité;.

<?xml version="1.0" encoding="..."?>
<!DOCTYPE book PUBLIC "..." "..." [
<!ENTITY bz "bizarre">
]>
<book>
...
<para>
- Oui, vous regardez votre couteau et vous dîtes &bz;,&bz;. Alors je croyais que ...
</para><para>
- Moi, j'ai dit &bz;, &bz;, comme c'est étrange ! Pourquoi aurais je dit &bz;, &bz; ?
</para><para>
- Je vous assure mon cher cousin, que vous avez dit &bz;, &bz;.
</para><para>
- Moi, j'ai dit &bz;,  comme c'est &bz; !" 
</para>
...

Elles permettent d'inclure un fichier externe dans le document.

<?xml version="1.0" encoding="..."?>
<!DOCTYPE book PUBLIC "..." "..." [
<!ENTITY chap1 SYSTEM "/home/antoine/doc/a_la_banane.xml">
<!ENTITY chap2 SYSTEM "/home/antoine/doc/au_raisin.xml">
]>
<book>
   <title>Les tartes aux fruits</title>
   &chap1;
   &chap2;
</book>

Il est possible d'inclure des fichiers binaires, à condition de préciser leur type dans la définition (NDATA suivi du type) et de les inclure uniquement en tant qu'attributs.

<?xml version="1.0" encoding="..."?>
<!DOCTYPE article PUBLIC "..." "..." [
<!ENTITY graphic SYSTEM "/path/to/file.png" NDATA PNG>
]>
<article>
...
<imagedata entityref="graphic"/>

Il s'agit en fait d'entités : "&amp;" donnera "&". En voici une petite liste :

    half  ½          num  #         copy  ©        laquo  «
      lt  <          amp  &          reg  ®        raquo  »
      gt  >          ast  *        trade  ™         para  ¶
  dollar  $       commat  @        micro  µ       hellip  …