Qu’est-ce que DITA? Partie 3 : A quoi ressemblent les fichiers DITA?

Exemples de fichiers DITA

Comme je l’avait décrit dans la première partie de cette série d’articles, avec DITA on crée un document de la manière suivante :

  • On crée des fichiers Topic qui sont autant de briques élémentaires de contenu : par exemple un topic intitulé « Mettre en route le produit », un autre « Comprendre les messages d’erreur » …
  • On crée un ou plusieurs fichiers Map qui structurent le document : ordre et hiérarchie des topics
  • On génère le document dans un ou plusieurs formats (PDF, HTML, RobotHelp…) avec un outil de publication

Je souhaite ici vous présenter un exemple de topic DITA, et un exemple de Map DITA. Le but n’est pas de vous apprendre à rédiger avec DITA, simplement de satisfaire votre curiosité : qu’est-ce qu’il y a sous le capot ?

Avant de décortiquer les fichiers DITA, comment sont-ils fabriqués ?

Ils peuvent être créés de deux manières différentes :

Créer des fichiers DITA sans connaitre parfaitement la syntaxe…

Si on est pas un Geek, on peut utiliser un éditeur XML adapté à la rédaction en DITA, comme XML Oxygen ou XML Mind. Ces logiciels aident le rédacteur en affichant à l’écran non pas le code complet, mais une interprétation du code : on se rapproche de l’interface de Word, ouf ! Ces logiciels proposent en plus, et à chaque instant, la bonne syntaxe, et permettent de vérifier que le fichier DITA est valide.

… ou se prendre pour un codeur

On peut utiliser un éditeur de texte standard comme Notepad ++ ou Wordpad.

Cela nécessite de connaitre la syntaxe, le rédacteur doit taper des balises en plus du texte. Cela ressemble au travail d’un programmeur, ou à l’écriture d’un document HTML. L’avantage de cette méthode est de pouvoir travailler avec un logiciel gratuit, et de mettre en évidence les caractéristiques d’un fichier DITA.

Dans la suite de cet article, je présenterai le « code complet », mais pas de panique, même les spécialistes de la syntaxe DITA utilisent souvent des éditeurs XML.

Exemples de Topic DITA

J’ai choisi de vous présenter des fichiers contenus dans le DITA Open Toolkit, qui est un outil de publication libre et gratuit.

Un fichier : Topic de type concept

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
 "../../dtd/technicalContent/dtd/concept.dtd">
<concept id="taskconcept" xml:lang="en-us">
<title>Garage Tasks</title>
<shortdesc>When you go into the garage, be prepared to get your hands dirty!</shortdesc>
<conbody></conbody>
</concept>

Ok, à ce stade cela à l’air compliqué. Regardons ligne par ligne et essayons de comprendre.

Et dans les détails

La première ligne <!--?xml version="1.0" encoding="utf-8"?--> signifie que ce fichier est écrit en langage XML.

Ensuite <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"../../dtd/technicalContent/dtd/concept.dtd">
signifie que le fichier est un fichier de topic DITA de type Concept.

Ensuite arrive le contenu de ce Topic de type Concept. Les éléments du contenu sont encadrés par des balises.

Les balises :

  • sont ces mots contenus dans les signes < et />.
  • permettent d’indiquer quel est le type d’information (titre, corps de texte, étape d’une procédure, entrée d’index…)
  • sont relativement simple à comprendre si on a des notions d’anglais
  • permettront un traitement informatique puissant lors de la publication

Cela fonctionne ainsi : <type balise>contenu</type balise>

On remarque qu’à l’intérieur de Concept, on a 3 éléments :

  • un titre : <title>Garage Tasks</title>
  • une « short description » : <shortdesc>When you go into the garage, be prepared to get your hands dirty!</shortdesc>
  • et d’un corps de texte… vide : <conbody></conbody>

id="taskconcept" xml:lang="en-us" permet d’attribuer à tout ce qui est contenu dans Concept une identité, et la langue utilisée (en-us signifie anglais des USA).

Exemple de Map

Une Map pour organiser les Topics

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN"
"../dtd/technicalContent/dtd/map.dtd">
<map title="Working in the garage">
  <topicref href="tasks/garagetaskoverview.xml" type="concept">
    <topicref href="tasks/changingtheoil.xml" type="task"/>
    <topicref href="tasks/organizing.xml" type="task"/>
    <topicref href="tasks/shovellingsnow.xml" type="task"/>
    <topicref href="tasks/spraypainting.xml" type="task"/>
    <topicref href="tasks/takinggarbage.xml" type="task"/>
    <topicref href="tasks/washingthecar.xml" type="task"/>
  </topicref>
  <topicref href="concepts/garageconceptsoverview.xml" type="concept">
    <topicref href="concepts/lawnmower.xml" type="concept"/>
    <topicref href="concepts/oil.xml" type="concept"/>
    <topicref href="concepts/paint.xml" type="concept"/>
    <topicref href="concepts/shelving.xml" type="concept"/>
    <topicref href="concepts/snowshovel.xml" type="concept"/>
    <topicref href="concepts/toolbox.xml" type="concept"/>
    <topicref href="concepts/tools.xml" type="concept"/>
    <topicref href="concepts/waterhose.xml" type="concept"/>
    <topicref href="concepts/wheelbarrow.xml" type="concept"/>
    <topicref href="concepts/workbench.xml" type="concept"/>
    <topicref href="concepts/wwfluid.xml" type="concept"></topicref>
  </topicref>
</map>

Analysons cette Map

On remarque que le début du fichier ressemble à celui du Topic décortiqué plus tôt : on indique que c’est un fichier XML, puis que c’est un Map DITA.

Ensuite, les balises permettent de faire référence et de hiérarchiser les Topics de la Map :

  • A l’intérieur de l’objet « Map » délimité par les balises <map>; et </map>, se trouveent des lignes de type <topicref href="concepts/lawnmower.xml" type="concept"/>.
  • Chaque ligne « topicref » fait référence à un Topic, à une brique de contenu
  • Lors de la publication d’une Map DITA, un document sera créé en combinant les Topics qui y sont listés
  • L’imbrication des balises permet de hiérarchiser l’information. Lors de la publication, le niveau des titres dépendra de cette imbrication

Après ce survol d’exemples de fichiers DITA, si vous voulez tester la syntaxe par vous-même, je vous conseille le tutoriel en anglais « DITA pour les impatients ».

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *