Les info-incrustations sont créées en associant l'ID de contexte
déclaré dans le code de l'interface graphique à la liste de liens à
des rubriques connexes dans l'aide en ligne. Ces associations
sont effectuées dans un fichier XML. Vous pouvez créer un nombre
de fichiers XML contenant des association d'incrustations pour chaque
plug-in. La description et les liens de chaque ID de contexte
figurent dans les éléments de <contexte> du fichier
XML. Chaque élément de contexte peut posséder un élément
facultatif de <description> utilisé pour décrire l'objet
de l'interface et plusieurs <rubriques> relatives à la
documentation en ligne.
<contexts> <context id="panic_button"> <description>This is the panic button.</description> <topic href="tasks/pushing_the_panic_button.htm" label="Pushing the panic button"/> <topic href="reference/panic_button.htm" label="Panic Button Reference"/> </context> ... </contexts>
Une fois les contextes décrits dans le ou les fichiers XML, vous pouvez faire référence aux fichiers de contexte dans le manifeste de votre plug-in. Dans l'exemple, l'ID de contexte n'est pas qualifié complet. Ceci est autorisé tant que le fichier de contexte est fourni dans le manifeste du plug-in ayant défini l'ID de contexte. En d'autres termes, l'ID de contexte est adapté à l'ID du plug-in ayant fourni le fichier XML.
Un plug-in fournit des fichiers de contexte à l'aide du point d'extension org.eclipse.help.contexts.
<extension point="org.eclipse.help.contexts"> <contexts name="myInfopops.xml" /> </extension>
Vous pouvez faire référence à des fichiers de contexte à partir d'autres plug-in en incluant l'attribut plugin. Vous pouvez ainsi regrouper toute votre documentation, y compris les info-incrustations, dans un seul plug-in et y faire référence à partir du plug-in de code de l'interface graphique ou tout autre plug-in relatif.
<extension point="org.eclipse.help.contexts"> <contexts name="myInfopops.xml" plugin="com.example.helpExample" /> </extension>
Vous disposez donc d'une grande souplesse d'organisation de vos info-incrustations dans un ou plusieurs fichiers figurant dans un ou plusieurs plug-in. L'important est que les ID de contexte dans les fichiers soient correctement résolus. Si vous ne qualifiez pas complètement un ID de contexte, vous devez fournit les fichiers XML dans le plug-in ayant déclaré les ID. Si vous utilisez des ID de contexte qualifiés complets dans votre fichier XML, vous bénéficierez d'une grande souplesse à l'emplacement de vos fichiers XML et du choix de plug-in apportant les contextes.
Pour toujours plus de souplesse d'action, vous pouvez fournir des info-incrustations pour le même ID de contexte provenant de divers plug-in. Cette opération est par exemple utile s'il existe plusieurs ensembles de plug-in de documentation installés ou non dans la configuration utilisateur. Chaque plug-in de documentation peut ainsi déclarer ses contexte de façon indépendante. L'utilisateur final verra le contenu fusionné pour tous les plug-ins ayant fourni des contextes à l'ID du widget.
L'ID de contexte qualifié complet d'un widget doit être employé car aucun plug-in de documentation n'a déclaré l'ID de contexte. Lorsque plusieurs plug-in fournissent des incrustations pour le même ID de contexte, le contenu défini dans le plug-in ayant déclaré le contexte (plug-in de l'interface graphique) s'affiche en premier. D'autres descriptions et liens sont ajoutés dans un ordre aléatoire.