Sun Officially Unveils JavaHelp 2.0 Beta
Click a link below to jump to a particular section; click any "
After several years of fits and starts, Sun Microsystems recently announced the release of the long-awaited JavaHelp 2.0 Beta. For the uninitiated, JavaHelp is an online Help delivery mechanism designed specifically for Java applications. JavaHelp leverages the "write once, run everywhere" mantra of Java itself, and thus is ideal for Java applications. (JavaHelp is not a suitable replacement for Windows-only Help systems, for which HTML Help is a viable solution.) Prior to the 2.0 Beta release, JavaHelp was not comparable to other HTML-based systems (such as WebHelp and WebWorks Help) because it used a built-in content viewer based on the Swing JEditorPane component. With the introduction of server-based help in the JavaHelp 2.0 Beta, JavaHelp is comparable to other HTML-based systems that rely on a 3rd party browser for delivery.
This review of the new JavaHelp 2.0 Beta includes a comparison of JavaHelp 1.1.3/2.0 functionality and an evaluation of JavaHelp 2.0 Beta covering installation, operating system support, migration issues, and new features. Also included is information about downloading the 2.0 Beta and how to provide feedback to Sun.
JavaHelp's genesis goes all the way to back to 1997. Shortly after the emergence of Java itself, the JavaSoft division of Sun recognized a need for an online Help platform, and JavaHelp was born. JavaHelp developers attended the 1997 WinWriters Help Technology Conference and the 1998 Annual WinWriters Conference to raise awareness of this fledgling online Help platform. The initial version of JavaHelp, version 1.0, was released in March 1999.
In May of 1999, WinWriters and Sun jointly sponsored the well-attended "JumpStart Conference for JavaHelp Technology," held in San Francisco. JavaHelp's benefits were heralded as a true cross-platform solution (without the hassles of cross-browser support). In reality, the 1.0 version of JavaHelp was not ready for prime time, specifically because of limitations in terms of HTML support, graphics rendering, and printing functionality. (These limitations are due to the underlying Java Runtime Environment, which JavaHelp uses to render content.) But because of the steadily increasing popularity of Java itself, the promise of JavaHelp was still appealing to a wide audience in the technical communications field.
That promise failed to live up to expectations. Incremental point releases trickled out, but overall, Help authors waited in vain for additional features and improved functionality. For the JavaHelp team at Sun, the following several years posed quite a challenge. Reorganizations and management changes at Sun decimated the JavaHelp team. JavaHelp's future seemed uncertain, and it appeared that Sun's commitment to the project was dubious. In early 2002, there was even talk that JavaHelp would be folded into the open source NetBeans Organization. Then in December 2002, JavaHelp finally found a home within Sun's Java 2 Standard Edition (J2SE) division of the Java development group.
On March 13, 2003, the lead engineer of JavaHelp, Roger Brinkley, announced the release. In a posting on the JavaHelp discussion list, he stated, "The updates include enhancements to merging of helpsets, multi-topic printing, more ways to display Help in secondary windows and popups, additional Navigators, and a major new feature: server-based Help."
The JavaHelp 2.0 Beta is now available at the following location (requires free registration):
The distribution is a dainty 6MB.
JavaHelp 2.0 retains much of the directory structure and file naming conventions as JavaHelp 1.1.3. Table 1 (shown below) provides an overview of the JavaHelp2.0 Beta contents, and how it compares to the JavaHelp1.1.3 contents. The following topics are also evaluated in a comparison between 1.1.3 and the 2.0 Beta:
Table 1: JavaHelp 2.0 Beta components compared to JavaHelp 1.1.3
Because the actual rendering of content is controlled by the Java SDK Swing "JEditorPane" component, the JavaHelp 2.0 Beta does not exhibit any improvements in terms of content rendering. JavaHelp 1.1.3 exhibited some annoying behavior patterns in terms of graphics rendering. For example, the JavaHelp viewer occasionally displayed a "broken graphic" icon (when in fact the graphic file was accessible), and then it immediately displayed the graphic properly upon refreshing the viewer contents. In other instances, the JavaHelp viewer displayed a shadow of a broken graphic, which also disappeared upon a screen refresh. The content rendering is entirely dependent on the underlying Java SDK to display the JavaHelp system. JavaHelp 2.0 Beta will not provide any improvements in terms of content presentation. The good news is that Sun is continuously improving the Java SDK, and thus the JEditorPane's rendering capabilities will likely improve with each version of the Java SDK.
Figure 1 (shown below) is a screen capture of JavaHelp 2.0 Beta exhibiting the same behavior as 1.1.3. (Note that version 1.4.0_01 of the Java SDK was used to display the JavaHelp system in Figure 1. In my testing, the rendering improved when I upgraded to the 1.4.1 version of the Java SDK).
Figure 1: JavaHelp 2.0 rendered with Java SDK 1.4.0 - Content pane with 'ghost' image icon (below the horizontal rule)
JavaHelp 1.1.3 occasionally printed topics in which the right-hand margin would be cut off, making the printed topic illegible. (The official Sun bug ID is 4352983.) Another periodic problem with printing was that a print job from JavaHelp would "pin" the CPU (this was caused by JavaHelp's inability to determine the end of the page). According to Roger Brinkley, Lead JavaHelp engineer of Sun, both of these problems have been fixed in JavaHelp 2.0 Beta.
In my testing, neither of these problems occurred. However, I did notice some formatting issues, specifically in terms of:
Both of these behaviors were exhibited when I printed the "The JavaHelp 2.0 Release" topic in the JavaHelp 2.0 User's Guide HelpSet.
Title Bar Icon
With JavaHelp 1.1.3, there is no "officially" documented way to change the "coffee cup" icon in the title bar (though if you search the JavaHelp listserv archives, there are instructions for how to accomplish this programmatically). With JavaHelp 2.0, there still is no "official" mechanism for changing the title bar icon, as shown in Figure 2 below. According to Roger Brinkley the framework of the JavaHelp Help broker has fundamentally changed, and thus the instructions posted to the listserv for changing the icon programmatically will not work for the 2.0 release.
Figure 2: Icon in Title Bar is not customizable in JavaHelp 2.0
Search Term Highlighting
One of the problems that plagued the 1.1.3 version of JavaHelp was improper search term highlighting (documented in Sun bug ID 4375554). Typically, the highlighted search term was shifted by one or two characters to the left or right. For example, the user enters christmas in the search entry box. Rather than highlighting the entire search word in the topic, the JavaHelp viewer would highlight 'hristmas' or 'christma' instead of 'christmas.' According to a posting by Roger Brinkley the "...implementation of the search highlighting (is) too susceptible to changes in the parsing of the JDK." In my initial testing with the JavaHelp 2.0 Beta and the Java SDK version 1.4.0_01, the improper search term highlighting was still evident. (See Figure 3 below.) However, when I upgraded to the 1.4.1 version of the Java SDK, the search term highlighting was markedly improved. As with content rendering in general, the search term highlighting is particularly reliant on the underlying Java SDK.
Figure 3: JavaHelp 2.0 Beta exhibits improper search term highlighting with version 1.4.0 of the Java SDK
The Java 2 SDK is required before you attempt to install JavaHelp. Although the JavaHelp User's Guide states, "You must uninstall prior releases before unpacking V2.0 into a directory," a more precise requirement is that you must not install V2.0 into a directory that contains V1.1.3. In other words, you do not have to remove your JavaHelp 1.1.3 installation in order to install V2.0 in a new directory. Keep in mind, however, that you may have to change the value of your PATH environment variable in order to specify which version of the jhindexer to use.
There is no installation program for JavaHelp; it is available on Sun's site as a .zip file. "Installation" is accomplished by unzipping the distribution file. (At one point in an early release, JavaHelp was packaged with an "InstallAnywhere" installation wizard, but Sun later abandoned it because of JDK incompatibility issues.) This lack of an Install wizard will not surprise JavaHelp veterans and others who are accustomed to zipping, tarring, and jarring. (In fact, this distribution method is consistent with Sun's overall method of distributing Java extensions.)
But for those who expect an install wizard? No dice. JavaHelp's "out-of-box" experience could be improved by delivering a genuine installation program that installs the program and, for example, invokes the JavaHelp viewer with the JavaHelp User's Guide after completing the installation. A genuine installation program provides a polished, professional touch to a software deliverable, and improves the overall "out-of-box" experience for the uninitiated. A genuine installation program for JavaHelp 1.1.3 is available on the Solaris 9 CD, and JavaHelp 2.0 is slated to ship on the upcoming Solaris 10 CD.
Here's an example of why links to external sites are less-than-ideal in JavaHelp: when I clicked on the link to the "Component One" web site, it displayed very poorly in the JavaHelp viewer. When I clicked the "Back" [<] button to return to the "Introduction" topic, the content did not display. in fact, none of the topics displayed, forcing me to close the helpset viewer and start over. because of these kinds of behavioral oddities, combined with the Help viewer's inability to display sites that utilize scripting, it's generally not a good idea to insert links to external sites.
The JavaHelp User's Guide HelpSet should serve as a model for how to design a HelpSet. With the exception of the links to external sites, it succeeds overall.
Figure 4: JavaHelp displaying an external web site
According to the JavaHelp User's Guide, testing of the 2.0 Beta was conducted only for Windows 2000 and the Solaris platforms. This does not mean that JavaHelp will not run on other platforms; it simply means that it has not been tested on other platforms. Further testing on additional platforms will likely be conducted during the Beta cycle. In theory, the Java "write once, run anywhere" mantra also applies to Java extensions such as JavaHelp.
Strictly speaking, there are no migration issues. JavaHelp 2.0 is completely "backwards compatible." Without the aid of a Help Authoring Tool, you can still cobble together a JavaHelp system "by hand" (i.e., create the HTML content, hand-code the HelpSet file, Map file, index file, TOC file, and then build the search index with the jhindexer command-line tool) just as you would with JavaHelp 1.1.3. Be aware, however, that the current versions of Help authoring tools do not have interfaces for supporting such new features as glossary creation. So even if you replace the JavaHelp 1.1.3 libraries with the 2.0 Beta libraries in your authoring tool installation, the authoring tool won't be able to leverage the new features.
Forward-looking Statements from Help Authoring Tool Vendors
Greg Roig, Sales Manager at Quadralay Corporation (makers of the WebWorks Publisher conversion tools), states that "we will definitely be supporting JavaHelp 2.0, but not until the 2.0 version is officially released." Greg predicted that the 2004 version of WebWorks Publisher will support JavaHelp 2.0. (Sun anticipates that the official 2.0 release will be available this summer. Of course, the formal 2.0 release depends entirely on the duration of the Beta program.)
Stephan Schlect of Software7 (makers of the Helen authoring tool) is currently implementing support for the JavaHelp 2.0 features. He anticipates that a Beta version of Helen will be available soon. Paul Trotter, President of AuthorIT, states, "Yes we do intend to add support for JavaHelp 2.0," but was not specific about when support will be available. Marty Ford of SolutionSoft (makers of HelpBreeze), states, "Yes, we are definitely planning to support JavaHelp 2.0." It is currently working with the 2.0 Beta.
ComponentOne (makers of Doc-To-Help) and eHelp Corporation (makers of RoboHelp) did not respond to inquiries about JavaHelp 2.0 support.
Look for further announcements from the tool vendors over the next several months.
JavaHelp 2.0 Beta enables users to submit a print job for multiple topics (essentially mimicking a batch print job). (In previous versions of JavaHelp, users can print only the currently displayed topic, requiring a "one-at-a-time" printing process.) How does multi-topic printing work? (The JavaHelp User's Guide does not contain any explicit information on how to do multi-topic printing.) The user must select the desired topics before clicking the print button. (This requirement is somewhat counterintuitive, as my initial instinct was to click the "Print" button, with the presumption that the Print dialog had been enhanced.) The actual print dialog has not changed from the 1.1.3 version to the 2.0 Beta version of JavaHelp.
For example, in Figure 5 shown below, the user selects the "Ash Wednesday," "Easter," and "Historical Climate" topics, clicks the "Print" button, clicks "OK" in the Print dialog box, and all three topics print consecutively. (Note: the selected topics do not have to be consecutive; i.e., the user can select nonconsecutive topics.) The topic title and "N of N" numbering appear in the upper-right hand corner of every printed page. (The "N of N" numbering is per topic; i.e., if Topic A is 4 pages, the first printed page will read "Topic A 1/4".)
Figure 5: Result when multiple topics are selected... all print
However, in my testing, the multi-topic printing behavior was not always what I expected. For example, if the user selects the top-level "History of Easter" folder (which would presumably print all child topics), nothing prints. (See Figure 6 below.) (Note that the "History of Easter" folder does not display a corresponding topic in the content pane.)
Figure 6: Result when selected folder in navigation pane has no corresponding topic... nothing prints
In another test, I selected the "Release Information" top-level topic in the JavaHelp Users' Guide HelpSet. (See Figure 7 below.) (In this case, the "Release Information" folder does display a corresponding topic when selected.) I expected the "Release Information" topic, as well as all the child topics, to print, but only the "Release Information" topic actually printed.
Figure 7: Result when selected folder in navigation pane has a corresponding topic... only corresponding topic prints (child topics do not print)
As another point of reference, HTML Help handles multi-topic printing in the following manner:
Figure 8: 'Print Topics' dialog box in HTML Help
This model works well, because it presents an option to the user, and provides a sense of what to expect.
Comprehensive Merging Options
The merging capabilities of 1.1.3 JavaHelp were, in a word, inadequate. In fact, if you attempted to merge two or more HelpSets with indexes, you quickly realized that the result was unusable because the index entries were concatenated, rather than sorted alphabetically. In other words, the index would list index entries A-Z for the first HelpSet, then A-Z for the next HelpSet, etc., which made the index unusable. This behavior was quite frankly a "show-stopper" in terms of merging multiple HelpSets with indexes, especially considering recent trends that position the index as the preferred navigational device (widely over the TOC, and often over the search engine).
JavaHelp 2.0 introduces the concept of a "merge type," which enables the Help author to define how to merge the "views" of a HelpSet. The following merge types are defined:
(See the JavaHelp User's Guide for descriptions of each merge type.)
By default, the "merge type" for the index "view" is "Append," which maintains the useless functionality of JavaHelp1.1.3 merging (this is designed to "maintain compatibility" with JavaHelp1.1.3). In theory, with these new merging types, merging HelpSets with indexes becomes practical.
I was curious to see how the "Newmerge demo" would reflect this new merging behavior. The JavaHelp User's Guide states that the Newmerge demo "Demonstrates (the) JavaHelp system HelpSet merging capabilities. For details, see the online Help available from the Help menu in the newmerge demo program." I invoked the Newmerge demo, and a window appeared that looks similar to a JavaHelp viewer. (See Figure 9 below.)
Figure 9: "newmerge" demo, initial window
The Help - Contents menu of the demo window provides information on how to use the "newmerge" demo to demonstrate the merging functionality. To add additional HelpSets to the initial window, simply select HelpSet - Add and navigate to the following directory:
and select the vertebrates.jar file. Repeat and select invertebrates.jar. After adding both HelpSets, the window reflects the vertebrates and invertebrates content, as shown in Figure 10 below.
Figure 10: "newmerge" demo, with invertebrates and vertebrates HelpSets added (note the merged TOC)
Figure 11 below displays the merged vertebrates and invertebrates HelpSets, with the index entries sorted canonically based on the
Figure 11: Merged index
Another feature of the "newmerge" demo is its "Master and Slave view" display (see Figure 12 below), which displays the respective navigational views of the master and slave HelpSets. This display is accessible from the View menu of the "newmerge" demo.
Figure 12: 'Master and Slave view' tool
New Views in Navigator Pane of Help Viewer
First, let's define some terms. What is a "view" in the JavaHelp Viewer? The JavaHelp User's Guide refers to the various navigational elements of the navigation pane as "views." (This concept is also applied in the HelpSet file.)
The supported "view" types are:
The Glossary and Favorites view types are new in JavaHelp 2.0. (See Figure 13 below.)
Figure 13: New 'view' types: Glossary and Favorites
The Glossary View
For JavaHelp veterans, creating a glossary view will be a snap. It's a matter of defining the glossary terms and definitions in an XML file (similar to the index file), and then defining the glossary view in the HelpSet file. (The JavaHelp User's Guide describes this in detail, and provides examples.) While the glossary view can be used to enhance the navigator pane, another (more straightforward) approach is to simply create a single HTML topic with glossary terms and definitions. The advantage of the glossary view is that the user can view the glossary view while simultaneously viewing a topic in the content pane.
Figure 14: Glossary view of the 'History of the Holidays' sample HelpSet
In my testing, it was straightforward to add glossary entries. The process is as follows:
Figure 15 shows the resulting HelpSet.
Figure 15: Holiday History sample HelpSet with 'Boxing Day' added to glossary
The Favorites View
The favorites view enables the user to 'bookmark' the desired topics. Similar to the glossary view, creating a favorites view is a matter of defining the view in the HelpSet file. Because the user actually controls the 'favorite' topics, JavaHelp writes to the favorites.xml file "on-the-fly," and stores it in the userdir/.JavaHelp/ directory.
The IDEDEMO (located in the
Figure 16: Adding a favorite topic via the context menu
In addition to the right-click context menu, a "Favorites" button is a toolbar customization option.
Presentation Controls - Toolbar Buttons
The 2.0 Beta release provides the ability to customize the toolbar of the JavaHelp viewer. You can select to add a combination of any of the following buttons on the toolbar:
For an example of these toolbar buttons, see Figure 16, which has "Back," "Forward," "Home," "Print," and "Print Setup" buttons on the toolbar. To control which buttons to display on the toolbar, you must edit the HelpSet file and insert a
Here is an example of the required code:
<!--begin snippet <presentation default=true> <name>main window</name> <size width=400 height=400 /> <location x=200 y=200 /> <title>Project X Help</title> <toolbar> <helpAction>BackAction</helpAction> <helpAction>ForwardAction</helpAction> <helpAction image="homeicon">HomeAction</helpAction> </toolbar> </presentation> end snippet--!>
Enhanced Controls Over Window Types
The IDEDEMO for JavaHelp 2.0 is enhanced to demonstrate the functionality of secondary windows and popups, (see Figure 17 below).
Figure 17: Enhanced Help menu of the IDEDEMO
With the 2.0 version of JavaHelp, the ability to define windows types (such as secondary or popup) is pervasive throughout the system. The "Java Development Environment - Online Help" (which is accessible from the Help > Demo JDE - Help menu) contains an example of a secondary and popup windows accessible from the navigation pane (see Figure 18 below).
Figure 18: Java Development Environment - Online Help DemoWhen the user clicks on "Beans In JDE - in Popup" in the navigation pane, a popup window appears (see Figure 19 below).
Figure 19: Example of popup window, accessible from the navigation pane
The popup window in Figure 19 is perhaps larger than the recommended size for a popup, but it is intended primarily for demonstration purposes.
One of the highly touted new features of JavaHelp 2.0 is server-based Help. The JavaHelp User's Guide defines the subject on a highly conceptual level, and there are no sequential task-based instructions for how to implement JavaHelp in a server-based context. This documentation is clearly geared towards the Java programmers and Web engineers tasked with implementing server-based Help systems.
In a nutshell, server-based Help is "served" dynamically from a web server and rendered in a browser (e.g., IE). This is in contrast to "stand-alone" JavaHelp systems that reside on a file system (e.g., a local or mapped drive) and use the JavaHelp viewer to render the content. The primary role of JavaHelp in a "server-based" online Help scenario is the "back-end" management functionality, as opposed to the "front-end" GUI.
For the Help author, there is a one critical difference between "served" Help and "stand-alone" Help in terms of how the content is developed. Because "served" Help can use a browser for delivery, the Help author is not restricted by the rendering limitations of the JavaHelp viewer. Server-based Help is of course more complex in terms of architecture, and thus the Help author will likely have to work closer with the Java engineers and Web engineers who are tasked with designing and implementing a server-based Help scenario.
The 'serverhelp' demo is located in the following directory:
This demo is not documented in the "Demonstration Programs" section (or anywhere else) in the JavaHelp 2.0 User's Guide. There is a README file in the following directory:
The README states that the server-based demo "...requires Jakarta Tomcat 4.0 or greater and Apache Ant." Many Help authors may not be familiar with the Apache open source technology. (For a primer on Apache, you may want to attend my upcoming session at the 50th Annual STC Conference, entitled "Web Servers 101.") Both of these tools require the JAVA_HOME environment variable, which is not documented in the README file.
The README states that both Jakarta Tomcat and Apache Ant are available on the following web site:
However, only Tomcat is available on the defined site. Apache Ant is available on the following web site:
After downloading and installing both Tomcat and Ant, I followed the next step in the README file, which is to execute the following command:
ant –Dcatalina.home=Jakarta_tomcat_home all deploy
Note: this command must be executed from the following directory:
To see the actual server-based help running, ensure that your Jakarta Tomcat server is running, and then enter the following URL in a browser:
where <localhost> is your local system name.If the demo was built correctly, you will see what's shown in Figure 20 below:
Figure 20: JavaHelp 2.0 Beta 'server-based' demo - initial page
The links in Figure 20 actually display "served" JavaHelp systems. For example, if you click on the first "Animals - A merged Helpset" link, the following appears in Figure 21 below:
Figure 21: A 'served' JavaHelp system, rendered in Internet Explorer
An alternate display of the same content is accessible from the second "Animals - A merged Helpset" link. This content is also rendered in Internet Explorer in Figure 22 below.
Figure 22: An alternate presentation of a server-based JavaHelp system
To get the latest information on JavaHelp, consider attending the upcoming JavaOne conference. According to Larry Hoffman of the JavaHelp team, "We may be doing a full-scale talk at JavaOne and are definitely doing a BOF (Birds Of a Feathersmall WinWriters style talk as opposed to a mega session)." JavaOne will be held at San Francisco's Moscone Convention Center, June 10-13, 2003.
For the latest information on JavaHelp developments, consult the JavaHelp site.
The JavaHelp listserv is quite active and is regularly monitored by both the JavaHelp engineers as well as real people using JavaHelp in the real world. The Beta version is exactly thata Beta. Sun is looking for your feedback. So, download it, install it, put it through the wringer, and let Sun know what you think! Here are some suggestions to note when providing feedback:
After your posting on the listserv, you may be instructed by the JavaHelp team to file an official bug report.
JavaHelp is a viable online Help delivery mechanism for Java applications. (Do not consider JavaHelp unless you are developing a Help system for a Java application.) JavaHelp's distinct advantage over other HTML-based systems (such as WebWorks Help and WebHelp) is that it can be implemented without the reliance on a 3rd party browser (e.g., Netscape, Internet Explorer, Mozilla, Opera, etc.). Of course, the JavaHelp viewer has its own limitations, and is subject to all the variations of the Java SDK.
JavaHelp's API allows developers to easily implement JavaHelp without all the known variables of browser-based systems. Also, browser-based systems require you to validate your content against multiple browsers and various versions.
The JavaHelp 2.0 Beta introduces some compelling features, especially the potential for server-based implementations. Perhaps the most disappointing element of the JavaHelp 2.0 Beta is that it is still subject to all the same fundamental rendering problems of JavaHelp 1.1.3 due to its reliance on the JEditorPane. But server-based Help does provide some alternatives in terms of content rendering. Overall, the JavaHelp 2.0 Beta is worth exploring. Help authors can easily leverage some of the new features (such as glossary views in the navigation pane and multi-topic printing), while other features will require a significant investment in development (such as merging, toolbar enhancements, and server-based implementations). And of course, a Beta release is not recommended for production Help systems.
Table 2: Links referenced in this article
Sarah Leritz-Higgins is an Information Architect for Mentor Graphics. Before entering the field of Technical Communications in 1997, Sarah worked as a Technical Support Engineer for six years. This direct customer interaction sparked her interest in software usability and documentation methodologies. Sarah has a Bachelor's degree from Allegheny College in Meadville, PA.