This chapter introduces the utilities and processes of authoring Oracle Help systems.
This topic contains the following sections:
Oracle Help does not include a complete authoring environment. While it is fairly straightforward to author a help system without using an authoring tool, you may prefer to use a tool that supports Oracle Help directly, such as Adobe RoboHelp, Quadralay WebWorks, or AuthorIT Software Corporation's AuthorIT.
Because Oracle Help's file formats are based on JavaHelp file formats, you could also start with any authoring tool that creates JavaHelp systems. However, you have to add features specific to Oracle Help manually. Oracle Help also supports the control file formats from Microsoft's HTML Help, so you could start with a help authoring tool that supports HTML Help. Again, you have to add any Oracle Help-specific features manually.
OHJ and OHW use the same file formats, so you can author a help system one time and display it without modification.
The basic steps for authoring an Oracle Help help system are as follows:
Write the HTML pages that comprise the topics of your help system.
Create a helpset file. This XML file identifies the help system and specifies many of its properties, including certain aspects of the user interface. For example, this is where you specify which "navigators" (generally displayed as tabs) are displayed. The standard navigators are Contents, Index, and Search. This is the main Oracle Help control file, and it is required.
Create a map file. This XML file maps topic IDs to HTML pages. These IDs are used in the API for context-sensitive calls; in table-of-contents, index, and link files; and in topic ID links in topic files. This file is required.
Create an index file. This XML file defines the keyword index that appears in the Index tab. If your help system does not have an index, this file is not required. However, if you do not have an index, you should not define an index tab in the helpset file.
Create a table of contents file. This XML file defines the table of contents that appears in the Contents tab. If your help system does not have a table of contents, this file is not required. However, if you do not have a table of contents, you should not define a Contents tab in the helpset file.
Generate a search index. This file contains the data used when a user searches for a word or phrase in the Search tab. This file is optional. However, if you do not have a text search index, you should not define a Search tab in the helpset file. If you are not using an authoring tool to create your help system, you can use the indexing tool, which is included with Oracle Help. See Using the Text Search Indexer.
If you want to use associative links, create a link file. This XML file associates topics with associative link keywords. This file is optional.
Two authoring utilities are included with Oracle Help for Java. You can use these tools to help author an Oracle Help system if you do not have an authoring tool that supports Oracle Help. Follow the links below for more information on each:
Helpset Authoring Wizard: This wizard converts certain noncompatible help content and control files into files that can be used by Oracle Help. For example, you can use the wizard to create an Oracle Help system from files generated by RoboHelp 2000 for Microsoft HTML Help.
Text Search Indexer: This utility generates the search index file used in Oracle Help when a user searches on a word or phrase in the Search tab.
As part of the embedded Help feature in OHW, each component in an application can have multiple levels of Help associated with it that get triggered on a certain user gesture. The levels of help are:
Definition Text
Instructions Text
Full Help
Each of these levels can be any arbitrary HTML content. Definition and Instructions Text are collectively referred to as Embedded Help Content. Full Help content is the content that appears as a separate topic in a Help window.
Definition Text is to be specified within a <div> with the hardcoded style class name definition. The title attribute, if present, represents the topic ID of the Definition Text. Note that only plain text can be entered here, HTML content is not processed for this <div> tag. For example,
<div title="topicId" class="definition"> Any plain text </div>
Instructions Text is to be specified within a <div> with the hardcoded style class name instructions. The title attribute, if present, represents the topic ID of the Instructions Text. For example,
<div title="topicId" class="instructions"> Any HTML content </div>
Definition and Instructions Text content for a topic are to be specified using typical HTML in a topic file as follows:
The <div> tags for the Definition Text and Instruction Text appear within the HTML body. It is required that the content for the both these levels of Help is specified in the same file. If either of them is not available in the same file, the content is assumed to be undefined.
Help authors specify the Definition Text and Instruction Text content for a topic ID in an existing topic HTML file. Here is a sample topic named topic1.html.
<html> <body> <div title="topic1" class="definition"> This is Definition Text help content. </div> ... <div title="topic1" class="instructions"> This is <b>Instructions Text</b> help content. </div> ... This is the regular Full Help content. ... </body> </html>
Note:
The title attribute represents the topic ID, and is optional. If not specified, the topic ID of the container HTML file is considered. If specified, it must match the topic ID of the HTML file in which the embedded Help is contained.
The <div> can appear anywhere within the <body>.
The definition and instructions style classes can be defined in the existing style sheet
The two style classes can be defined in such a way that they provide the necessary visual cues to distinguish them from the full Help content. For example, Help authors can use a light yellow background with a gray border to indicate Definition Text and a light blue background with a blue border to indicate Instruction Text. This is useful for creating and editing content.
The two style classes can be defined to be invisible (display:none) when Help authors must view the full Help content alone. This is useful for previewing.
HTML within a <div> that has either of the style class names is not indexed.