Building an easy-to-use and searchable help document

Level: Getting Started

Arthur Barr software engineer, IBM 2004 March

There is a very powerful IDE's Eclipse platform with its own help system, which is based on an XML directory table that references an HTML file. It is aware that you don't have to write the Eclipse plugin to use it. Any project can use a simplified version of the platform to provide professional, easy-to-use and searchable documents. This documentation system has been successfully applied to many IBM projects, including projects like WebSphere Application Server.

When you visit the Eclipse Help System (via help> Help Contents), you actually launched an embedded Apache Tomcat server. Then open a web browser-based window to locate the appropriate page on the server (see Figure 1). The document also provides a foldable index on the left side, and the right side is an HTML document and can be searched at any time (fortunately with APACH Lucene search engine). Due to TOMCATE, you don't just use HTML; for example, you can use JSP to make your document to dynamically change (but we will discuss one of the possible causes of avoiding this).

Figure 1. Eclipse Help Example

The "Hello World" document for the document plug-in is split as "book", as long as you wish, you can have any books in one instance of the help system. Each book is written as an Eclipse plugin, but it is very much in this step. To write a sample plugin, you will need a plugin.xml file to describe your plugin, and its content is similar to Listing 1.

Listing 1. Plug-in definition

Version = "1.0.0" provider-name = "ibm">

Depending on your project, modify the Name, ID, Version, and Provider-Name of the plugin to the appropriate value. Extended Org.eclipse.Help.toc will identify this as a plugin for the help system. The Toc.xml file is referenced, as the directory of this plugin; this file will provide data for the hierarchical information in the left pane of the Eclipse Help window. Listing 2 is an example file containing similar content.

Listing 2. Directory definition

The packaging plug-in is in the final document, each of the subject elements behaves as an entry in the navigation list. These topics can nested (they can contain more topics), each pointing to an HTML or JSP file. When you have finished this step, all you need to do is to pack all the contents in the structure shown in Figure 2 (note that the plugin directory name matches the plugin attribute ID and Version defined in PLUGIN.XML). Figure 2. Plug-in directory structure

For convenience, in order to compress file size, Eclipse allows you to store the actual file (HTML file) in a ZIP file called Doc.zip, so you can use the directory structure shown in Figure 3.

Figure 3. Another plugin directory structure

To view documentation, the easiest way to test your plugin is to drag the entire directory (like above) to the plug-in directory that has already installed the Eclipse platform, then starts Eclipse and select Help> Help Contents. You will get a help window that adds your plugin (similar to that in Figure 1).

It is of course good to use IDE to test, but in order to use without IDE, the document needs to be more easy, so we really want to run a process in the background, let us connect to it in your browser. This method of operation is referred to as infocenter (see Figure 4). InfoCenter processes (basically Apache Tomcat) are included in the Eclipse Help System document (see links in this article). Note that there are some instructions to simplify the Eclipse system so that you just meet your needs.

Figure 4. Operating infocenter

Handling a large directory If your project has multiple people involved, or have a lot of documentation, then update a single directory file (Toc.xml) will become unrealistic. To change this situation you can add a LINK element to the topics in the primary TOC.XML file (see Example of Listing 3).

Listing 3. Directory definition

BAR-TOC.XML file is another directory, the format should be identical to any other Toc.xml file. When document is browsed, use this method and simply contain additional topic elements.

Generating a separate document set, if you don't mind if you need to release 20 MB of extra code, use the Eclipse help the system is of course good, but this is unrealistic. Install an Infocenter on the central server, allowing people to access remotely. People can make full use of all the features of the Eclipse help system (such as search), but those who cannot be connected are still helpless. Therefore, in addition to using InfoCenter on the host, it is necessary to include ordinary HTML in a downloadable package. As long as you do not use any server-side technology, such as JSP, you can easily generate an HTML directory to replace the XML directory used by Eclipse. That's why we have to use XSLT. XSLT (Extensible Stylesheet Language Transform) is a technique that transfers XML format into other formats, such as XHTML (a more stringent XML version of HTML). XSLT provides a rich and powerful language to complete the conversion, it is the theme of many books and articles, so we are no longer detailed here. Listing 4 gives an example of simply conversion of Toc.xml files, presented the entry as a nested HTML list. Note that this particular conversion is created for the content of all document sets, which may not be practical when the file is large. So, if you have split your directory into multiple files, this XSLT will be invalid.

Listing 4. Sample XSLT for generating html directories

Version = "1.1"

XMLns: XSL = "http://www.w3.org/1999/xsl/transform">

• With an XSLT processor, such as Apache Xalan, use the previous XSLT to process the Toc.xml file, generate a HTML file as shown in Figure 5 when viewing in the browser:

  Figure 5. Generated INDEX.html

  End language Use the Eclipse help system to easily develop a professional appearance and can search for documents. If you don't need an independent document set, you don't even need to ignite XSLT; you only need to write two simple XML files to enjoy the document. let's start.

  Reference

  Download the source code used herein. Find more information about the Eclipse Help item on the Eclipse Help Project Web site. Read will help the system installed as an information center. Note that these instructions apply to the Eclipse 2.1 platform. Learn XSLT in Doug Tidwell's excellent tutorial "Transforming XML Document" (DeveloperWorks, May 2000). Download Apache Xalan XSLT processors (with Java and C versions, but if you are using Java 2 v1.4 runtime environment, the standard has come with an XSLT processor). Check IBM WebSphere Application Server V5.1 InfoCenter how to help the system run on a big project. Find more articles prepared for Eclipse users at the developerWorks Open Source Project Zone. Also can learn the latest Eclipse technology download in AlphaWorks.

  About the author Arthur Barr is a software engineer in the IBM HURSLE development laboratory of the UK. He has applied this article to the Business Integration for Games project, which should be the project he is currently working. You can contact Arthur via Arthur.Barr at Uk.ibm.com.