Limitations and Bugs

HTML Viewer

The JavaHelp HTML viewer is based on the Swing JEditorPane component. HTML rendering differs somewhat depending on which version of Swing your application uses. Differences between versions are noted below.

Images Distorted

Occasionally, images are distorted (stretched). Redisplaying the page corrects the problem.

You can avoid this problem by explicitly specifying "height" and "width" attributes with the <IMG> tag.

Classpath Limitations

Due to Java security protocols, it is not possible to reference images and files from your topics that are outside the classpath of your application (or hsviewer). For example, if you start hsviewer with the following command:


   hsviewer -helpset C:\my_app\help\myhelpset.hs

The hsviewer command sets the classpath to be:


  C:\my_app\help

You cannot reference files above the C:\my_app\help folder. For example, in this case an image in C:\my_app\images referenced like this:


   <IMG SRC="../../images/foo.gif">

will not be displayed.

You can work around this problem by using the demos\bin\hsviewer1_1 command. This command allows you to specify the classpath separately from the HelpSet file, that way you can set the classpath to include the folder that contains the image and specify the HelpSet file relative to that folder. For example:


   hsviewer1_1 help\myhelpset.hs C:\my_app

Duplicate Lines Displayed (JDK1.2.2)

If a TOC, or index entry points to an anchor target specified at or near the top of the page (in the first scroll zone), Swing1.1.1 (also part of JDK1.2.2) positions the lines incorrectly, this results in lines being displayed twice.

Anchor Targets

Anchor targets (<A NAME="foo"></A>)are displayed in the center of the viewer display rather than at the top, as is the case in most browsers.
If the TOC or index is used to access a topic file that contains anchor targets within the first scroll zone in the viewer, text will be duplicated in the display.
Named anchors cause a space to be added at the beginning of the object that follows them.

The best way to work around this problem is to nest the anchor within a tag. For example:


   <H2>Working With Widgets<A NAME="widgets"></H2>

Cascading Style Sheets

Tag names in styles and style sheets must be specified using lowercase letters or they are ignored.

 and Tags

In some cases (for example, within <UL> and <OL> lists), the tag does not create the expected vertical space. In these cases, the tag does (incorrectly) create the expected vertical space.

The Tags (JDK1.2.2)

The tags are ignored on JDK 1.2.2 systems.

The Width Attribute of the <TD> Tag

The width attribute of the <TD> tag is ignored on JDK 1.2. The viewer assigns its own width to table columns.

On JDK 1.2.2, the width attribute works when specified in absolute pixels, the use of percentages is not supported.

Named Anchors in Ordered and Unordered Lists

If the first item after a list tag (<UL> <OL> <DL>) is a named anchor (<A NAME>), the list is rendered incorrectly:

This list is rendered incorrectly:


  <ul>
  <a name="17539"> </a>
  <li>Transmitter reports
  <a name="17540"> </a>
  <li>Channel reports
  </ul>

This one is rendered correctly:


  <ul>
  <li>Transmitter reports
  <a name="17539"> </a>
  <li>Channel reports
  <a name="17540"> </a>
  </ul>

TABS in <PRE> Tag not Recognized

TABS used in text within <PRE> tags are not recognized. Space characters are recognized correctly.

Viewer Cannot Load Image Files Directly

The help viewer aborts if you attempt to load a graphic file (*.gif, *.jpg) directly. The images must be included in an HTML file using the <IMG> tag.

Page Setup Settings not Preserved (Printing)

Changes made to the default settings in the Page Setup dialog box are not preserved between activations. The default settings are always set upon activation.

Null Pointer Exception (fixed in JDK1.2.2)

Due to a timing problem in the underlying Swing JEditorPane component, the following exception occurs occasionally:


   Exception occurred during event dispatching:
   java.lang.NullPointerException
      at javax.swing.text.View.preferenceChanged(View.java:121)
      at javax.swing.text.html.ImageView.run(ImageView.java:414)

This problem is benign.

Client-side Image Maps (fixed in JDK1.2.2)

The tags required to implement client-side image maps are not implemented (<MAP>, <IMG USEMAP>).

<TT> and <CODE> Tags (fixed in JDK1.2.2)

The <TT> and <CODE> tags do not change characters to a monospaced font. Also, other formatting tags (for example, , ) located within these tags are not recognized.

<OL> Tag After Headings (fixed in JDK1.2.2)

