Contexts

Identifier: org.eclipse.help.contexts

Description: For defining context-sensitive help for an individual plug-in.

Configuration Markup:

<!ELEMENT contexts EMPTY>
<!ATTLIST contexts file CDATA #REQUIRED>

file - the name of the manifest file which contains the context-sensitive help documentation for this plug-in.

Configuration Markup for Contexts (this is what goes into the contexts manifest file):

<!ELEMENT contexts (context)* ) >

<!ELEMENT context (description?,topic*) >
<!ATTLIST context id ID #REQUIRED >

<!ELEMENT description (#PCDATA)>

    <!ELEMENT topic EMPTY >
    <!ATTLIST topic label CDATA #REQUIRED >
    <!ATTLIST topic href CDATA #IMPLIED >

The contexts manifest files provide all the information needed when context-sensitive help is requested by the user. The id is passed by the platform to identify the currently active context. The context definitions with matching IDs are then retrieved. The IContext object is then created by help system that contains descriptions and topics from all context definitions for a given ID. The description is to be displayed to the user, and related topics might be useful to the user for understanding the current context. The related topic are html files packaged in doc.zip, together with topics that are part of on line help.

Examples:

The following is an example of using the contexts extension point.

(in file plugin.xml)

   <extension point="org.eclipse.help.contexts">
      <contexts file="xyzContexts.xml"/>
   </extension>

(in file xyzContexts.xml)

    <contexts>
      <context id="generalContextId">
        <description> This is a sample F1 help string.</description>
        <topic href="contexts/RelatedContext1.html" label="Help Related Topic 1"/>
        <topic href="contexts/RelatedContext2.html" label="Help Related Topic 2"/>
      </context>
    </contexts>

Externalizing Strings

The Context XML files can be translated and the resulting copy (with translated descriptions labels) should be placed in nl/<language>/<country> or nl/<language> directory. The <language> and <country> stand for two letter language and country codes as used in locale codes. For example, Traditional Chinese translations should be placed in the nl/zh/TW directory. The nl/<language>/<country> directory has a higher priority than nl/<language>. Only if no file is found in the nl/<language>/<country>, the file residing in nl/<language> will be used. The the root directory of a plugin will be searched last.

The related topics contained in doc.zip can be localized by creating a doc.zip file with translated version of documents, and placing doc.zip in
nl/<language>/<country> or nl/<language> directory. The help system will look for the files under this directories before defaulting to plugin directory.

API Information: No code is required to use this extension point. All that is needed is to supply the appropriate manifest file(s) mentioned in the plugin.xml file.

Supplied Implementation: The default implementation of the help system UI supplied with the Eclipse platform fully supports the contexts extension point.