Infopops are described by associating the context id declared in the UI code
with a description and list of links to related topics in the online help.
These associations are made inside an XML file. You can create any number
of XML files containing infopop associations for each plug-in. The
description and links for each context id is made inside <context>
elements in the XML file. Each context element can have an optional <description>
element which is used to describe the UI object and any number of <topic>
elements which link to the on-line documentation.
<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>
Once the contexts have been described in the XML file (or files), you are ready to refer to the context files in your plug-in manifest. Note that the context id is not fully qualified above. This is allowed, as long as the context file is contributed in the manifest of the plug-in that defined the context id. In other words, the context id is resolved to the id of the plug-in that contributed the XML file.
A plug-in contributes context files using the org.eclipse.help.contexts extension point.
<extension point="org.eclipse.help.contexts"> <contexts name="myInfopops.xml" /> </extension>
You can reference context files from other plug-ins by including the plugin attribute. This allows you to group all of your documentation, including infopops, in one plug-in, and refer to it from the UI code plug-in or some other related plug-in.
<extension point="org.eclipse.help.contexts"> <contexts name="myInfopops.xml" plugin="com.example.helpExample" /> </extension>
As you can see, you have a lot of flexibility in organizing your infopops into one or more files contained in one or more plug-ins. The main consideration is that the context ids in the files resolve correctly. If you do not fully qualify a context id, then you must contribute the context XML files in the plug-in that declared the context ids. If you use fully qualified context ids in your context XML file, then you have complete flexibility in the location of your XML files and which plug-in contributes the contexts.
Another level of flexibility is the ability to contribute infopops for the same context id from different plug-ins. This is useful, for example, if there are different sets of documentation plug-ins that may or may not be installed in a user's configuration. This allows each documentation plug-in to declare its contexts independently. The end user will see the merged infopop content for all plug-ins that contributed contexts for the widget's id.
Note that the fully qualified context id for the widget must be used, since none of the documentation plug-ins declared the context id. When multiple plug-ins contribute infopops for the same context ID, the content defined in the plug-in that declared the context (the UI plug-in) is shown first. Additional descriptions and links are appended in no guaranteed order.