Target Formats

Since all content is stored within Eclipsepedia which use MediaWiki text format for structure and styling, it is recommended that projects leverage Mylyn WikiText for the publishing process. Mylyn WikiText allows for the export of mediawiki files into a variety of ouput formats. The sections that follow describe these formats and steps to produce the content in more detail.

DocBook

Introduction to DocBook

This page contains information about how to use DocBook for authoring Eclipse Help. If you are using DocBook in Eclipse and have questions, comments, etc., about integration, send a note to the WTP Incubator Dev List or contact me, David Carver.

DocBook is an XML format designed for technical documentation. This includes books, articles, and help. XSL Tools uses docbook for it's user documentation format. It allows the writer to focus on the content of the book, and not how it looks. This seperation of content from presentation allows the information to be presented in a wide variety of formats, including the Eclipse Help system.

The DocBook Project - the home for the XSL Stylsheets for transform XML. Including an eclipse help stylesheet.

The DocBook Project

The DocBook Project provides a very popular and highly customizable set of DSSL and XSLT stylesheets for working with and generating DocBook content into a wide variety of formats. The project has been on going since 1999 and the most current version of the XSL Stylesheet are 1.74, June 2008. This project is continually being improved and patches applied. The stylesheets are free available for download. Note that it does make use of several other open source releated projects, so it may be necessary to check all licensing terms to make sure they meet your specific needs.

This HowTo will assume that the XSL Stylesheets are being used.

Getting Started

You'll need the following in your workspace:

The XSL Stylesheets from the DocBook Project. Create a Project for these and then import the ZIP file.

XSL Tools 0.5 or greater installed to allow for easy Launching and Testing of the process. XSL Tools also includes an XInclude ant task for helping to merge multiple docbook files into one complete package.

Individual chapters can be previewed and worked on seperately from the main content.

Allows more than one person to work on a document.

The XSL Tools org.eclipse.wst.xsl.doc plugin can be viewed as an example.

Eclipse XSL Stylesheet

The Eclipse Platform Help System section in Chapter 25, outlines the basics of generating Eclipse Help with DocBook files. The stylesheet included with Docbook is designed for pre-eclipse 3.0. It uses some deprecated ways of generating the appropriate plugin.xml and toc.xml files need. The stylesheet below can be used with the one included by the DocBook Project to add eclipse 3.0 and greater support.

manifest - The default value for this is 1, which means that it should generate a Manifest file for the documentation plugin. Set this to 0 to turn this feature off.

create.plugin.xml - The default value for this is 1, which means that the plugin.xml file should be generated and the appropriate toc.xml information added to it.

If you have created a plugin project already, and set up the initial toc.xml entry in the plugin.xml file, then you can turn this option off, and it will generate only the Toc.xml file that contains a link to the appropriate html entries.

ANT Build Script

As mentioned, you can use XSL Tools to help test individual chapters and see what they will look like. Do this by using the HTML stylesheets: docbook.xsl or chunk.xsl. It is recommended that the chunk.xsl stylesheets be used, and the base eclipse.xsl stylesheet imports this already. This splits the content into multiple html output files.

For generating the eclipse help plugin files, it is recommended to setup an ANT build script, and also use the XSL Tools xsl.xinclude ant task for merging the contents. The XSL Tools documentation generator build.xml looks like the following:

This script can be run independent of the workspace it was created and should be able to be run without change in a headless build. No system environment variables are used to gather information. The build script will output it's information into a directory called HTML in the current plugin. The only variables that may need to be updated are the $docbookdir and $docbooksource to indicate where the docbook files are stored.

The main processing is done in the create-doc, the xinclude resolutions are done in the merge target. It will generate table of contents for Book, Chapter, and Section elements. Running the build script will update the toc.xml in the plugin's root directory, and link automatically to the generated html documentation.

CSS Doesn't Match Eclipse Style

The default stylesheet and formatting for the Eclipse Help generated by Docbook doesn't integrate well with the eclipse help system. Review Using CSS for more information on how to customize the look and feel.