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 :
<!ELEMENT extension (toc*)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED
>
<!ELEMENT toc EMPTY>
<!ATTLIST toc
file CDATA #REQUIRED
primary
(true | false) "false"
extradir CDATA #IMPLIED
>
Marques de configuration du fichier TDM :
<!ELEMENT toc (topic | anchor | link)* >
<!ATTLIST toc link_to CDATA #IMPLIED >
<!ATTLIST toc label CDATA #REQUIRED >
<!ATTLIST toc topic CDATA #IMPLIED >
<!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 topic est le chemin d'accès à un fichier de rubriques décrivant la table de matières. 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.
(dans le fichier plugin.xml)
<extension point="org.eclipse.help.toc"> <toc file="maindocs.html" 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>
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 TOC XML peuvent être traduits et la copie résultante (intitulés traduits) doit être placée dans le répertoire nl/<langue>/<pays> ou nl/<langue>. Les répertoires <langue> et <pays> correspondent aux deux lettres de code de langue et de pays utilisé 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>. Ce n'est que si un fichier se trouve dans nl/<langue>/<pays> que celui figurant dans nl/<langue> est utilisé. Le répertoire racine d'un 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 du système d'aide fournie avec la plateforme Eclipse supporte totalement le point d'extension toc.
Copyright (c) 2000, 2003 IBM Corporation and others.
All rights reserved. Ce programme et les produits qui l'accompagnent sont
fournis sous licence v1.0 associée à cette distribution et disponibles à
l'adresse suivante :
http://www.eclipse.org/legal/cpl-v10.html