C Working With HelpBooks

This appendix describes how older versions of OHJ used the helpbook file and the HelpBook object. Helpbooks are still supported in current versions of OHJ; however, it is preferable in current versions to use helpsets (helpset file and HelpSet object).

If you are still using helpbook file and object, and do not wish to use helpsets, the following sections provide helpbook specific information.

This appendix includes the following sections:

Section C.1, "HelpBook File Name Extensions"
Section C.2, "Adding the Help Data in OHJ"
Section C.3, "Locales in Oracle Help for the Web Configuration File"

C.1 HelpBook File Name Extensions

If you are using helpbooks, you must ensure that file name and extensions are correct. OHJ and OHW look in a specified directory for files with file name extensions that correspond to the supported file formats, including TOC, TOK, HHC, HHK, OHT, and IDX. For more information about correct file name and extensions, see Section 4.2, "File Name Extensions"

When you use helpsets, you don't have to use specific extensions for the names of the associated control files.

C.2 Adding the Help Data in OHJ

If you want to add a helpbook in OHJ, you must first create a Help object. For more information, see Section 13.2, "Constructing the Help Object".

Note:

When an OHJ system is implemented using a HelpBook, the map file must use the OHT file format. HelpBooks and OHT files are legacies from early versions of OHJ and are no longer recommended, but they are still supported by OHJ. For more information about the map file, see Section 5.3, "Map Files".

After creating a Help object, you must add one or more Book objects to it. A Book object encapsulates a collection, or a book of help content.

This HelpBook book implementation handles legacy OHJ file formats. The HelpBook class examines a directory, identifies files with known extensions, and adds them to the help system.

The following sections describe how to add the helpbooks, and other optional features:

Section C.2.1, "Constructing a HelpBook"
Section C.2.2, "Adding Books to Help"

For more information, see the API documentation for oracle.help.library.helpset.HelpSet.

C.2.1 Constructing a HelpBook

The HelpBook format is directory based. Use its constructors to specify the location of the directory containing the help content (HTML topic files).

Table C-1 HelpBook() Constructors

Constructor Description

Constructor	Description
`HelpBook(String baseURL, String baseName, String bookTitle)`	Create a `HelpBook` with the specified title, loading the data from the directory location specified by `baseURL`. The `HelpBook` object examines the directory to identify known control files (TOC, TOK, HHC, HHK, OHT, and IDX) named with the given `baseName`. Use this constructor when you know the exact location of the help content directory. Parameters: `baseURL` - A String specifying the exact location of the helpset file in URL format. `baseName` - The base name of the control files found in the specified directory (for example, if your control files are named userguide.hhc, userguide.hhk, etc., the `baseName` is `userguide`). `bookTitle` - The book name that will appear in the book selection pull down menu in multiple book help systems. The title is often supplied by the help author.
`HelpBook(Class baseClass, String dirPathExt, String baseName, String bookTitle)`	Create a `HelpBook` with the specified title, loading the data from the directory location specified by `baseClass` and `dirPathExt`. The `HelpBook` object examines the directory to identify known control files (TOC, TOK, HHC, HHK, OHT, and IDX) named with the given `baseName`. Use this constructor when you know only the path to the help content directory relative to your application implementation. Parameters: `baseClass` - One of your application classes. The `HelpBook` object uses the location of this class to determine the location of your help content directory. `dirPathExt` - The path to the help content directory relative to the location of `baseClass`. The value of this parameter is appended to the absolute path to the directory containing the `baseClass`. The resulting path should be the path to your help content directory. `baseName` - The base name of the control files found in the specified directory (i.e. if your control files are named `discoverer.hhc`, `discoverer.hhk`, etc., `the baseName` would be `discoverer`). `bookTitle` - The book name that will appear in the book selection pull down menu in multiple book help systems. The title is often supplied by the help author.

HelpBook(String baseURL, String baseName, String bookTitle)

Create a HelpBook with the specified title, loading the data from the directory location specified by baseURL. The HelpBook object examines the directory to identify known control files (TOC, TOK, HHC, HHK, OHT, and IDX) named with the given baseName. Use this constructor when you know the exact location of the help content directory.

Parameters:

baseURL - A String specifying the exact location of the helpset file in URL format.
baseName - The base name of the control files found in the specified directory (for example, if your control files are named userguide.hhc, userguide.hhk, etc., the baseName is userguide).
bookTitle - The book name that will appear in the book selection pull down menu in multiple book help systems. The title is often supplied by the help author.

HelpBook(Class baseClass, String dirPathExt, String baseName, String bookTitle)

Create a HelpBook with the specified title, loading the data from the directory location specified by baseClass and dirPathExt. The HelpBook object examines the directory to identify known control files (TOC, TOK, HHC, HHK, OHT, and IDX) named with the given baseName. Use this constructor when you know only the path to the help content directory relative to your application implementation.

