Table des matières (TDM)

Identificateur : org.eclipse.help.toc

Description : destiné à l'enregistrement de la contribution d'une aide en ligne pour un plug-in individuel.

Chaque plug-in contribuant aux fichiers d'aide doit en général procéder comme suit :

Marques de configuration du point d'extension toc (elles correspondent au contenu du fichier plugin.xml) :

    <!ELEMENT toc EMPTY>
    <!ATTLIST toc file CDATA #REQUIRED>
    <!ATTLIST toc primary (true | false) "false">
    <!ATTLIST toc extradir CDATA #IMPLIED>

Marques de configuration de la table des matières (elles correspondent aux éléments du fichier TDM) :

    <!ELEMENT toc (topic | anchor | link)* >
    <!ATTLIST toc link_to CDATA #IMPLIED >
    <!ATTLIST toc label CDATA #REQUIRED >

    <!ELEMENT topic (topic | anchor | link )* >
    <!ATTLIST topic label CDATA #REQUIRED >
    <!ATTLIST topic href CDATA #IMPLIED >

    <!ELEMENT anchor EMPTY >
    <!ATTLIST anchor id ID  #REQUIRED >

    <!ELEMENT link EMPTY >
    <!ATTLIST link toc CDATA #REQUIRED >

En général, un plug-in devant fournir une aide en ligne définira ses propres fichiers TDM. En fin de compte, le système d'aide est configuré pour être lancé en fonction de certaines actions et le chemin au fichier TDM peut être utilisé à cette fin.

L'élément de rubrique

Tous les éléments de rubrique sont ajoutés comme parties du conteneur de la table des matières. Ces dernières peuvent avoir une structure hiérarchique et figurer dans une liste à plat.

La rubrique est l'élément le plus utile de la structure de la table des matières. La rubrique a deux fonctions :

1. Fournir une liaison à un fichier de documentation, un fichier HTML en général.
2. Agir comme conteneur pour d'autres tables de matières, dans le même manifeste ou dans un autre.

1. Les rubriques en tant que liens
L'utilisation la plus simple d'une rubrique est comme lien à un fichier de documentation.

<topic label="Some concept file" href="concepts/some_file.html" />

L'attribut href est relatif au plug-in auquel appartient le fichier manifeste. Si vous devez accéder à un fichier dans un autre plug-in, vous pouvez utiliser la syntaxe suivante :

<topic label="topic in another plug-in" href="../other.plugin.id/concepts/some_other_file.html"/>

2. Les rubriques en tant que conteneurs
La rubrique peut ensuite servir de conteneur à une autre table des matières.  La rubrique conteneur elle-même peut toujours faire référence à un fichier spécifique.

<topic label="Integrated Development Environment" href="concepts/ciover.htm">
  <topic label="Starting the IDE" href="concepts/blah.htm"/>
  ...
</topic>

L'élément de liaison

L'élément de liaison permet de relier la table des matières définie dans un autre fichier TDM. Toutes les rubriques du fichier TDM spécifiées dans l'attribut toc apparaîtront fans la table des matières comme si elles étaient directement définies à la place de l'élément lien. Pour inclure la table des matières à partir du fichier api.xml, vous pouvez écrire :

<topic label="References" >
  ...
  <link toc="api.xml" />
  ...
</topic>

L'élément d'ancrage

L'élément d'ancrage définit un point qui permettra de relier d'autres fichiers TDM à cette navigation et de l'étendre sans utiliser l'élément de liaison ni référencer d'autres fichiers à partir de cet endroit. Pour permettre l'insertion de la table des matières avec plus de rubriques après le document "ZZZ", vous devez définir un point d'ancrage comme suit :

...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...

L'élément TDM

L'élément TDM est une table des matières regroupant des rubriques et d'autres éléments définis dans ce fichier. Le libellé identifie la table des matières pour l'utilisateur au moment de l'affichage. L'attribut facultatif link_to permet de relier la table de ce fichier à une autre plus haut dans la hiérarchie de navigation. La valeur de l'attribut link_to doit spécifier un point d'ancrage dans un autre fichier TDM. Pour effectuer une liaison de myapi.xml à un fichier api.xml spécifié dans un autre plugin, vous devez utiliser la syntaxe

<toc link_to="../anotherPlugin/api.xml#moreapi" label="My Tool API"/>
...
<toc />

