DocBook for Eclipse: Reusing DocBook's Stylesheets

DocBook is a popular tool for creating software documentation among developers. One reason for its success is the existence of the DocBook XSL stylesheets, which can be used to convert DocBook XML source into many target formats including HTML, XHTML, XSL-FO (for print), JavaHelp, HTML Help, and man pages. The stylesheets can be further customized to get other outputs as well. In this article I am going to show you how easily you can integrate DocBook documents into the Eclipse platform help system by reusing existing stylesheets.

Many help systems currently in use are built around HTML. The best known is probably Microsoft's HTML Help, dominant on the Windows platform. (You can easily find the HTML Help files on your Windows system: their suffix is .chm.) The corresponding technology in the Java world is JavaHelp, and there are many other formats besides. All of them share one common characteristic -- they are just a set of HTML files supplemented by auxiliary files containing the table of contents and other additional metadata.

These auxiliary files are usually XML or HTML-based, so we can use XSLT to generate them. If you have your documentation in DocBook and you want to feed it into the help system, the only thing you need is to extend the existing stylesheets to emit the auxiliary files together with a standard HTML output. That is even easier if you reuse some existing DocBook XSL stylesheet templates.

Inside Eclipse platform help

The whole Eclipse platform is developed around the idea of plugins. If you want to contribute your help documents to the Eclipse platform, you have to develop a new help plugin. The plugin is composed of the HTML and image files, the table of contents file in XML, and the manifest file.

The table of contents file describes the nested structure of topics which is displayed in the left pane of the help system. The manifest file (plugin.xml) is used for registering a new plugin inside the Eclipse platform.

The table of contents file is a simple tree-structured XML file containing the names of all topics and their subtopics, together with the filenames of corresponding HTML pages with help content. You can see sample table of contents file on Figure 1:

Figure 1. Table of contents and XML structure which describes it.

The manifest file is not very interesting, but the Eclipse platform needs it for recognizing the plugin and adding it into the global table of contents:

<?xml version="1.0" encoding="utf-8"?>
<plugin name="DocBook Online Help Sample" 
        id="com.example.help" 
        version="1.0" 
        provider-name="Example provider">
   <extension point="org.eclipse.help.toc">
      <toc file="toc.xml" primary="true"/>
   </extension>
</plugin>

If you want to use your own help inside the Eclipse platform, you must create a new directory inside the plugins directory named the same as the content of id attribute (com.example.help in our example). The manifest file, the table of contents file, and all HTML files must be placed inside this directory. After restarting the Eclipse platform our help will be part of the Eclipse help, and a new item it will be displayed in the global table of contents.

Pages: 1, 2

Next Page