E-Mail Address: Roger.Brinkley@Sun.Com

Telephone Number: 719-488-5657

Fax Number: none

Specification Lead: Roger D. Brinkley

E-Mail Address: Roger.Brinkley@Sun.Com

Telephone Number: 719-488-5657

Fax Number: none

Initial Expert Group Membership:

Endorsers:

Section 2: Request

2.1 Please describe the proposed Specification:

The proposed Specification is an enhancement to the existing JavaHelp 1.0 Specification. Additional APIs and file formats are proposed to improving merging, printing, secondary windows and popups, dynamic Context Sensitive Help, JFC ToolTip support, HelpSet presentation controls, and additonal Navigators.

2.2 What is the target Java platform? (i.e., desktop, server, personal, embedded, card, etc.)

Desktop

2.3 What need of the Java community will be addressed by the proposed specification?

Merging

The current JavaHelp Specification supports the concept of merging. However, it is not possible to control the way navigator data is merged without additional attributes in the file formats and possible additions to the Navigator APIs. In the current reference implementation the navigator data in sub-HelpSets is appended to Navigator data in the master HelpSet. While this is somewhat acceptable for Table of Contents Navigators, it is an inferior implementation for Index Navigators. The proposed specification would allow the Navigator data to be either merged, appended and sorted.

Printing

Printing support is not defined in the current specification but has been implemented in the reference implementation. It allows for single page printing of the current ID. Users have requested the ability to print multiple pages. Potentially this requires API changes in the JHelp class and the proposed JHelpToolbar class to allow support of multiple page printing.

Secondary Windows and Popups

In the reference implementation Secondary Windows and Popups are only activated from the JHelpContentViewer. Users have requested the ability to have help displayed in a lightweight Secondary Window or Popup when activated from either the application, navigator, or Context Sensitive Help (CSH). This requires API changes as well as file format changes to the Navigator file formats.

Dynamic Context Sensitive Help (CSH)

In the current specification CSH is activated by setting an ID on a particular component. Users have requested a method or callback by which they can dynamically set the ID for a given component.

Tooltips

JDK1.3 provides for HTML content in ToolTips. JFC ToolTips are set with the method JComponent.setToolTipText(String) -- users have requested a methodology that allows the ToolTip content to be within the HelpSet.

Toolbar

Users have requested for more control over the JHelp Toolbar in the JHelp component. Such control would be accomplished through a new JHelpToolBar component and with additonal HelpSet presentation controls. The JHelpToolBar component would complement the existing JavaHelp JHelp, JHelpContentViewer, JHelpTOCNavigator, JHelpIndexNavigator, and JHelpSearchNavigator components.

Presentation Control

Users have requested a greater degree of control over the presentation by defining attributes in the HelpSet. Specifically, they have requested control over:

• The initial size and location of the JavaHelp viewer
• The initial state (compressed or expanded) of navigation entries
• Navigator icon in the navinfo tag of a HelpSet
• The text of the tooltips displayed for components in the JavaHelp viewer

Navigators

Users have requested additional navigators to provide session history, bookmarking of content pages visited, and a glossary. To implement these Navigators additional JHelpNavigator classes would be established along with the associated Views and file formats for the data where appropriate. Additionally, there has been a request to allow subitems within an Index.

Dynamic Update

There have been multiple requests for functionality that makes it possible to dynamically create or update HelpSets, help content, and Navigator data. The current specification only supports static creation of this data or content. Implementation of this request requires API changes to the HelpSet, JHelpContentViewer, Views and Navigators.

2.4 Why isn't this need met by existing specifications?

The existing JavaHelp 1.0 Specification does not fully address the areas of merging, printing, secondary windows and popup, dynamic CSH, JFC ToolTip support, HelpSet presentation controls, or additional Navigators.

2.5 Please give a short description of the underlying technology or technologies:

JavaHelp software is a full-featured, platform-independent, extensible help system that enables developers and authors to incorporate online help in applets, components, applications, operating systems, and devices. Authors can also use the JavaHelp software to deliver online documentation for the Web and corporate Intranet.

2.6 Is there a proposed package name for the API Specification? (i.e., javapi.something, org.something, etc.)

javax.help is the current package name for the JavaHelp Specification.

2.7 Does the proposed specification have any dependencies on specific operating systems, CPUs, or I/O devices that you know of?

None

2.8 Are there any security issues that cannot be addressed by the current security model?

None

2.9 Are there any internationalization or localization issues?

Internationalization and localization are properly addressed in JavaHelp 1.0 Specification.

2.10 Are there any existing specifications that might be rendered obsolete, deprecated, or in need of revision as a result of this work?

No

2.11 Please describe the anticipated schedule for the development of this specification.

Section 3: Contributions

3.1 Please list any existing documents, specifications, or implementations that describe the technology. Please include links to the documents if they are publicly available.

• JavaHelp 1.0 Specification http://java.sun.com/products/javahelp/download_spec.html
• JavaHelp-Interest archives http://archives.java.sun.com/archives/javahelp-interest.html

3.2 Explanation of how these items might be used as a starting point for the work.

The JavaHelp 1.0 Specification serves as current specification of record for JavaHelp. The JavaHelp-Interest archives is an archive of the JavaHelp-Interest mailing list that supports many of the changes that are requested in this proposal.