Jump to: navigation, search

Authoring Eclipse Help Using 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.

More information about DocBook can be found at the following sites:

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.
  • A plugin that will hold the end use documentation.
  • An ANT build script that will publish the documentation.
  • Xalan 2.7.1 or Saxon 6.5 installed for processing the XSL Stylesheets. Note: XSL Tools 0.5 includes Xalan 2.7.1.

Optional:

  • 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.

Creating the DocBook Files

It is recommended that Chapter 23: Modular DocBook Files be followed when creating eclipse help. There are several benefits for doing this:

  • Allows content to be re-arranged.
  • Allows for easier maintenance
  • 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.

<?xml version="1.0"?>
<!-- 
*******************************************************************************
 * Copyright (c) 2008 Standards for Technology in Automotive Retail and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     David Carver - STAR - Extended existing eclipse.xsl file to produce valid
 *                           eclipse 3.3 plugin.xml with a manifest file.
 *******************************************************************************/
 
 -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	xmlns:ng="http://docbook.org/docbook-ng" xmlns:db="http://docbook.org/ns/docbook"
	xmlns:exsl="http://exslt.org/common" version="1.0"
	exclude-result-prefixes="exsl db ng">
	<xsl:import href="eclipse.xsl"/>
	<xsl:param name="manifest">1</xsl:param>
	<xsl:param name="create.plugin.xml">1</xsl:param>

	<xsl:template name="plugin.xml">
	    <xsl:if test="$create.plugin.xml = '1'">
			<xsl:call-template name="write.chunk">
				<xsl:with-param name="filename">
					<xsl:if test="$manifest.in.base.dir != 0">
						<xsl:value-of select="$base.dir" />
					</xsl:if>
					<xsl:value-of select="'plugin.xml'" />
				</xsl:with-param>
				<xsl:with-param name="method" select="'xml'" />
				<xsl:with-param name="encoding" select="'utf-8'" />
				<xsl:with-param name="indent" select="'yes'" />
				<xsl:with-param name="content">
					<xsl:choose>
						<xsl:when test="$manifest = '1'">
						   <plugin>
								<extension point="org.eclipse.help.toc">
									<toc file="toc.xml" primary="true" />
								</extension>
				 		   </plugin>
						</xsl:when>
						<xsl:otherwise>
							<plugin name="{$eclipse.plugin.name}" id="{$eclipse.plugin.id}"
								version="1.0" provider-name="{$eclipse.plugin.provider}">
								<extension point="org.eclipse.help.toc">
									<toc file="toc.xml" primary="true" />
								</extension>
							</plugin>
						</xsl:otherwise>
					</xsl:choose>
				</xsl:with-param>
			</xsl:call-template>	    
	    </xsl:if>
	</xsl:template>
</xsl:stylesheet>

CSS Doesn't Match Eclipse Style

The *.css files that come with the Docbook Stylesheets use a different style than Eclipse. You can specify a parameter for the eclipse help stylesheets to use to find the appropriate CSS stylesheet to use.