Creating a Stand Alone Eclipse Infocenter for DITA

The DITA Open Toolkit offers an actively maintained output for Eclipse Help. One of the features of this help system is that it can be deployed as a stand alone help server.

This feature allows any valid DITA content to be served by a sophisticated and well maintained help system, that is free for personal and commercial use. Eclipse Help rivals commercial products in its stability and feature set.

The only cost (so far) that I have seen in deploying this system is that it is designed for Eclipse and Java developers. Setup of the system is not obvious for someone who lives and works outside of the Eclipse universe, due to the Eclipse documentation, which is oriented towards program development. Actual setup for documentation purposes is not difficult.

The purpose of this document is to minimize the pain of Eclipse Help deployment for those wishing to use the DITA Eclipse Help transformation type.

This document is based on deployment of the current Eclipse stable release, 3.3.2, from February 21, 2008. If you use a different release of Eclipse, then file name references given in the following examples may not match your installation.

The Eclipse Platform Runtime Binary Package

The Eclipse Platform Runtime Binary package is available from the

Eclipse Download Page (on that page, click the link for the most recent release, then scroll down to find the Platform Runtime Binary package for your OS)

Download the Platform Runtime Binary package that is appropriate for your platform.

Be sure to download the Platform Runtime Binary package, instead of the entire Eclipse development environment. The Platform Runtime Binary package is only around 40M to download, whereas versions of the development environment can be 100M and up.

The Platform Runtime Binary package is distributed as an archive file, and can be unarchived at any suitable location.

Setting Up Your First DITA Document

Render a DITA map and topic content using the "eclipsehelp" transformation type. See the DITA User Guide for instructions on how to run a DITA transformation.

After rendering, the output directory will contain an Eclipse Help plugin. Simply copy the entire output directory to:

<where you installed the Eclipse Platform Runtime Binary package>/eclipse/plugins

so that the copied output directory is beneath the plugins directory. For example, if you were to render the Dita Users' Guide, you could copy the output directory to:

<where you installed the Eclipse Platform Runtime Binary package>/eclipse/plugins/dita-uguide

Starting the Eclipse Infocenter

The Infocenter requires Sun Java 1.5. Start the Infocenter with the following command:

java -classpath <eclipse-location>/eclipse/plugins/org.eclipse.help.base_3.3.1.v20070813_33x.jar org.eclipse.help.standalone.Infocenter -command start -eclipsehome <eclipse-location>/eclipse -port 8081

where <eclipse-location> is the point where you installed the Eclipse Platform Runtime Binary package.

NB: This command is run on a single line.

Point your favorite browser to http://localhost:8081/help/index.jsp

The Infocenter will appear, with bookmarks to the left, and an Eclipse welcome page in the right frame.

The first few bookmarks will be Eclipse platform documentation. At the bottom of the bookmark list, you should see your Dita document.

To shut down the Infocenter, re-run the above command, but with the augument "-command shutdown"

Customization and Branding

When you opened the Infocenter, you probably noticed how the help system was branded as an Eclipse product. To change the branding to suit your Dita documentation requires editing a set of configuration files.

 

Product Plugin

The product plugin for an Information Center is the plugin ID that is defined in the config.ini file or via the  -plugincustomization option in the start command.  The product plugin contains the overrides for branding your particular Informaiton Center.

If you're interested in a 'cookbook recipe' for creating a product plugin using Eclipse, see An infocenter product plugin cookbook.

 

Product Branding

With your favorite text editor, open:

<eclipse-location>/eclipse/plugins/<your_product_plugin>/plugin.properties

Near the top of the file, you will see:

productName=Eclipse Platform

Change this to suit your Dita documentation.

To activate this variable, it may be necessary to erase the Eclipse runtime cache. As of this writing, the only way I know how to do this is to delete the cache by hand. After shutting down the Infocenter, go to:

<eclipse-location>/eclipse/configuration

Delete all directories that start with "org.", being careful NOT to delete the file "config.ini"

The preferred way to link the controlling to your Elcipse envirment is via the configuration/config.ini.  At the bottom of the file add the following line:

eclipse.product=<your_product_plugin_id>.helpProduct

The -plugincustomization (location if product plugin containing the plugincustomization.ini file) is useful alternative if you are using the same Eclipse framework to serve up multiple Information Centers.  One issue to be aware of, in this case, is that the URL to the folder or jar file is harcoded in the start command. If the folder name or jar file name is updated, then the start command also needs to be updated.

 

Bookmarks

