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.

Eclipse documentation plug-ins can contain Java for creating dynamic content. You can extend the Eclipse help system by taking advantage of the org.eclipse.help.contentProducer extension point. The examples in this article demonstrate how to create a simple template that is parsed at run time to display dynamic text.

Skill level: intermediate

You can download the sample project that provides a simple framework for getting started with your own plug-in. If you have a basic level of Java programming experience or experience with other programming languages, you should be able to understand the concepts and examples.

Getting Started

This article assumes that you are using Eclipse 3.5 IDE for Java EE Developers (Galileo), but you can use other versions if they contain the Plugin Development Environment (PDE). The screenshots and steps might differ for other versions.

1. Extract the Eclipse ZIP file and launch the Eclipse executable.
2. Download the sample Eclipse project for a dynamic documentation plugin.
3. Import the zip file as an archived project: File->Import->Existing Projects into Workspace. Choose the Select archive file option and browse to the downloaded sample project zip file.
4. Click Finish and the project com.mrscripter.dynamicsample.doc will be added to your workspace and available for browsing within the Project Explorer view.

This sample provides a basic example of producing dynamic content using Java and Eclipse extension points.

Run the sample project

When you build the project, the compiled version of the plug-in will go into your eclipse/plugins directory so that you can test the dynamic content in the Eclipse help system.

1. Right-click the project folder in the Project Explorer view and select Export.
2. Select Plug-in Development->Deployable plug-ins and fragments

3. In the export destination area, choose the Directory option and select the directory that you previously extracted your Eclipse download. You should select the folder that contains your eclipse.exe file. The export wizard creates the output jar file in the plugins subfolder, for example: C:\my_dir\eclipse\plugins\com.mrscripter.dynamicsample.doc_1.0.0.jar.

4. Restart Eclipse to register this new plugin with the help system.

5. After Eclipse restarts, click Help->Help Contents to display the help system.

In the help system, you will see a top-level navigation entry titled “Dynamic Documentation Sample.” Each table of contents entry within this section links to what appears to be different files; however, the contentProducer extension designates the HelloDynamicWorld class as the responder for all content requests. Each table of contents link uses a different query string title parameter that the HelloDynamicWorld class uses to populate in the text for the title and body.

The following sections explain in more detail how the plug-in works. If you have a good understanding of Java, you might choose to explore the source code at your own pace.

If you modify the plug-in code, you must re-export and restart Eclipse each time that you would like to view the results of the change.

Dissecting the plugin

The plugin.xml file contains directions that allow the Eclipse runtime environment to understand how to process the files contained within a directory or JAR file that is in the plugins directory. These instructions take the form of extensions and extension points.

The org.eclipse.help.contentProducer extension point is the key to creating dynamic output. You add this extension point to your plugin.xml and register a content producer by specifying the name of the Java class that you want to control the dynamic processing:

<extension
   id="com.mrscripter.dynamicsample.doc"
   name="Dynamic documentation sample plugin"
   point="org.eclipse.help.contentProducer">
     <contentProducer producer="HelloDynamicWorld"/>
 </extension>

Content producer

In the sample project, the content producer extension points to the HelloDynamicWorld class. This class must extend the IHelpContentProducer interface and provide the required getInputStream method, which allows the plugin to send its content to the browser:

public InputStream getInputStream(String pluginID, String href, Locale locale)

You return an InputStream from your own Java class to Eclipse for display. An InputStream is a byte representation of your text.

The HelloDynamicWorld.java class contains two important methods: getInputStream and createMyDynamicOutput.

import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.File;
import java.io.FileReader;
import java.io.InputStream;
import java.net.URL;
import java.util.Locale;

import org.eclipse.core.runtime.FileLocator;
import org.eclipse.core.runtime.Path;
import org.eclipse.core.runtime.Platform;
import org.eclipse.help.IHelpContentProducer;
import org.osgi.framework.Bundle;

public class HelloDynamicWorld implements IHelpContentProducer{

    private static Bundle bundle = Platform.getBundle("com.mrscripter.dynamicsample.doc");
    private static Path path = new Path("template/template.html");
    private static URL url = Platform.find(bundle, path);
    private static File templateFile=null;
    private static StringBuffer templateBuffer=null;

	public InputStream getInputStream(String pluginID, String href, Locale locale) {
		InputStream is = null;
		String title = QueryStringHelper.getValue(href,"title");
	      try{
	          return createMyDynamicOutput(href,title);
	      }
	      catch(Exception e){
	          e.printStackTrace();
	      }
	      return is;
	}

	private InputStream createMyDynamicOutput(String href, String title) throws Exception{
	    try{
        	templateBuffer = new StringBuffer();
        	templateFile = new File(FileLocator.toFileURL(url).getFile());
                BufferedReader in = new BufferedReader(new FileReader(templateFile));
                String s=null;
                while((s = in.readLine()) != null){
            	    templateBuffer.append(s);
                }
            }
            catch(Exception e){
                System.out.println(e.getMessage());
                e.printStackTrace();
            }

	    String tempOut = templateBuffer.toString().replaceAll("%TITLE%", title);
	    return new ByteArrayInputStream(tempOut.toString().getBytes("UTF-8"));
	}
}

The typical HelloWorld application is not dynamic so the sample project adds a little more code to demonstrate changing the output based on some simple input.  This sample looks for a query string parameter named “title” and gets the value of the parameter and then inserts that value into a template response. The result is returned as an InputStream for passing back to Eclipse for further processing prior to rendering.