If the <OL> tag is used directly after a heading, the first number in the list is rendered in the same font as the heading. You can work around this by inserting a tag (for example, ) between the heading and the list.

Empty Entities (fixed in JDK1.2.2)

Using the tag to create empty entities such as:

   <DD><BR>
   <TD><BR></TD>

causes the following error:


   Exceptions occurred during event dispatching:
   javax.swing.text.StateInvariantError: infinite loop in formatting

Full-text Search

Parsing of Asian Languages

The JDK word-break iterator that the JavaHelp search indexer and search navigator use to parse Asian (Japanese, Chinese, Korean, Thai) languages uses a heuristic that is not well suited to searching. As a result, topic files are not parsed into words that users are likely to enter into the Find input field.

However, because the parser works on the same model that is used to highlight words when the user double-clicks in the content pane, as a workaround (albeit an inconvenient one) the Asian language user can conduct a full-text search using the following process:

Double-click on words in the content pane
Copy/paste them into the search navigator Find field
Press Return

Match Limit

To enhance full-text search performance in this release, the search navigator only reports the 100 most relevant matches. For example, in the idedemo program, if you search for the word "build", you will notice that different forms of the word (builder, built, builds) are not highlighted because the 100 match limit was met with the exact match "build". This should not be a problem with more complex, multi-word, natural language queries.

NullPointerException in Search Navigator

A NullPointerException sometimes occurs when search results are displayed. This can be ignored, program execution proceeds normally.

jhindexer Does Not Parse "." Correctly

The jhindexer does not treat the "." character correctly. As as result, a search for "javax.help" in the apiviewer returns no matches.

Context Sensitive Help

Field-level help ActionListener (JDK 1.1)

The field-level help ActionListener in the default implementation of the HelpBroker is disabled for JDK 1.1. JDK 1.1 doesn't allow the creation of custom cursors and doesn't support a predefined question-arrow cursor. Developers who want to support field-level help on JDK 1.1 can implement a field-level ActionListener that sets the cursor to one of the predefined cursors in java.awt.Cursor and then follow the steps described in the JavaHelp System User's Guide chapter "Implementing Context-Sensitive Help".

Field-Level Help Button

In the idedemo, if the field-level help button is clicked before the help viewer has been accessed (for example, Help->Demo JDE Help), a NullPointerException occurs.

F1 Help (Solaris OpenWindows)

On Solaris OpenWindows manager the F1 key does not get help on the the component with focus.

Limitations on Running in Web Browsers

It is only possible to use the JavaHelp system in applets running in web browsers using JRE/JDK1.1.6 or later with the Java Plug-in.

JavaHelp does not run correctly in web browsers and the appletviewer due to a limitation in Swing 1.1. This limitation will be corrected in a future version of Swing. In the meantime, a description of how to work around this issue will be posted to the JavaHelp website.

Other Bugs

Copy/Paste on Solaris

On Solaris systems, follow these steps to copy and paste text from the help viewer:

Highlight text in the viewer
Type Control-C to copy the text
With focus in the target Solaris window, press the Paste key

jar: Protocol

Due to a bug, the Java^TM 2 SDK jar: protocol does not permit relative references to JAR files--they must be fully qualified. For example, the following works correctly:

   jar:file://c:/my_app/help.jar!map.jhm

There is no way to make that reference relative from the location of a HelpSet file. For that reason, you must include the HelpSet and map files in the JAR file with the rest of the HelpSet.

Index Navigator

If an index entry contains more that two hierarchical levels, a "turner" mechanism (like the one used in the TOC) is added to the second +n levels.

Popup Window Accessibility

JavaHelp popup windows are not as accessible as they should be due to a bug in the underlying AWT classes that prevents the popups from obtaining focus. Popup windows can be accessibly dismissed by pressing the F10 key -- the Esc key does not work because the window cannot obtain focus. In addition, this same bug prevents scrollbars in popup windows from being accessible from the keyboard, therefore it is important to set the size of popups so that all the information can be displayed in a single scroll zone.

Fonts/Localization

There are limitations in this release on the ability to display fonts in the help viewer content pane. Due to a bug in the JDK, the only character encoding that can be displayed in the HTML content pane is the system default. Different locales that use that encoding are rendered correctly.

Installation

If you uninstall the JavaHelp release while you are viewing any of the release directories (using Explorer, the MSDOS command prompt, or Solaris shell), the directories are not removed.