JavaHelp^TM 1.0 - File Formats

Copyright 1998-1999 Sun Microsystems

Overview

• The HelpSet (help content and meta information) is encapsulated and compressed using the JAR (Java Archive) format.
• Map, table of contents and index file models are described in XML.
• The HelpSet file is based on the Extended Markup Language (XML) as defined by the World Wide Web Consortium (http://w3c.org/XML/).
• Localization is done following the I18N Java conventions.

JavaHelp provides for an extensible set of navigational types, but predefines a few types.   The standard types are:

• javax.help.TOCView for the Table of Contents.
• javax.help.IndexView for the Index.
• javax.help.SearchView for the Search.

• HelpSet file: Identifies the map, and navigational views (e.g. TOCs, indexes and search database files).
• Map file(s): Defines the map that associates topic IDs used by the application to refer to HTML topic files.
• Table of contents: Defines the table of contents entries, their structure, and the IDs to which they map
• Index: Defines the index entries and the IDs to which they map
• Search Database: The search database searched by the search engine. The default search database is created using the JavaHelp system jhindexer command.
• Content: The HTML topic files that provide information to help users

Document Type Definitions (DTDs) for HelpSet, Map, TOC View and Index View data are included in this specification and can be used for validation. In each of these cases, the valid documents are those valid XML documents conformant with the DTD except that the DOCTYPE section must not have any inner DTD subset (this is the same restriction used in the W3C SMIL recommended specification).

JAR is used to encapsulate and compress a HelpSet into a single file. Encapsulation and compression are not required, but recommended in most production environments.

HelpSet File

The HelpSet file is localized following the same naming conventions used with ResourceBundle. Once a HelpSet file for a given locale has been found, no additional localization searches are needed, which is very important in a networked environment.

Format

HelpSet files are encoded in an XML-based syntax; The DTD is dtd/helpset_1_0.dtd. The top level tag is <helpset>. A version attribute is optional, when present its value must be "1.0".

The HelpSet file is organized into sections within the <helpset> tag. There is a section for ID maps, sections for the navigational views, and a final section for subhelpsets. The general outline of a HelpSet file is:

   

    <?xml version='1.0' encoding='ISO-8859-1' ?>
    <!DOCTYPE helpset
      PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"
             "http://java.sun.com/products/javahelp/helpset_1_0.dtd">

    <!-- next is a Processing Instruction (PI).
      This is ignored by the Reference Implementation -->
    <?MyFavoriteApplication this is data for my favorite application ?>

    <helpset version="1.0">

	<!-- Global properties -->
	<title>My Title</title>

	<!-- maps section -->
	<maps>
	    <homeID>my homeID</homeID>
	    <mapref location="url"/>
	</maps>

	<!-- Zero or more View sections -->
	<view>
	    <name>TOC</name>
	    <type>javax.help.TOCView></type>
	    <data>jar:file:/c:/Program Files/JW3.0/JW3.0.jar!/TOC.xml</data>
	</view>

	<!-- Optional subHelpSet section >
        <subhelpset location="file:/c:/Foobar/HelpSet1.hs"/>
    </helpset>

Whenever a relative URL specification appears in a HelpSet, it is to be interpreted relative to the URL of the HelpSet (note that the constructor for a HelpSet takes a URL).

Processing Instructions

The reference implementation ignores the Processing Instructions.

HelpSet properties

Tag	Description	Allowed In	Body	Attributes
title	Title of the HelpSet	helpset	Actual title	none

ID Map Section

The second section of a HelpSet file contains information on the mapping of IDs to URLs used for context sensitive help. The homeId tag provides the default entry to present when a HelpSet is first shown. The mapref tag provides a reference to a map file.

Tag	Description	Allowed In	Body	Attributes
maps	Map definition	helpset	empty	none
homeID	Default ID of the HelpSet	maps	ID string	none
mapref	URL to map	maps	empty	location, the spec relative to HelpSet

Finally, an ID Map section corresponding to a Bean will want to include a topic ID corresponding to the BeanInfo.getHelpId(). If there is a single Bean for this HelpSet file, the value of <homeID> could be used. If several Beans share the HelpSet file, several topic IDs are needed

Map Example

<map>
   <data>jar:file:/c:Program Files/JWS3.0/JW3.0.jar!/TheMap.map</data>
   <data>jar:http://www.sun.com/devpro/JWS3.0Encyclopedia.jar!/TheMap.map</data>
</map>

NOTE: There is a bug in the JavaHelp 1.0 reference implementation which only supports one map.

Navigational Views Section

The final sections of a HelpSet file describe the navigational views, which include tables of contents, indices, and search. There are three mandatory tags for each view: <label>, <name>, and <type>. Additionally, most views will define <data>.

Tag	Description	Allowed In	Body	Attributes
view	View definition	helpset	none	xml:lang
name	a name identifying the view	view	text of the name	none
label	a label to show in the presentation	view	text for the label	none
type	a subclass of NavigatorView	view	name of the class	none
data	URL spec	view	text of the spec	optional "engine", a class implementing SearchEngine

The language specified in the xml:lang attribute of name must not be different that of the view, if that was given explicitly. The language specified in the xml:lang attribute of view must not be different to that the HelpSet, if that was given explicitly.

View Example

<view>
   <name>TOC</name>
   <name>Table of Contents</name>
   <type>javax.help.TOCView</type>
   <data>jar:file:/c:Program Files/JWS3.0/JW3.0.jar!/toc.xml</data>
</view>

A HelpSet file can statically include other HelpSets using the <subhelpset> tag. The HelpSets indicated using this tag are merged automatically into the HelpSet where the tag is included. If the URL spec refers to a non-existing file, the subhelpset tag is silently ignored; this permits an enclosing HelpSet to refer to subhelpsets that may or not be installed. More details about merging can be found in Merge.

Tag	Description	Allowed In	Body	Attributes
subhelpset	Static subHelpSet to merge	helpset	empty	location="URL spec to HelpSet file"

Each map file provides a mapping of topic IDs to URLs. Map files are encoded in an XML-based syntax; The DTD is dtd/map_1_0.dtd. The top level tag is <map>. A version attribute is optional, when present its value must be "1.0".

The main tag is mapID relating a topic ID and a URL specification. Relative URL specifications are to be resolved against the absolute URL for the map file.

Tag	Description	Allowed In	Body	Attributes
map	A Map	top level	empty	xml:lang="lang" Language for this item version="1.0" (optional) version
mapID	An individual map entry	empty	map	target="string" ID url="string" URL spec xml:lang="lang" Language for this item

The following is an example of a simple map file:

<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE map
  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN"
         "http://java.sun.com/products/javahelp/map_1_0.dtd">

<map version="1.0">

    <mapID target="intro" url="hol/hol.html" />
    <mapID target="halloween" url="hol/hall.html" />
    <mapID target="jackolantern" url="hol/jacko.html" />
    <mapID target="mluther" url="hol/luther.html" />
    <mapID target="reformation" url="hol/inforefo.html" />
</map>

Note that the IDs should be unique within the HelpSet (although they may also appear in a subhelpset of this HelpSet).

Table of Contents

JavaHelp1.0 specifies one table of contents type: javax.help.TOCView. This navigational view models a table of contents. TOC files are encoded in an XML-based syntax; The DTD is dtd/toc_1_0.dtd. The top level tag is <toc>. A version attribute is optional, when present its value must be "1.0".

A TOC can contain only the following two tags:

Tag	Description	Allowed In	Body	Attributes
toc	Table of contents	top level	empty	xml:lang="lang" Language for this item version="1.0" (optional) version
tocitem	Table of contents item. Tags can be nested to create hierarchical entries.	Text to show in the presentation	toc, tocitem	target="string" destination ID image="string" destination ID xml:lang="lang" Language for this item

Table of Contents Example

<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE toc
  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 1.0//EN"
         "http://java.sun.com/products/javahelp/toc_1_0.dtd">

<toc version="1.0">
   <tocitem>Introducing JavaHelp
      <tocitem target="api" image="image/document.gif">
         JavaHelp API
      </tocitem>
      <tocitem target="platform" image="image/document.gif">
         JavaHelp platforms
      </tocitem>
   </tocitem>
</toc>

Index

JavaHelp1.0 specifies one index navigator view: javax.help.IndexView. This navigational view models an index. Index files are encoded in an XML-based syntax; The DTD is dtd/index_1_0.dtd. The top level tag is <index>. A version attribute is optional, when present its value must be "1.0".

An index can contain the following two tags:

Tag	Description	Allowed In	Body	Attributes
index	Index	top-level	empty	xml:lang="lang" Language for this item version="1.0" (optional) version
indexitem	Index item. indexitem tags can be nested to create hierarchical entries.	index, indexitem	text to show in the presentation	target="string" destination ID xml:lang="lang" what language to use

Index Example

<?xml version='1.0' encoding='ISO-8859-1'  ?>
<!DOCTYPE index
  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 1.0//EN"
         "http://java.sun.com/products/javahelp/index_1_0.dtd">
<index version="1.0">
   <indexitem>Java Applets
      <indexitem target="applet_over">
         Overview
      </indexitem>
      <indexitem>Usage
         <indexitem target="applet_insert"> 		   
            Inserting an applet in a content page
         </indexitem>	
         <indexitem target="applet_editing">
            Editing an applet in a content page
         </indexitem>	
      </indexitem>
   </indexitem>
</index>

Help Content

Search Database

JavaHelp1.0 specifies one search navigator view: javax.help.SearchView. This navigational view models a search interacting with a search database though objects that implement the javax.help.search package. The view has an <engine> tag that is the name of a class that is a subclass of SearchEngine. That class is responsible for interpreting the search database that is described by the URL in <data>.