Sun Officially Unveils JavaHelp 2.0 Beta

By Sarah Leritz-Higgins


Contents

Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

Introduction    Link to the article Contents

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.

Brief History: From Vaporware to the 2.0 Beta    Link to the article Contents

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.External link 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 Download    Link to the article Contents

The JavaHelp 2.0 Beta is now available at the following location (requires free registration):
developer.java.sun.com/developer/earlyAccess/javahelp/index.htmlExternal link

The distribution is a dainty 6MB.

JavaHelp 1.1.3 - 2.0 Beta Comparisons    Link to the article Contents

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:

  • Graphics Rendering
  • Printing
  • Title Bar Icon
  • Search Term Highlighting
Component JavaHelp2.0 Beta JavaHelp1.1.3
JavaHelp User's Guide

Same as 1.1.3, available in both PDF and JavaHelp. (TOC in PDF is at the beginning of the file.) Structure of the User's Guide is essentially the same as 1.1.3; grouped into 5 top-level categories:

* JavaHelp 2.0 Release
* JavaHelp System Overview
* Authoring Help Information
* Programming with the JavaHelp System
* Localizing Help Information

Link text in PDF User's Guide is not distinct from normal text, making hypertext navigation difficult.

Section 2.4, "Demonstration Programs," "Newmerge Demo" is a bad link.

TOC in PDF User's Guide is at the end of the file. Link text in PDF is enclosed in boxes, enabling hypertext navigation.

Specification

JavaHelp 2.0 spec. (PDF) Published March 13, 2003. (Essentially an updated draft of the JavaHelp APIs proposed in JSR-097.)

Provides the following list of changes from the V1.0 Specification
* Added Glossary and Favorites Navigators
* Removed JDK 1.1 as a supported platform
* Added Server based JavaHelp through JSP Extensions and ServletHelpBroker
* Added comprehensive merge support
* Added Presentation controls to HelpSet file and navigator files
* Added Presentation Class and CSH changes to support presentation class
* Added customizable Toolbar support in HelpSet file
* Added implementation section to HelpSet file
* Added Dynamic CSH for components
* Update Invocation Mechanism scenarios.

JavaHelp 1.0 spec. (HTML) Published in April 1999. (This was the original published spec.)

API

Documents the same packages as 1.1.3, with one addition:
javax.help.tagext

Documents the following packages via JavaDoc:
com.sun.java.help.impl
javax.help
javax.help.event
javax.help.plaf
javax.help.plaf.basic
javax.help.search

Libraries and tools

Identical in terms of file names, with the exception of the ../lib/dtd/ directory:

../lib/dtd
favorites_2_0.dtd
helpset_2_0.dtd
index_2_0.dtd
map_2_0.dtd
toc_2_0.dtd

../bin/JavaHelpindexer
JavaHelpindexer.bat
JavaHelpindexer.jar
JavaHelpsearch
JavaHelpsearch.bat
JavaHelpsearch.jar

../lib/JavaHelp.har
JavaHelpall.jar
JavaHelpbasic.jar
jsearch.jar

../lib/dtd/
helpset_1_0.dtd
index_1_0.dtd
map_1_0.dtd
toc_1_0.dtd

Demonstration programs

Identical in terms of filenames, with one addition:
../demos/bin/newmerge.jar

../demos/bin
apiviewer.jar
hsviewer.jar
idedemo.jar
merge.jar
object.jar
UserGuide.jar

Sample Helpsets

Includes all the same HelpSet demos as 1.1.3, plus a major new example of merging:
../demos/hsjar
animals.jar
invertebrates.jar
vertebrates.jar

../demos/hsjar
apidoc.jar
holidays.jar
idehelp.jar
idehelp_de.jar
idehelp_en.jar
idehelp_ja.jar
object.jar

JavaHelp source files

Identical in terms of file name (src.jar) and path: <install_dir>/<JavaHelp2.0|JavaHelp1.1.3/src.jar

Source files for the JavaHelp system (except the full-text search engine). (src.jar)

DTDs

The DTDs (Document Type Definitions) that define the XML-based metadata files (helpset, map, TOC, Index). JavaHelp 2.0 updates the .dtd files from 1.1.3, and provides one new .dtd file:

../lib/dtd
favorites_2_0.dtd
helpset_2_0.dtd
index_2_0.dtd
map_2_0.dtd
toc_2_0.dtd

