#
JavaHelpTM 1.0 - File Formats

## Copyright 1998-1999 Sun Microsystems

## Overview

The JavaHelp system defines the file formats for the meta data files: HelpSet file, Map file, and the data for the standard TOC and Index views. The file formats used in JavaHelp are based on industry standards:

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

The typical files involved in a HelpSet are:

- 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".

Tag | Description | Allowed In | Body | Attributes
--- | --- | --- | --- | ---
helpset | HelpSet definition | top-level | none |
`xml:lang`="lang" | Language for this item
`version`="1.0" | (optional) version

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

A HelpSet has a title that is used mostly in the presentation.

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

The following is an example of a map definition in a HelpSet file:

    <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

The following is an example of a view section in a HelpSet file:

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

### SubHelpSet Section

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"

## Map Files

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.

A Map can contain only the following two tags:

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

The following is an example of a table of contents file:

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

The following is an example of an index file:

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

JavaHelp displays help topic files formatted using HTML version 3.2. Links are resolved using the URL protocols supported by the underlying platform. Lightweight JComponents can be added to topic pages using the `<OBJECT>` tag.

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

JavaHelpTM 1.0
Send your comments to javahelp-comments@eng.sun.com
Last modified: Mon Apr 12 17:07:13 MDT 1999