DocBook for Eclipse: Reusing DocBook's Stylesheets
by Jirka Kosek
August 13, 2003
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.