../lib/dtd
helpset_1_0.dtd
index_1_0.dtd
map_1_0.dtd
toc_1_0.dtd

Default Style Sheet

Identical to 1.1.3.

../doc/css/default.css

  

Table 1: JavaHelp 2.0 Beta components compared to JavaHelp 1.1.3

Graphics Rendering

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)

Figure 1: JavaHelp 2.0 rendered with Java SDK 1.4.0 - Content pane with 'ghost' image icon (below the horizontal rule)

Printing

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:

  • Extra space around italicized and underlined words and phrases
  • Underlining that extends beyond the actual word or phrase

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

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

Figure 3: JavaHelp 2.0 Beta exhibits improper search term highlighting with version 1.4.0 of the Java SDK

JavaHelp 2.0 Beta Installation    Link to the article Contents

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.

JavaHelp Documentation    Link to the article Contents

While the JavaHelp 2.0 Beta User's Guide has been enhanced to document new features, it is essentially the same structurally. One questionable practice is its use of links to external sites. The "Introduction" topic contains several links to the web sites of the respective Help authoring tool vendors. While helpful in theory, in practice this is not recommended because the JEditorPane Swing component (which actually displays the help content) does not support HTML 4.x. Why does this matter? Because most modern sites employ some sort of scripting (for example, JavaScript), and scripting is only supported in HTML 4.x. These external links also assume the user has Internet access (a fairly safe assumption, though not a guarantee).

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

Figure 4: JavaHelp displaying an external web site

OS Support    Link to the article Contents

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.

Migration Issues    Link to the article Contents

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.

Analysis of New Features    Link to the article Contents

Multi-Topic Printing

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

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

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)

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:

  1. User selects a folder ('heading') with child topics.
  2. User clicks the 'Print' button. dialog box in Figure 8 below appears, offering the user a choice.
  3. After selecting a radio button and clicking OK, the standard 'Print' dialog box appears.

Figure 8: 'Print Topics' dialog box in HTML Help

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:

  • Unite-Append
  • Sort
  • Append
  • None

