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à.

Contributions

Identificateur : org.eclipse.help.contributions

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 pour le point d'extension contributions :

    <!ELEMENT topics EMPTY>
    <!ATTLIST topics name CDATA #REQUIRED>

    <!ELEMENT actions EMPTY>
    <!ATTLIST actions name CDATA #REQUIRED>     <!ELEMENT infoset EMPTY>
    <!ATTLIST infoset name CDATA #REQUIRED> Marques de configuration pour les rubriques (elles correspondent à ce qui entre dans le fichier manifeste des rubriques) :

    <!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 :

En règle générale, une rubrique ne peut être insérée qu'une fois dans une vue d'informations. Elle peut cependant, être insérée dans plusieurs vues d'informations. Ceci signifie, que si une rubrique parente, et par ce fait sa sous-arborescence, est insérée dans un ensemble d'informations, aucun de ses enfants ne peut être réinséré dans la même vue d'informations. L'insertion crée à la base des partitions indivisibles pour une vue d'informations spécifiques.

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">
 <insert from="org.eclipse.help.examples.ex1.topLevelTopics"
   to="org.eclipse.help.examples.ex1.topicsView" as="child"/>
</actions>
(dans le fichier topicsActions.xml)
<actions infoview="org.eclipse.help.examples.ex1.topicsView">
 <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>
 
 

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


 

Composants non intégrés

On peut s'attendre à ce qu'un plug-in soit parfois installé seul et dans d'autres cas, comme partie d'un composant ou d'un produit plus grand. S'il s'agit d'un plug-in flottant librement, il est préférable de s'assurer que l'ensemble d'informations est visible. Lorsque les rubriques sont intégrées dans un réseau plus large, cela n'a probablement plus d'intérêt de faire paraître un manuel autonome. Pour supporter cette documentation intégrée librement ou non intégrée, un plug-in peut définir un ensemble d'informations et des actions associées, et définir la valeur "true" pour leur attribut autonome. Ceci a un effet sur l'exécution des actions d'insertion, uniquement lorsque les rubriques n'ont jamais été ajoutées ailleurs et affiche l'ensemble d'informations uniquement s'il n'est pas vide. La définition d'attributs autonomes sur des actions et des ensembles d'informations est utile pour fournir un scénario "permettant de tout lier" (catch all) lorsque la documentation ne peut pas être ajoutée à un ensemble d'informations connu, mais que la documentation du plug-in doit tout de même apparaître quelque part.

Externalisation des chaînes

Les fichiers plugin.xml externalisent leurs chaînes en remplaçant la chaîne par une clé (par exemple, %pluginName) et en créant dans le fichier plugin.properties une entrée de la forme suivante :
    pluginName = "Online Help Sample Plugin"
Les fichiers XML de contribution sont externalisés par une approche similaire. Pour externaliser <topic id="plainTasks" label="Plain Stuff">, remplacez son libellé par une clé %plainStuff. La rubrique ressemblera alors à :
    <topic id="plainTasks" label="%plainStuff">
Créez une entrée dans le fichier doc.properties contenant l'entrée suivante :
    plainStuff = Plain Stuff
Le système d'aide utilisera le fichier doc.properties lors de la recherche des chaînes externalisées par les contributions de l'aide en ligne.
 

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.

Copyright IBM Corp. 2000, 2001. Tous droits réservés.