## Describing and packaging context-sensitive help content

Content-sensitive help is 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 context help 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.

Since 3.1, context elements can optionally override the default title used to present the context help information in the Help view.

    <contexts>
    	<context id="panic_button" title="Panic Button Title">
    		<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="myContextHelp.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 content-sensitive help, 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="myContextHelp.xml" plugin="com.example.helpExample"  />
       </extension>

As you can see, you have a lot of flexibility in organizing your contexts 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.

#### Context-sensitive help from multiple plug-ins

Another level of flexibility is the ability to contribute context-sensitive help 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 context-sensitive help 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 context-sensitive help 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.

Dynamic content

Dynamic content is available for the context help in the form of filters on context help topic links. For example, you may want a topic link to show up in the context help only when running on a specific operating system.