The URL that is called is http://…../help/topic/com.mrscripter.dynamicsample.doc/something.html?title=Testing+A+Title. The content producer class intercepts all URL requests for the plug-in. You can change something.html to any name and it will still work as long as you provide the title in the querystring.

If you request a URL with an extension other than .html, some browsers won’t display the result as HTML but rather as plain text because our sample does not adjust the response type in the response header.

Template

The sample project includes a simple template file that uses basic %variable% replacement. The getInputStream method uses the QueryStringHelper class to read the title parameter from the querystring and pass the title parameter to the createMyDynamicOutput method. The createMyDynamicOutput method reads the template file to a string buffer, templateBuffer. All instances of %title% within the template/template.html file are replaced title parameter.  The string is converted into a UTF-8 encoded ByeArrayInputStream and returned to Eclipse for display.

Expanding on the HelloDynamicWorld sample

The sample project demonstrates how documentation plug-s that run within the context of the Eclipse help system or in the Eclipse information center mode can response to dynamic input from a user. The org.eclipse.help.contentProducer extension point provides the ability to create a more dynamic and response help system. New content producers could include remote content from feed, local content or external information. For example, you could integrate your online Knowledge base contents directly into your help contents to provide in-context support documents.

Ideas for implementations

For corporations that author their help content in DITA-XM, instead of using a build framework such as the DITA Open Toolkit, they could instead render DITA content dynamically on-the-fly and produce targeted content based on metadata about a users configuration or environment to create custom documentation.

Using the contentProducer as a proxy, you can eliminate the cross-domain communication limitation that Javascript frameworks face. You could query and retrieve remote content and display within your help system. You could generate a dynamic XML table of contents based on content hosted on your own website, but users would be able to see it locally on their workstations. This approach can enable a push model for some content.

Links can be painful to deal with in help systems especially in multi-author environments or with larger numbers of topics.  Maintaining links over time can also be difficult. If you are authoring your help in DITA and using relationship tables, you might find they aren’t as easy to maintain as many claim. The Eclipse help system can make link validation difficult due to its frameset and difficulty for most link checkers to find all of your pages.

My goal in writing this is to find a link checker that meets the following requirements:

• Recursive link checking.
  Need to be able to specify how deep the program should follow links to discover and validate all links. Ideally, could limit this recursion to the same site.
• Reports that can be saved and distributed
  Share results with writing teams for resolving and fixing links.
• Customization of settings, especially links and link patterns to ignore.
  Link checkers often have false positives for various reasons and it is helpful to be able to filter and hide these “errors.”
• Bonus: Works with dynamic pages and JavaScript.
  The newest versions of the Eclipse Help System rely soley on JavaScript to generate the navigation tree. Ideally, a link checker could work with the same view that we see. Often, link checkers are just verifying the response codes in the headers rather than actually examining the page for dynamically generated content and links.
• Bonus: Command line support.
  Integration into a post-build process or for otherwise automating will likely require a command line interface.

I’ve long used ParaSoft WebKing for accessibility and link checking for projects within IBM but it can be quite difficult to configure to meet the goals above.  I’ve also tried a few other applications including LinkChecker, W3C Link Checker, and Xenu. Xenu works pretty well for discovering broken links to any kind of resources, including images, stylesheets, and JavaScripts.

Robots.txt

Many link checkers try to follow the rules  that websites define in their robots.txt file. These files instruct search engines and other spiders how they are to behave when snooping around a website. I ran into this problem when trying to test my IBM information center by using the LinkChecker from SourceForge and W3C Link Checker.

My solution was to run the link checking program against my test infocenter rather than our production server. This eliminated the W3C link checker from my possible tools because it cannot access my intranet. Xenu does not follow the robots.txt instructions.

What URL to use?

You might also assume like me that just pointing your link checker at the top level URL should work just fine. I’ve had mixed results trying to use http://publib.boulder.ibm.com/infocenter/idm/v2r2/index.jsp as my starting page.  Your link checker might also have a difficult time with the frames also.

I suggest experimenting by also running it against the TOC that is used for non-JavaScript enabled browsers, which for my IC is http://publib.boulder.ibm.com/infocenter/idm/v2r2/basic/tocView.jsp. This page does not use the standard JavaScript based navigation tree so a link checker should have an easier time with it.  If you set your link checker to recursively dig down enough levels the navigation starting point should work pretty and even better if you provide plenty of cross-linking within your files.

No broken links?

There is an Eclipse bug about certain versions not returning a proper 404 response status.  If you are experiencing this same problem, you might need to try testing with a different version of Eclipse. I’ll try to track down this bug # and put it in here.

Checking the links of my infocenter

I installed the latest version of Xenu, which had recently been updated. I pointed Xenu to http://publib.boulder.ibm.com/infocenter/idm/v2r2/index.jsp and left all of the default options.  This infocenter contains approximately 17,000 topics for all languages and are owned by some 12 or more contributing authors.

Xenu is still running but it looks as if it is properly crawling the site and finding problems:

Starting to see plenty of red showing up and quite a bit more than I was expecting so I expect I’ll be sending this report out to our team.  The total number of pages and files to test were discovered thus far is over 10k so the link checker seems to be working correctly.

When Xenu finally finished, I generated a report (Hit Cancel on the FTP screen) and it is formatted for viewing from a couple different perspectives.  The HTML markup behind the scenes is very basic, I’ll have to investigate how to parse it to show broken links by plugin for being able to send the reports to the correct people but that might be a later post.

Here’s a quick screen cap showing one easily identifiable broken link:

Other tools?

I’ve listed a few here from my own experiences but would love to hear from others.