(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

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:

jh2.0beta_install_dir/jh2.0/demos/hsjar/

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 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 merge type. This merging functionality as demonstrated is quite compelling, and for the first time in JavaHelp's history, merging multiple HelpSets with indexes becomes practical.

Figure 11: Merged index

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'

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:

  • TOC
  • Index
  • Search
  • Glossary
  • Favorites

The Glossary and Favorites view types are new in JavaHelp 2.0. (See Figure 13 below.)

Figure 13: New 'view' types: Glossary and Favorites

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

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:

  1. Add glossary term to HelpSet file (*.hs).
  2. Add map ID to map file (*.jhm).
  3. Create glossary definition as an HTML file.

Figure 15 shows the resulting HelpSet.

Figure 15: Holiday History sample HelpSet with 'Boxing Day' added to glossary

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 /jh2.0/demos/bin directory) contains a HelpSet with a favorites view. I opened the HelpSet and tried to add a topic to the favorites view. (The JavaHelp User's Guide does not contain any explicit information on how a user can add favorites to the favorites view.) I right-clicked within a topic, but nothing happened. (I had expected a pop-up menu.) I later discovered that the user must right-click within the navigation pane (not the content pane) when the desired topic is displayed. This behavior is counter-intuitive. I suspect that most users will not intuit that the mouse pointer must hover over the navigation pane (instead of the content pane) to right-click and select 'Add' (see Figure 16 below).

Figure 16: Adding a favorite topic via the context menu

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:

  • Back button - Previous topic
  • Favorites button - Add current topic to Favorites list
  • Forward button - Next topic
  • Home button - Loads home topic in content pane
  • Print button - Print
  • Print Setup button - Print Setup
  • Reload button - Reload current topic in the content pane
  • Separator - Create separator between buttons

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 and elements.

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

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 Demo

Figure 18: Java Development Environment - Online Help Demo

When 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

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.

Server-Based JavaHelp

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.

Server-based Demo

The 'serverhelp' demo is located in the following directory:

<install_dir>/jh2.0/demos/serverhelp

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:

../jh2.0/demos/serverhelp

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:
jakarta.apache.orgExternal link

However, only Tomcat is available on the defined site. Apache Ant is available on the following web site:
ant.apache.orgExternal link

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:

C:\JH2.0re-install\jh2.0\demos\serverhelp>C:\ant\apache-ant-1.5.3\bin\ant
    -Dcatalina.home=c:\jakarta_tomcat\jakarta-tomcat-4.0.6 all deploy
Buildfile: build.xml

clean:

prepare:
[mkdir] Created dir: C:\JH2.0re-install\jh2.0\demos\serverhelp\build
[copy] Copying 48 files to C:\JH2.0re-install\jh2.0\demos\serverhelp\build
[mkdir] Created dir: C:\JH2.0re-install\jh2.0\demos\serverhelp\build\WEB-INF
\lib
[copy] Copying 1 file to C:\JH2.0re-install\jh2.0\demos\serverhelp\build\WE
B-INF\lib
[unjar] Expanding: C:\JH2.0re-install\jh2.0\demos\hsjar\animals.jar into C:\
JH2.0re-install\jh2.0\demos\serverhelp\web\animals
[unjar] Expanding: C:\JH2.0re-install\jh2.0\demos\hsjar\vertebrates.jar into
C:\JH2.0re-install\jh2.0\demos\serverhelp\web\vertebrates
[unjar] Expanding: C:\JH2.0re-install\jh2.0\demos\hsjar\invertebrates.jar in
to C:\JH2.0re-install\jh2.0\demos\serverhelp\web\invertebrates

compile:
[mkdir] Created dir: C:\JH2.0re-install\jh2.0\demos\serverhelp\build\WEB-INF
\classes

all:

prepare:
[copy] Copying 124 files to C:\JH2.0re-install\jh2.0\demos\serverhelp\build

[unjar] Expanding: C:\JH2.0re-install\jh2.0\demos\hsjar\animals.jar into C:\
JH2.0re-install\jh2.0\demos\serverhelp\web\animals
[unjar] Expanding: C:\JH2.0re-install\jh2.0\demos\hsjar\vertebrates.jar into
C:\JH2.0re-install\jh2.0\demos\serverhelp\web\vertebrates
[unjar] Expanding: C:\JH2.0re-install\jh2.0\demos\hsjar\invertebrates.jar in
to C:\JH2.0re-install\jh2.0\demos\serverhelp\web\invertebrates

compile:

deploy:
[mkdir] Created dir: C:\jakarta_tomcat\jakarta-tomcat-4.0.6\webapps\JavaHelp
Demo
[copy] Copying 173 files to C:\jakarta_tomcat\jakarta-tomcat-4.0.6\webapps\
JavaHelpDemo
[copy] Copied 1 empty directory to C:\jakarta_tomcat\jakarta-tomcat-4.0.6\w
ebapps\JavaHelpDemo

BUILD SUCCESSFUL
Total time: 6 seconds
C:\JH2.0re-install\jh2.0\demos\serverhelp>

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:

http://<localhost>:8080/JavaHelpDemo

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

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

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

Figure 22: An alternate presentation of a server-based JavaHelp system

For Further Information    Link to the article Contents

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 JavaOneExternal link and are definitely doing a BOF (Birds Of a Feather—small 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.External link

Providing Feedback to the JavaHelp Team    Link to the article Contents

The JavaHelp listservExternal link 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 that—a 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:

  • The OS you're running (Windows 2000, Solaris 2.7, etc.).
  • The version of the Java SDK you have installed (note that JavaHelp 2.0 does not work with JDK 1.1.x).
  • Is the behavior reproducible? If so, provide the exact steps that cause the given behavior.
  • How does the behavior compare to JavaHelp 1.1.3?
  • What's the severity of the issue? Is it a "show-stopper" or a "nice-to-have," or somewhere in between?

After your posting on the listserv, you may be instructed by the JavaHelp team to file an official bug report.

In Summary    Link to the article Contents

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.

Resource Links    Link to the article Contents


URL Description

www.netbeans.orgExternal link

Netbeans is an open source organization that provides development tools based on the Java platform.

developer.java.sun.com/developer/earlyAccess
/javahelp/index.html
External link

Location for downloading the JavaHelp 2.0 Beta (requires free registration).

www.stc.org/50thConf/sesDayPage.asp?Day=4External link

STC's site on the upcoming 50th annual conference; a brief description of the 'Web Servers 101' presentation.

jakarta.apache.orgExternal link

ant.apache.orgExternal link

Apache is an open source organization that provides web servers, among other software tools.

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.


up