To hide the Eclipse documentation listed in the bookmarks, edit the file:

<eclipse-location>/eclipse/plugins/<your_product_plugin>/helpData.xml

Change the tocOrder tag to "hidden" to hide the Eclipse bookmarks. The file should look like:

<?xml version="1.0" encoding="utf-8"?>

<extensions>

<hidden>

<toc id="/org.eclipse.platform.doc.user/toc.xml"/>

<toc id="/org.eclipse.jdt.doc.user/toc.xml"/>

<toc id="/org.eclipse.platform.doc.isv/toc.xml"/>

<toc id="/org.eclipse.jdt.doc.isv/toc.xml"/>

<toc id="/org.eclipse.pde.doc.user/toc.xml"/>

</hidden>

</extensions>

If you have several Dita documents served by the Infocenter, they will appear in the bookmark list in a default order. If you would like to modify the order, you can use the helpData.xml file to do so. This is done with the tocOrder element. For example:

<?xml version="1.0" encoding="utf-8"?>

<extensions>

<tocOrder>

<toc id="/dita-userguide/DITA-userguide.xml"/>

<toc id="/another-doc/DOC-document.xml"/>

</tocOrder>

<hidden>

<toc id="/org.eclipse.platform.doc.user/toc.xml"/>

<toc id="/org.eclipse.jdt.doc.user/toc.xml"/>

<toc id="/org.eclipse.platform.doc.isv/toc.xml"/>

<toc id="/org.eclipse.jdt.doc.isv/toc.xml"/>

<toc id="/org.eclipse.pde.doc.user/toc.xml"/>

</hidden>

</extensions>

The content of the id attribute in the above example is not a filename reference. Instead, it is based on information contained in the Dita document plugin configuration file. This file is named "plugin.xml," and is located in the Dita eclipsehelp output directory. For example, in the Dita User Guide output located at:

<eclipse-location>/eclipse/plugins/dita-ugide/plugin.xml

the content is:

<?xml version="1.0" encoding="utf-8"?>

<plugin name="DITA User Guide" id="dita-userguide" version="1.0" provider-name="DITA">

<extension point="org.eclipse.help.toc">

<toc file="DITA-userguide.xml" primary="true"/>

</extension>

<extension point="org.eclipse.help.index">

<index file="index.xml"/>

</extension>

<!-- Product plugin extension point -->

<extension id="helpProduct" point="org.eclipse.core.runtime.products">

<product name="%productName" application=""/>

</extension>

</plugin>

The first part of the extensions/tocOrder/toc/@id attribute in helpData.xml is taken from the the id attribute in the plugin.xml file. The second part of the extensions/tocOrder/toc/@id attribute, after the second /, is a filename reference. It is taken from the plugin.xml file at plugin/extension/toc/@file attribute.

In other words, the first part, between the first / and the second / is from the id attribute in plugin.xml. The second part is from the file attribute in the toc element in plugin.xml

NB: In helpData.xml, the tocOrder element MUST precede the hidden element.

Product Banner

This feature is optional, a matter of taste or policy. The banner, if activated, appears at the top of every help page, and reduces the display area of the page. It can be used to display such things as logos and customer service information. It's a standard html page.

Banner configuration is done in a configuration file located in the platform plugin directory:

<eclipse-location>/eclipse/plugins/<your_product_plugin>/plugin_customization.ini

The basic configuration syntax is:

<plugin-name>/<parameter> = <value>

To set a banner page that is located in the dita-uguide plugin directory:

org.eclipse.help.base/banner = /dita-userguide/doc/banner.html

In this case, org.eclipse.help.base is the plugin that sets this parameter, banner is the parameter that is being set, dita-userguide is the plugin id where the banner page is located (NOT the plugin directory), doc is the directory within the plugin directory where the page is located, and banner.html is the banner page itself.

As with the TOC configuration, it's important to remember to distinguish between the plugin id and the name of the plugin directory.

To set the pixel height of the window where the banner will be displayed, add this parameter to plugin_customization.ini:

org.eclipse.help.base/banner_height = 80

To activate this configuration, shutdown and re-start the Infocenter.

Home Page

The home page is displayed when the user clicks on the home icon at the top of the help display. It can be used to explain basic usage of the help system.

To set a home page that is located in the dita-uguide plugin directory, add this parameter to your plugin_customization.ini:

org.eclipse.help.base/help_home = dita-userguide/doc/help_home.html

The syntax is the same as for the banner page parameter.

To activate this configuration, shutdown and re-start the Infocenter.