Document a project using the Eclipse Help system

When you visit the Eclipse Help system (through aid > Assistance Contents), you actually start an embedded Apache Tomcat server. Then you open a Web browser based window and navigate to the appropriate page on the server (see Figure 1). The document also provides a collapsible index on the left and an HTML document on the right, ready to be searched (fortunately for the Apach Lucene search engine). With Tomcate, you can use not just HTML; for example, you can use JSPs to make your documents dynamically change (but we'll talk about one of the possible reasons to avoid doing so later).

Figure 1. Eclipse Help Sample

"Hello World" for document Plug-ins

The document is split into "books," and as long as you want, you can have as many books in one instance of the Help system. Each book is written as an Eclipse plug-in, but there are few things you can do about it. To write a sample plug-in, you will need a plugin.xml file to describe your plug-in, which is similar to Listing 1.

Listing 1. Plug-in definition

<plugin　name="Sample　Documentation　Plug-in"　id="com.ibm.sample.doc"
　　 version="1.0.0"　provider-name="IBM">
　　 <extension　point="org.eclipse.help.toc">
　　　 <toc　file="toc.xml"　primary="true"　/>
　　 </extension>
</plugin>

Depending on your project, modify the plug-in's name, ID, version, and provider-name to the appropriate values. Extension Point Org.eclipse.help.toc identifies this as a plug-in to the Help system. The Toc.xml file is referenced as the directory for this plug-in, which provides data for the hierarchical information in the left pane of the Eclipse Help window. Listing 2 is a sample file that contains similar content.

Listing 2. Catalog Definition

<toc　label="Sample　Documentation">
　　 <topic　label="My　Section"　href="mySection.html">
　　　　 <topic　label="Foo"　href="foo.html"/>
　　　　 <topic　label="Bar"　href="bar.html"/>
　　 </topic>
</toc>