<h1>Creating a Stand Alone Eclipse Infocenter for Dita</h1>

<p>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.</p>

<p>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.</p>

<p>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.</p>

<p>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.</p>

<p>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.</p>

<h2>The Eclipse Platform Runtime Binary Package</h2>

<p>The Eclipse Platform Runtime Binary package is available from the </p>

<p><a
href="http://download.eclipse.org/eclipse/downloads/drops/R-3.3.2-200802211800/index.php">Eclipse 3.3.2 Download Page</a></p>

<p>Download the Platform Runtime Binary package that is appropriate for your
platform.</p>

<p>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.</p>

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

<h2>Setting Up Your First Dita Document</h2>

<p>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.</p>

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

<p>&lt;where you installed the Eclipse Platform Runtime Binary
package&gt;/eclipse/plugins</p>

<p>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:</p>

<p>&lt;where you installed the Eclipse Platform Runtime Binary
package&gt;/eclipse/plugins/dita-uguide</p>

<h2>Starting the Eclipse Infocenter</h2>

<p>The Infocenter requires Sun Java 1.5. Start the Infocenter with the
following command:</p>

<p><code>java -classpath
&lt;eclipse-location&gt;/eclipse/plugins/org.eclipse.help.base_3.3.1.v20070813_33x.jar
org.eclipse.help.standalone.Infocenter -command start -eclipsehome
&lt;eclipse-location&gt;/eclipse -port 8081</code></p>

<p>where &lt;eclipse-location&gt; is the point where you installed the
Eclipse Platform Runtime Binary package.</p>

<p>NB: This command is run on a single line.</p>

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

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

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

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

<h2>Customization and Branding</h2>

<p>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.</p>

<h3>Product Branding</h3>

<p>With your favorite text editor, open:</p>

<p>&lt;eclipse-location&gt;/eclipse/plugins/org.eclipse.platform_3.3.3.r33x_r20080129/plugin.properties</p>

<p>Near the top of the file, you will see:</p>

<p><code>productName=Eclipse Platform</code></p>

<p>Change this to suit your Dita documentation.</p>

<p>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:</p>

<p>&lt;eclipse-location&gt;/eclipse/configuration</p>

<p>Delete all directories that start with "org.", being careful
<strong>NOT</strong> to delete the file "config.ini"</p>

<h3>Bookmarks</h3>

<p>To hide the Eclipse documentation listed in the bookmarks, edit the
file:</p>

<p>&lt;eclipse-location&gt;/eclipse/plugins/org.eclipse.platform_3.3.3.r33x_r20080129/helpData.xml</p>

<p>Change the tocOrder tag to "hidden" to hide the Eclipse bookmarks. The
file should look like:</p>
<pre>&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;extensions&gt;
&lt;hidden&gt;
&lt;toc id="/org.eclipse.platform.doc.user/toc.xml"/&gt;
&lt;toc id="/org.eclipse.jdt.doc.user/toc.xml"/&gt;
&lt;toc id="/org.eclipse.platform.doc.isv/toc.xml"/&gt;
&lt;toc id="/org.eclipse.jdt.doc.isv/toc.xml"/&gt;
&lt;toc id="/org.eclipse.pde.doc.user/toc.xml"/&gt;
&lt;/hidden&gt;
&lt;/extensions&gt;</pre>

<p>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:</p>
<pre>&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;extensions&gt;
&lt;tocOrder&gt;
&lt;toc id="/dita-userguide/DITA-userguide.xml"/&gt;
&lt;toc id="/another-doc/DOC-document.xml"/&gt;
&lt;/tocOrder&gt;
&lt;hidden&gt;
&lt;toc id="/org.eclipse.platform.doc.user/toc.xml"/&gt;
&lt;toc id="/org.eclipse.jdt.doc.user/toc.xml"/&gt;
&lt;toc id="/org.eclipse.platform.doc.isv/toc.xml"/&gt;
&lt;toc id="/org.eclipse.jdt.doc.isv/toc.xml"/&gt;
&lt;toc id="/org.eclipse.pde.doc.user/toc.xml"/&gt;
&lt;/hidden&gt;
&lt;/extensions&gt;</pre>

<p>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:</p>

<p>&lt;eclipse-location&gt;/eclipse/plugins/dita-ugide/plugin.xml</p>

<p>the content is:</p>
<pre>&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;plugin name="DITA User Guide" id="dita-userguide" version="1.0" provider-name="DITA"&gt;
  &lt;extension point="org.eclipse.help.toc"&gt;
    &lt;toc file="DITA-userguide.xml" primary="true"/&gt;
  &lt;/extension&gt;
  &lt;extension point="org.eclipse.help.index"&gt;
    &lt;index file="index.xml"/&gt;
  &lt;/extension&gt;
&lt;/plugin&gt;
</pre>

<p>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.</p>

<p>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</p>

<p>NB: In helpData.xml, the tocOrder element <strong>MUST</strong> precede
the hidden element.</p>

<h3>Product Banner</h3>

<p>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.</p>

<p>Banner configuration is done in a configuration file located in the
platform plugin directory:</p>

<p>&lt;eclipse-location&gt;/eclipse/plugins/org.eclipse.platform_3.3.3.r33x_r20080129/plugin_customization.ini</p>

<p>The basic configuration syntax is:</p>

<p>&lt;plugin-name&gt;/&lt;parameter&gt; = &lt;value&gt;</p>

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

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

<p>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.</p>

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

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

<p>org.eclipse.help.base/banner_height = 80</p>

<p>To activate this configuration, shutdown and re-start the
Infocenter.</p>

<h3>Home Page</h3>

<p>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.</p>

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

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

<p>The syntax is the same as for the banner page parameter.</p>

<p>To activate this configuration, shutdown and re-start the
Infocenter.</p>