Remarque : Le système d'aide est toujours en cours de développement et il faut s'attendre à ce qu'il soit modifié d'ici son achèvement. Il est diffusé à ce stade pour solliciter les commentaires des premiers utilisateurs, tout en signalant que les détails des mécanismes de contribution peuvent considérablement changer d'ici là. |
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 :
<!ELEMENT topics EMPTY>
<!ATTLIST topics name CDATA #REQUIRED>
<!ELEMENT topics (topic)* ) >
<!ATTLIST topics id ID #REQUIRED >
<!ELEMENT topic (topic)* >
<!ATTLIST topic id ID #IMPLIED >
<!ATTLIST topic label CDATA #REQUIRED >
<!ATTLIST topic href CDATA #IMPLIED
>
Marques de configuration pour les ensembles d'informations (elles correspondent à ce qui entre dans le fichier manifeste des ensembles d'informations) :
<!ELEMENT infoset (infoview)* >
<!ATTLIST infoset id ID
#REQUIRED >
<!ATTLIST infoset label CDATA
#REQUIRED >
<!ATTLIST infoset href CDATA
#IMPLIED >
<!ATTLIST infoset standalone
(false|true) false #IMPLIED >
<!ELEMENT infoview EMPTY>
<!ATTLIST infoview id ID #REQUIRED >
<!ATTLIST infoview label CDATA #IMPLIED >
Marques de configuration pour les actions d'insertion (elles correspondent à ce qui entre dans le fichier manifeste des actions) :
<!ELEMENT actions (insert)* >
<!ATTLIST actions infoview CDATA #REQUIRED
>
<!ATTLIST actions standalone (true | false)
false #IMPLIED >
<!ELEMENT insert (insert) >
<!ATTLIST insert from CDATA #REQUIRED >
<!ATTLIST insert to CDATA #REQUIRED >
<!ATTLIST insert as (child
| first-child | last-child | prev-sib | next-sib) "child" >
<!ATTLIST insert label CDATA #IMPLIED >
En règle générale, un plug-in qui doit fournir une aide en ligne, définit ses propres manifestes de rubriques, ainsi que les manifestes d'actions nécessaires pour lier les rubriques aux emplacements corrects. En fin de compte, le système d'aide est configuré pour être lancé en fonction de certaines actions et l'ID de l'ensemble des informations peut être utilisé à cette fin.
Il existe quatre types d'éléments XML utilisables par un plug-in : la rubrique, l'ensemble d'informations, les actions et les éléments d'insertion.
L'élément rubrique
En ce qui concerne les rubriques, elles sont mises à contribution en tant qu'élément conteneur de rubriques. Ces dernières peuvent avoir une structure hiérarchique et figurer dans une liste à plat. Un manifeste de rubriques se visualise comme une source de données destinée à une imbrication ultérieure et à une organisation des rubriques en réseau intégré, avec différentes perspectives de vue. De plus, les rubriques peuvent être activées en spécifiant leur ID, mais l'une d'elles peut également agir sur un groupe de rubriques en spécifiant l'ID de l'élément rubrique ou des rubriques concernées. Lors de la liaison des rubriques aux vues ou à d'autres rubriques, la structure définie dans le manifeste des rubriques est maintenue (restant sujette aux modifications dues aux actions d'insertion).
L'élément de rubrique est le "cheval de labour" de la structure de navigation. Il existe trois utilisations typiques de l'élément de rubrique :
1. Fournir une liaison à un fichier de documentation, un fichier HTML en général.
2. Agir en tant que conteneur pour d'autres rubriques, dans le même manifeste ou dans un autre.
3. Fournir un point d'insertion à d'autres rubriques, 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
L'utilisation suivante la plus courante d'une rubrique est de servir de conteneur à d'autres rubriques. La rubrique du conteneur elle-même peut toujours faire référence à un fichier spécifique également.
<topic label="Integrated Development Environment" href="concepts/ciover.htm"
>
<topic label="Starting the IDE" href="concepts/blah.htm"
/>
...
</topic>
3. Les rubriques en tant que points d'insertion
Les rubriques peuvent être utilisées comme points d'insertion. Elles fournissent un emplacement logique à d'autres rubriques pour tenter une fusion. Pour pouvoir agir en tant que point d'insertion, la rubrique doit avoir un attribut d'ID.
L'élément d'ensemble d'informations
Un ensemble d'informations est un point d'entrée dans un support de documentation. Il peut être considéré comme une collection de vues.
Les vues sont destinées à fournir des regroupements sémantiques de haut niveau dans une documentation. Elles sont définies à l'aide de l'élément infoview (vue d'informations) défini dans un ensemble d'informations. Une équipe travaillant sur la documentation peut utiliser une vue pour fournir des sections de guide d'initiation, tâches et références (ou d'autres vues définies par l'équipe produit). La plateforme ne spécifie pas les sections réelles, seulement le mécanisme permettant de les définir.
Par exemple, une "vue des tâches" définie peut être une fusion de toutes les rubriques d'une perspective "comment faire quelque chose". Une autre vue, "vue de composant", peut être également définie et être une arborescence de rubriques affichant tous les composants et leur documentation.
L'élément de la vue d'informations représente un conteneur pour les rubriques qui peuvent être "partagées" par des plug-ins. Il s'agit d'une perspective de la documentation complète. Il peut y avoir des moments où un certain nombre de plug-ins différents contribuent au même composant de documentation logique. Cet élément s'assure qu'au cours d'une "vue de composants", ils fusionnent correctement afin de former une vue cohérente.
L'élément d'actions
Le manifeste d'actions contient des actions de script devant être exécutées sur des rubriques et des vues. Généralement, il n'y a qu'une seule sorte d'action, l'insertion, qui est utilisée pour écrire les rubriques et les vues dans un support d'informations intégré, avec des vues multiples.
Les actions sont des actions structurelles (insert) et de ce fait, s'appliquent à une certaine vue d'informations (infoview). Ainsi, toutes les actions d'insertion contenues dans un manifeste génèrent la hiérarchie des rubriques dans une vue d'informations.
L'élément d'insertion "insert"
L'une des parties les plus compliquées de la navigation par composant est de créer une structure d'informations intégrée avec un flot de navigation continu. Pour ce faire, nous devons utiliser un mécanisme permettant de publier des points d'insertion, choisir le point d'insertion que nous souhaitons utiliser et indiquer où les rubriques doivent être insérées (parent, enfant, avant, après).
Les points d'insertion peuvent être des rubriques ou des vues. Une rubrique indique sa volonté d'être un point d'insertion en fournissant un ID. Les vues doivent avoir un ID. Seuls les ID complets qualifiés peuvent être utilisés comme références. Par exemple, l'ID complet qualifié de la rubrique <topic id="concepts" label="concepts"> dans le plug-in org.eclipse.help.examples.ex1 est org.eclipse.help.examples.ex1.concepts.
Comme les points d'insertion se trouvent généralement dans d'autres plug-ins, et qu'ils peuvent ne pas être installés, l'un d'eux peut spécifier un autre point d'insertion. Par défaut, si aucun des choix n'aboutit, la rubrique reste sous sa hiérarchie de composants. L'attribut "to" spécifie le point d'insertion cible. La rubrique spécifiée par l'attribut "from" est la rubrique insérée. Ci-dessous figurent plusieurs possibilités d'insertion d'une rubrique, spécifiées comme suit :
D'autres options d'insertion sont fournies et sont exécutées lorsque les précédentes ne le peuvent pas. Les sous-éléments d'insertion imbriqués de l'élément d'insertion fournissent ces alternatives. Cela peut être considéré comme un mécanisme de "rétromigration" dans lequel lorsqu'une action d'insertion échoue, l'action d'insertion imbriquée est exécutée.
Dès lors que le point d'insertion choisi en premier est satisfait, les autres points d'insertion sont ignorés.
Exemples :
L'exemple ci-dessous montre l'utilisation du point d'extension contributions. Présumons que l'ID du plug-in concerné est "org.eclipse.help.examples.ex1". (Cet exemple doit être considéré comme un exemple général. Notez que la même hiérarchie de documentation, résultant de tous les fichiers de contribution suivants, pourrait être également créée avec des combinaisons de rubriques et de fichiers d'actions différentes.)
(dans le fichier plugin.xml)
<!-- Use the Help System contribution extension
point to define Infosets, topics, -->
<!-- and actions contribution files. For clarity,
the extension point is used -->
<!-- twice, once to define the Infoset and it's
view, and another to define the -->
<!-- Topics and their associated actions.
-->
<extension point="org.eclipse.help.contributions">
<infoset name="infoset.xml"/>
</extension>
<extension point="org.eclipse.help.contributions">
<topics name="infosetTopics.xml"/>
<actions name="infosetActions.xml"/>
</extension>
<!-- Configure the help contribution for this plugin
-->
<!-- This part should be in a documentation plugin
-->
<extension point="org.eclipse.help.contributions">
<topics name="topics.xml"/>
<actions name="topicsActions.xml"
/>
</extension>
(dans le fichier infoset.xml)
<!-- Define the Infoset, and any views it has. -->
<infoset id="ex1InfosetId" label="%help_system_example">
<infoview id="topicsView" label="%topics"/>
</infoset>
(dans le fichier infosetTopics.xml)
<!-- Now define a "container" topic that holds your general topics. This makes it -->
<!-- easier to quickly insert all these general topics under the view in the -->
<!-- Infoset. -->
<topics id="topLevelTopics">
<topic id="concepts" label="%concepts"/>
<topic id="tasks" label="%tasks"/>
<topic id="references" label="%references"/>
<topic id="samples" label="%samples"/>
</topics>
Définir des rubriques contenues dans les rubriques générales ci-dessus :
(dans le fichier topics.xml)
<topics id="topics">
<topic id="aConceptId" label="%introduction" href="concepts/concept.html"/>
<topic id="aTaskId" label="%creating_a_project" href="tasks/task1.html">
<topic id="aSubTaskId1" label="%creating_a_web_project" href="tasks/task2.html"/>
<topic id="aSubTaskId2" label="%creating_a_java_project" href="tasks/task3.html"/>
</topic>
<topic id="aReferenceId" label="%interfaces" href="ref/ref1.html"/>
<topic id="aSampleId" label="%help_system_sample" href="MissingFile.html"/>
</topics>
A présent, définir les actions d'insertion requises pour créer la hiérarchie de la documentation :
(dans le fichier infosetActions.xml)
<actions infoview="org.eclipse.help.examples.ex1.topicsView">(dans le fichier topicsActions.xml)
<insert from="org.eclipse.help.examples.ex1.topLevelTopics"
to="org.eclipse.help.examples.ex1.topicsView" as="child"/>
</actions>
<actions infoview="org.eclipse.help.examples.ex1.topicsView">La hiérarchie de la documentation résultante dans le plan de travail Eclipse est le suivant :
<insert from="org.eclipse.help.examples.ex1.aConceptId"
to="org.eclipse.help.examples.ex1.concepts" as="child"/><insert from="org.eclipse.help.examples.ex1.aTaskId"
to="org.eclipse.help.examples.ex1.tasks" as="child"/><insert from="org.eclipse.help.examples.ex1.aReferenceId"
to="org.eclipse.help.examples.ex1.references" as="child"/><insert from="org.eclipse.help.examples.ex1.aSampleId"
to="org.eclipse.help.examples.ex1.samples" as="child"/>
</actions>
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 optionnelle par défaut de l'interface utilisateur du système d'aide fournie avec la plateforme Eclipse supporte le point d'extension contributions.