où le caractère # sépare le nom du ficher TDM d'un autre identificateur d'ancrage.

Exemples :

Voici un exemple d'utilisation du point d'extension toc. Présumons que l'ID du plug-in concerné est "org.eclipse.help.examples.ex1". L'exemple est d'ordre général. Sachez que la même hiérarchie de documentation, formée avec tous les fichiers TDM ci-après, peut également être créée en combinant différemment d'autres fichiers TDM.

(dans le fichier plugin.xml)

 <extension point="org.eclipse.help.toc">
  <toc file="maindocs.xml" primary="true" />
  <toc file="task.xml" />
  <toc file="sample.xml" extradir="samples" />
 </extension>
 

(dans le fichier maindocs.xml)

<toc label="Help System Example">
 <topic label="Introduction" href="intro.html"/>
 <topic label="Tasks">
  <topic label="Creating a Project" href="tasks/task1.html">
   <topic label="Creating a Web Project" href="tasks/task11.html"/>
   <topic label="Creating a Java Project" href="tasks/task12.html"/>
  </topic>
  <link toc="task.xml" />
  <topic label="Testing a Project" href="tasks/taskn.html"/>
 </topic>
 <topic label="Samples">
  <topic label="Creating Java Project" href="samples/sample1.html">
   <topic label="Launch a Wizard" href="samples/sample11.html"/>
   <topic label="Set Options" href="samples/sample12.html"/>
   <topic label="Finish Creating Project" href="samples/sample13.html"/>
  </topic>
  <anchor id="samples" />
 </topic>
</toc>


(dans le fichier tasks.xml)

<toc label="Building a Project">
 <topic label="Building a Project" href="build/building.html">
  <topic label="Building a Web Project" href="build/web.html"/>
  <topic label="Building a Java Project" href="build/java.html"/>
 </topic>
</toc>


(dans le fichier samples.xml)

<toc link_to="maindocs.xml#samples" label="Using The Compile Tool">
 <topic label="The Compile Tool Sample" href="compilesample/example.html">
  <topic label="Step 1" href="compilesample/step1.html"/>
  <topic label="Step 2" href="compilesample/step2.html"/>
  <topic label="Step 3" href="compilesample/step3.html"/>
  <topic label="Step 4" href="compilesample/step4.html"/>
 </topic>
</toc>


La hiérarchie de la documentation résultante dans le plan de travail Eclipse est le suivant :

Help Sample

En supposant que d'autres documents existent avec le chemin commençant par "samples", ils n'apparaîtront pas dans l'arborescence mais seront accessibles par le biais de recherches. La raison est la présence de l'attribut "extradir" dans l'élément <toc file="sample.xml" extradir="samples"/> à l'intérieur du fichier plugin.xml. Par exemple, la recherche de "Création d'un projet Java" peut renvoyer un document "Autres modes de création d'un projet Java", dont le chemin est samples/sample2.html.

Internationalisation

Les fichiers XML TDM peuvent être traduits et la copie obtenue (avec les intitulés également traduits) doit être placée dans le répertoire nl/<langue>/<pays> ou nl/<langue>. Les répertoires <langue> et <pays> correspondent aux codes de langue et de pays de deux lettres utilisés dans les environnements locaux. Par exemple, les traductions en chinois traditionnel doivent être placées dans le répertoire nl/zh/TW. Le répertoire nl/<langue>/<pays> a une priorité supérieure à nl/<langue>. Seulement si un fichier est trouvé dans nl/<langue>/<pays>, celui figurant dans nl/<langue> sera utilisé. Le répertoire racine du plug-in sera inspecté en dernier.

La documentation se trouvant dans le fichier doc.zip peut être localisée en créant un fichier doc.zip avec la version traduite des documents et en plaçant ce fichier dans le répertoire
nl/<langue>/<pays> ou nl/<langue>. Le système d'aide recherchera les fichier dans ces répertoires avant d'aller par défaut dans le répertoire du plug-in.
 

Informations d'API : aucun code n'est requis pour utiliser le point d'extension. Il suffit de fournir les fichiers manifestes appropriés, mentionnés dans le fichier plugin.xml.
 

Implémentation fournie : L'implémentation par défaut de l'interface utilisateur du système d'aide fournie avec la plateforme Eclipse supporte le point d'extension toc.


Copyright IBM Corp. and others 2000, 2002. All Rights Reserved.