Serveur d'aide et emplacements de fichiers

La plate-forme utilise son propre serveur de documentation pour fournir mes âges Web alimentant la documentation de votre plug-in. Un serveur personnalisé permet à la plate-forme de gérer indépendamment le contenu HTML dans un navigateur et d'offrir une prise en charge des plug-in. En tant que développeur de plug-in, la principale différence est que vous disposez d'un peu plus de souplesse de structuration de vos fichiers et de spécification de vos liens.

Un plug-in de documentation peut s'exécuter à partir d'un fichier jar ou être éclaté dans le répertoire du plug-in lors de l'installation. Un fichier jar de plug-in n'est pas développé dans un répertoire de plug-in lorsque la valeur de l'attribut unpack de l'élément plugin prend la valeur true dans le manifeste de la fonction. Dans ce type de plug-in, la documentation est compactée dans le fichier jar du plug-in, avec les autres fichiers du plug-in.

Dans les plug-in s'exécutant sous forme éclatée, la documentation peut être fournie dans un fichier zip, ce qui évite les problèmes liés à la présence d'un trop grand nombre de fichiers dans un répertoire de plug-in. Dans le plug-in exemple, nous créons un sous-répertoire nommé html. De la même façon, nous pourrions placer nos fichiers html dans un fichier zip nommé doc.zip. Ce fichier zip doit calquer la structure de fichiers sous le répertoire du plug-in.  Dans le cas présent, il doit contenir le sous-répertoire html et l'intégralité de son contenu.

Notez que pour les plug-in qui s'exécutent à partir d'un fichier jar, il n'est pas nécessaire que la documentation soit contenue aussi dans le fichier doc.zip et cette configuration du fichier doc.zip dans un fichier jar de plug-in non explosé n'est pas prise en charge par le système d'aide.

Lors de l'adaptation des noms de fichiers dans un plug-in s'exécutant sous forme éclatée, le serveur d'aide recherche les documents dans le fichier doc.zip avant de le faire dans le répertoire de plug-in.  Utilisé comme lien, l'argument dans href est censé être relatif au plug-in actuel.  Considérons le lien suivant :

   <topic label="Ref1" href="html/ref/ref1.html"/>

Le plug-in d'aide recherchera ce fichier comme suit :

Un lien qualifié complet peut être utilisé pour faire référence à un contenu sur le Web. 

   <topic label="Ref1" href="http://www.example.com/myReference.html"/>

Documents originaux et traduits

Le système d'aide de la plate-forme utilise le schéma de recherche du répertoire de langue nationale employé par le reste de la plate-forme pour localiser des fichiers traduits. Consultez la section Fichiers spécifiques à des environnements locaux pour en savoir plus sur cette structure de répertoire. Si vous utilisez un fichier doc.zip, vous devez produire un fichier doc.zip pour chaque ensemble de paramètres régionaux et le placer dans le répertoire correspondant (vous ne devez pas dupliquer la structure de répertoires de paramètres régionaux nl dans le fichier doc.zip).

Outre les répertoires spécifiques de l'environnement local, le système d'aide vérifie les répertoires du système de fenêtrage et du système d'exploitation lors de la recherche des ressources d'aide. La recherche est effectuée dans l'ordre suivant : sous-répertoires ws, os, nl, puis le répertoire d'installation du plug-in, jusqu'à ce que la ressource soit localisée. Les documents et autres ressources, tels que les images, qui diffèrent en fonction du système doivent être placés sous les répertoires ws ou os d'une plate-forme spécifique.

Référence croisée de plug-in

L'argument href peut également faire référence à un contenu provenant d'un autre plug-in. Cette opération est effectuée à l'aide d'une notation de référence croisée résolue par le serveur d'aide :

   <topic label="Ref1"
href="../"autre_id_plugin"/ref/ref1.html"/>

Par exemple, vous pouvez établir un lien à ce chapitre grâce à la section suivante :

   <topic label="Chapitre d'aide dans la documentation de la plate-forme" href="../org.eclipse.platform.doc.isv/guide/help.html"/>

Remarque : lorsque vous faites référence au contenu provenant d'un autre plug-in, assurez-vous d'utiliser l'ID du plug-in tel que déclaré dans le fichier plugin.xml , et non le nom du répertoire. Même s'ils sont souvent identiques dans la pratique, il est important de vérifier que vous employez bien l'ID.

Référencement du plug-in de produit.

Les informations commerciales sont généralement placées dans un plug-in définissant un produit, comme expliqué dans Définition d'un produit. Les ressources d'aide du plug-in de produit peuvent être référencées à partir de la table des matières ou des rubriques, au moyen d'un identificateur spécial "PRODUCT_PLUGIN" de l'ID de plug-in. Par exemple,

   href="../PRODUCT_PLUGIN/book.css"

fait référence à une feuille de style figurant dans le plug-in du produit en cours d'exécution.