The Eclipse help system is an extremely valuable tool that seems to intimidate new users.   This post is intended to cover some of the very basics about how to troubleshoot your plugins in an Eclipse help system.

Some basics first:

• A plugin is a folder or JAR file that provides instructions to Eclipse for how to process.
• Those instructions are given in the plugin.xml (extensions) and in the manifest file (prereqs, dependencies, etc).

Ensure the plugins are in the correct directory

While that might sound obvious, I have seen forum posts where the distinction between the workspace and plugins directories were causing problems. The workspace can be considered the directory where your source projects are stored for editing. That location is not processed by the Eclipse framework. You need to ensure that you store your plugins in the eclipse/plugins folder and in the correct format.

After you’ve checked that your plugins are in the correct location, verify that the contain the necessary files.

Plugins are formatted correctly and contain manifest/plugin.xml files

Open up your eclipse/plugins/my.plugin.folderorjar and check to ensure the plugin.xml is in the root of that folder or archive. You might optionally also have a META-INF/manifest.mf file.

Determine if Eclipse is picking up your plugin

Launch your help system or infocenter. If you are launching the help (Help->Help contents), you will want to open it with an external browser rather than the built-in browser. You can either change your preferences or you can just copy a TOC link address and paste it into a different browser. The port that the webserver for the Eclipse help system changes with each restart so you’ll need to determine that:

Your help URL will probably look something like http://127.0.0.1:3578/help/…. Once you have that, change the URL to http://127.0.0.1:xxxx/help/topic/my.plugin.folderorjar/plugin.xml.

If you get a topic not found or broken link

Then Eclipse did not pick up your plugin, which means something is likely wrong with your plugin.xml or manifest.

This could be a malformed XML file due to an XML markup error in your plugin.xml. Check that all tags are closed (</myclosetag>). Also, check for character encoding problems. XML is pretty strict when it comes to special characters and the most common problematic character is the ampersand (&). The ampersand in XML or XHTML (especially in links) should be represented in the file as: &amp;

Also, check that you are using the correct URL for your plugin. Eclipse uses the plugin ID in the path rather than the folder name or JAR file name.

If your plugin.xml file displays correctly

Then Eclipse found and registered your plugin. If this does not solve your problem, I am guessing you are wondering why your contents do not show up in the navigation. For your navigation file to be picked up, you have to register the TOC XML  file with the Eclipse org.eclipse.help.toc extension point in the plugin.xml.

If you want your toc to appear as a first level container, then you need to set primary=”true” for that TOC file:

<extension point=”org.eclipse.help.toc”>
<toc file=”toc.xml” primary=”true” />
</extension>

If you want this TOC file to be a child to another TOC, then you would set primary=”false” and link the maps together using a link_to (navref in Dita source) element or anchor/anchor_to (anchor & anchorref in Dita source).

You updated a plugin and the changes are not displayed

This is likely due to caching that Eclipse performs. You can either start Eclipse with the -clean parameter passed to the executable or you can manually clean the cache.

To manually clean the cache: stop Eclipse, find your Eclipse installation directory. Within the configuration subfolder, delete all of the contents except for the config.ini file and the org.eclipse.update directory.

Other issues?

Post your Eclipse help issues  as a comment and I’ll try to address them here also.