## Limitations and Bugs

This release of JavaHelp has the following limitations and bugs.

### HTML Viewer

The JavaHelp HTML viewer is based on the Swing JEditorPane component. HTML rendering can differ 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 sometimes avoid this problem by explicitly specifying "height" and "width" attributes with the `<img>` tag. For example,

`<img src="../../images/hg_note.gif" width="18" height="13">`

#### 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, you start `hsviewer` with the following command:

`java -jar c:\JavaHelp\demos\bin\hsviewer.jar -helpset C:\my_app\help\myhelpset.hs`

The `hsviewer` application sets the `CLASSPATH` to be:

`C:\my_app\help`

You cannot reference files above the `C:\my_app\help` folder. For example, in the following code an image in `C:\my_app\images` referenced as follows cannot be displayed:

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

You can work around this problem by using the `-classpath` parameter of `hsviewer.jar`. The parameter allows you to specify a `CLASSPATH` separately from the helpset file, enabling you to set the `CLASSPATH` to include the folder that contains the image and specify the helpset file relative to that folder. For example, you could enter the following command (all on one line) at the command line:

        java -jar c:\JavaHelp\demos\bin\hsviewer.jar -helpset C:\my_app\help\myhelpset.hs
        -classpath C:\my_app

#### Duplicate Lines Displayed (J2SE 1.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), the viewer can position the lines incorrectly, resulting in lines' being displayed twice.

#### Anchor Targets

There are two problems with anchors:

- On J2SE 1.2.2 systems only, if the TOC or index is used to access a topic file that contains anchor targets in 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 text of the target within the anchor tag. For example:

`<H2><a name="widgets">Working With Widgets</a></H2>`

#### Cascading Style Sheets

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

#### `<sup>` and `<sub>` Tags (J2SE 1.2.2)

The `<sup>` `<sub>` tags are ignored on J2SE 1.2.2 systems.

#### The Width Attribute of the `<td>` Tag

The width attribute of the <td> tag is ignored in J2SE 1.2. That version of the viewer assigns its own width to table columns.

On J2SE 1.2.2, the width attribute works when specified in absolute pixels (px). The use of percentages (%) is not supported in that version of J2SE.

#### Named Anchors in Ordered and Unordered Lists

If the first item after a list tag (`<ul>`, `<ol>`, or `<dl>`) is a named anchor (`<a name>`), the list shown in the following example is rendered incorrectly:

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

The following list is rendered correctly:

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

#### TABS in `<pre>` Tag not Recognized

TABS used in text enclosed in `<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. You must include the images in an HTML file by 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.

### Full-text Search

The text search feature, implemented by running `jhindexer` on your helpset, has the following limitations and bugs.

#### Parsing of Asian Languages

The J2SE 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 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 as follows:

1. Double-click a word in the content pane.
2. Copy and paste the word into the search navigator Find field.
3. Press Return.

#### Match Limit

To enhance full-text search performance, the search navigator reports the 100 most relevant matches. For example, in the `idedemo` program, if you search for the word "build", you see 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 limit should not be a problem with more complex, multi-word, natural language queries.

#### 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

#### F1 Help (Solaris OpenWindows)

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

### Other Bugs

#### Copy/Paste on Solaris

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

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

#### `jar:` Protocol

Due to a bug, the JavaTM 2 SDK `jar:` protocol does not permit relative references to JAR files. Instead, they must be fully qualified. For example, the following code 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 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 to enable all the information to be displayed in a single scroll zone.

#### Fonts and 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 J2SE, 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. `