Parameters:

baseClass - One of your application classes. The HelpBook object uses the location of this class to determine the location of your help content directory.
dirPathExt - The path to the help content directory relative to the location of baseClass. The value of this parameter is appended to the absolute path to the directory containing the baseClass. The resulting path should be the path to your help content directory.
baseName - The base name of the control files found in the specified directory (i.e. if your control files are named discoverer.hhc, discoverer.hhk, etc., the baseName would be discoverer).
bookTitle - The book name that will appear in the book selection pull down menu in multiple book help systems. The title is often supplied by the help author.

C.2.2 Adding Books to Help

Once you have constructed a Book instance using the HelpBook or HelpSet constructors, you must add the Book to your Help instance. This is accomplished by calling the following method on the Help instance:

Table C-2 addBook() Constructors

Constructor Description

Constructor	Description
`addBook(Book book)`	This method adds a `Book` instance to the help system. Author-defined views contained in the `Book` are displayed in the navigator window, and topics from the `Book` are available to display. Parameters: `book` - The `Book` instance to add to the help system.

addBook(Book book)

This method adds a Book instance to the help system. Author-defined views contained in the Book are displayed in the navigator window, and topics from the Book are available to display.

Parameters:

book - The Book instance to add to the help system.

C.3 Locales in Oracle Help for the Web Configuration File

While configuring Oracle Help for the Web configuration file (ohwconfig.xml) for locale, you can specify a single locale or multiple locales in the <locales> section.

For more information on configuration file, see Chapter 8, "Oracle Help for the Web Configuration File".

C.3.1 The <locale> Child Element <books>

The <books> element specifies the content to be displayed in Oracle Help for the Web. The <books> element can contain any number of helpbooks, or a combination of helpsets and helpbooks. Helpsets and helpbooks are also called as books.

Table C-3 describes the <helpbook> child element:

Table C-3 <books> Child Elements

Element Description

Element	Description
`<helpBook>`	The helpbook to include in this instance of OHW. This element has the following attributes: `id` – Unique id to this book. This attribute is required. `basename –` The name, without the file name extension, of the control files in the directory. For example, if the control files are named `myproject.hhc`, `myproject.hhk`, `myproject.idx`, and so on, the basename is `myproject`. `location` – The location of the helpbook file. The path can be either absolute or relative to the location of the OHW configuration file. `title` – The title to use when if helpbooks or helpsets are merged. The helpbook is displayed in the merged book list in the OHW user interface. By contrast, this title is set in the `<title>` element in the helpset file for a helpset. `controlFileencoding` – A Java-supported encoding name. The set of supported encodings varies with JDK version. For a list of supported encodings for Java SE, see `http://download.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.html`.

<helpBook>

The helpbook to include in this instance of OHW. This element has the following attributes:

id – Unique id to this book. This attribute is required.
basename – The name, without the file name extension, of the control files in the directory. For example, if the control files are named myproject.hhc, myproject.hhk, myproject.idx, and so on, the basename is myproject.
location – The location of the helpbook file. The path can be either absolute or relative to the location of the OHW configuration file.
title – The title to use when if helpbooks or helpsets are merged. The helpbook is displayed in the merged book list in the OHW user interface. By contrast, this title is set in the <title> element in the helpset file for a helpset.
controlFileencoding – A Java-supported encoding name. The set of supported encodings varies with JDK version. For a list of supported encodings for Java SE, see http://download.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.html.

For example:

<books>
 <helpBook id="disco" baseName="discoverer" location="discoverer/" title="Discoverer Help" />
</books>

The <helpbook> elements can contain zero or more <contentLocation> elements for situation when help topic files are located in locations other than those expected by Oracle Help.

For more information about other child elements of <books>, see Section 8.4.1, "<books> Child Elements".

C.3.2 The <contentLocation> Element

By default OHW automatically processes help topic files that are located in the same locations as helpbook base directories.

In helpbooks, OHW processes help topic HTML files:

in the helpbook base directory and subdirectories under that location
or if the helpbook is in a JAR file, all help topic files in the same JAR

If you have help topic files in some other location, you must use the <contentLocation> element to point to that location.

The <contentLocation> element has the attribute baseURI. It represents a URI to the root location of a set of help content, using a path that is either absolute or relative.

The <contentLocation> element can be a child of <helpbook>. A <helpbook> can contain zero or more <contentLocation> elements.

This element is needed because, unlike plain HTML files, Oracle Help help topic files must be processed by the servlet in order to be displayed. Therefore, it is necessary to explicitly list the locations where help topic files referenced in the helpbook reside, if they are not in the default locations. This can happen if your helpset includes a subhelpset in another location or even on another web server or if your context sensitive map file contains references to help topic files located elsewhere on the same server or on a different server.

For more information, see Section 8.4.2, "The <contentLocation> Element".