Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[aperi-dev] JavaHelp, Eclipse-based online help, and third-party downloads

Currently, to enable Aperi's online help system (F1 functionality) within the product UI, installers must 1) go out to the Sun Website, 2) accept a License agreement, 3) download and unzip JavaHelp (the help engine), 4) copy jh.jar from the JahaHelp zip file to multiple locations within the Aperi installation directory.

Forcing installers to manually download third-party files like JavaHelp is something we want to avoid for Aperi. To workaround this problem, I've been investigating two options:

- determining if there is a way to use the jh.jar file within the Aperi package without forcing installers to manually accept its license, download, and install it. I am currently waiting to hear back from Sun on this issue.
- researching the use of Eclipse-based help to replace the JavaHelp engine that we currently use.

Background:

One of the options to remove our dependency on manually downloading jh.jar during Aperi's installation is to change the format/engine of Aperi's online help system. Currently, Aperi uses JavaHelp to display its context-sensitive help topics and jh.jar is required by JavaHelp.

A possible alternative to JavaHelp as a help engine is to use an Eclipse-based help system, which is an optional Rich Client Platform (RCP) component (it is not part of the minimal RCP, but can be added to it).

Eclipse-based help consists of XML and HTML files, which is similar to the file formats used in Aperi's current JavaHelp system. The majority of files in JavaHelp are HTML, and those files contain the actual help content. The JavaHelp content files follow the HTML 3.2 specification, which is supported in Eclipse-based help. This means we could directly port those files to an Eclipse-based help system with minimal changes.

More information about Eclipse-based help is available here:http://help.eclipse.org/help32/index.jsp > Platform Plug-in Developer Guide > Programmer's Guide > User assistance support

Migrating JavaHelp to Eclipse-based help:

We currently have 372 HTML files that contain the content for Aperi JavaHelp. Converting these files would consist of 1) search/replace any HTML tag elements that need to be changed for Eclipse (if any), 2) place these HTML files within a similar directory structure under an Eclipse project, 3) correct any linking and other problems that might have occured during the conversion. This would be just for the content files.

We would also need to create a navigation structure in an Eclipse-based help system that mirrors the structure we have in the current JavaHelp system. This task would include: 1) creating an XML file to act as the master TOC for the help system and provide hooks to the sub-TOCs, 2) creating an XML file (7) for each of the sub-TOCs to provide navigation links to all the HTML files in the system. Although both JavaHelp and Eclipse-based help share the XML format for their TOC files, the actual coding in the JavaHelp XML files has to be manually rewritten to match the required syntax of Eclipse XML files.

The final step would require effort from both ID and development to integrate the help into the Aperi build and packaging. This would involve: 1) creating a "map" file that associates IDs with help topics (currently 7 XML files exist in JavaHelp for this purpose), 2) editing the product code to remove the current JavaHelp-related coding, 3) writing hooks into the product code to launch Ecplise-based help from the menu bar, 4) writing hooks into the product code to invoke window-specific, Eclipse-based help topics ("F1" functionality) based on IDs in the map file, 5) integrating the help plugin within the existing Aperi code structure.

Aperi's Eclipse plug-in online help would be contributed using the org.eclipse.help.toc extension point. The following plug-ins must be added to the RCP base in order to run the Help system:

org.apache.lucene
org.eclipse.help.appserver
org.eclipse.help.base
org.eclipse.help.ui
org.eclipse.help.webapp
org.eclipse.tomcat
org.eclipse.ui.forms

Summary of tasks for migrating from JavaHelp to Eclipse-based help:

Who Task
Help author: Ensure that the existing HTML files are usable in an Eclipse-based help system and perform an clean-up.
Help author: Create a structure for the HTML files in an Eclipse plugin.
Help author: Create a master TOC.
Help author: Create sub-TOCs (7 XML files) for each of the main help sections.
Help author: Create a map file.
Development: Remove the current JavaHelp-related coding.
Development: Create hooks to Eclipse help from the menu bar and when pressing F1 from a product window.
Help author & Development: Integrate the help plugin.

Summary:

- I am waiting to hear if jh.jar can be used without forcing manual acceptance of a license agreement, download, and manual installation.
- If we migrate from JavaHelp to Eclipse-based help, we'll need a development resource to help implement that change. Who will be that resource, and is it containable for v0.4?

Any feedback is welcome, and encouraged.
_________________

Chris King
Information Development - Aperi
chriskng@xxxxxxxxxx
Aperi documentation: http://www.eclipse.org/aperi/documentation/


Back to the top