Creating a Stand Alone Eclipse Infocenter for DITA

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

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

The only cost (so far) that I have seen in deploying this system is thatit is designed for Eclipse and Java developers. Setup of the system is notobvious for someone who lives and works outside of the Eclipse universe, dueto 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 Helpdeployment for those wishing to use the DITA Eclipse Help transformationtype.

This document is based on deployment of the current Eclipse stablerelease, 3.3.2, from February 21, 2008. If you use a different releaseof Eclipse, then file name references given in the following examplesmay 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 yourplatform.

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

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

Setting Up Your First DITA Document

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

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 Binarypackage>/eclipse/plugins

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

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

Starting the Eclipse Infocenter

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

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

where <eclipse-location> is the point where you installed theEclipse 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 Eclipsewelcome page in the right frame.

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

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

Customization and Branding

When you opened the Infocenter, you probably noticed how the help systemwas branded as an Eclipse product. To change the branding to suit your Ditadocumentation 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 Eclipseruntime cache. As of this writing, the only way I know how to do this is todelete the cache by hand. After shutting down the Infocenter, go to:

<eclipse-location>/eclipse/configuration

Delete all directories that start with "org.", being carefulNOT 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 thefile:

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

Change the tocOrder tag to "hidden" to hide the Eclipse bookmarks. Thefile 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 willappear in the bookmark list in a default order. If you would like to modifythe order, you can use the helpData.xml file to do so. This is done with thetocOrder 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 afilename reference. Instead, it is based on information contained inthe Dita document plugin configuration file. This file is named"plugin.xml," and is located in the Dita eclipsehelp outputdirectory. 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 inhelpData.xml is taken from the the id attribute in the plugin.xml file. Thesecond part of the extensions/tocOrder/toc/@id attribute, after the second /,is a filename reference. It is taken from the plugin.xml file atplugin/extension/toc/@file attribute.

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

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

Product Banner

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

Banner configuration is done in a configuration file located in theplatform 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 plugindirectory:

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

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

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

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

org.eclipse.help.base/banner_height = 80

To activate this configuration, shutdown and re-start theInfocenter.

Home Page

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

To set a home page that is located in the dita-uguide plugindirectory, 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 theInfocenter.