Chaque plug-in contribuant aux fichiers d'aide fonctionne en général comme suit :
De manière optionnelle, un index d'aide peut être préétabli et enregistré en utilisant l'élément index
afin d'améliorer les performances de la première tentative de recherche. Il n'est possible d'enregistrer qu'un seul index par plug-in - plusieurs éléments index
auront pour conséquence un comportement non défini.
<!ELEMENT extension (toc* , index?)>
<!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="Fichier de concept" 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="rubrique dans un autre 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="Environnement de développement intégré" href="concepts/ciover.htm">
<topic label="Démarrage de l'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="Références" >
...
<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.
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(depuis la version 3.1) élément facultatif permettant la déclaration d'un index de recherche préétabli créé à partir de documents fournis par ce plug-in.
index/
, nl/ja/JP/index/
, nl/en/US/index/
etc.).(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"
/>
<index path=
"index/"
/>
</extension>
(dans le fichier maindocs.xml)
<toc label="Exemple de système d'aide">
<topic label="Introduction" href="intro.html"/>
<topic label="Tâches">
<topic label="Création d'un projet" href="tasks/task1.html">
<topic label="Création d'un projet Web" href="tasks/task11.html"/>
<topic label="Création d'un projet Java" href="tasks/task12.html"/>
</topic>
<link toc="task.xml" />
<topic label="Test d'un projet" href="tasks/taskn.html"/>
</topic>
<topic label="Exemples">
<topic label="Création d'un projet Java" href="samples/sample1.html">
<topic label="Lancement d'un assistant" href="samples/sample11.html"/>
<topic label="Définition d'options" href="samples/sample12.html"/>
<topic label="Fin de la création de projet" href="samples/sample13.html"/>
</topic>
<anchor id="samples" />
</topic>
</toc>
(dans le fichier tasks.xml)
<toc label="Génération d'un projet">
<topic label="Génération d'un projet" href="build/building.html">
<topic label="Génération d'un projet Web" href="build/web.html"/>
<topic label="Génération d'un projet Java" href="build/java.html"/>
</topic>
</toc>
(dans le fichier samples.xml)
<toc link_to="maindocs.xml#samples" label="Utilisation de l'outil de compilation">
<topic label="Exemple d'outil de compilation" href="compilesample/example.html">
<topic label="Etape 1" href="compilesample/step1.html"/>
<topic label="Etape 2" href="compilesample/step2.html"/>
<topic label="Etape 3" href="compilesample/step3.html"/>
<topic label="Etape 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 fichiers dans ces
répertoires avant d'aller par défaut dans le répertoire du plug-in.
Copyright (c) 2000, 2005 IBM Corporation and others.
All rights reserved. Ce programme et les produits associés sont
distribués sous licence publique Eclipse v1.0 et disponibles à
l'adresse suivante :
http://www.eclipse.org/legal/epl-v10.html