Help information files contain information about the content of the help system. The information includes:
The Table of Contents (TOC) file is an XML file that describes the content and layout of the table of contents. It is typically rendered as the Contents tab.
Table 7-1 describes the elements used in the table of contents file:
| Element | Description |
|---|---|
|
|
Defines the table of contents. This element contains
|
|
|
Defines a table of contents entry. A
|
The following example shows a short table of contents file:
<?xml version='1.0'?>
<toc version="1.0">
<tocitem text="Introduction to My Product">
<tocitem target="aboutmyp" text="About My Product" />
<tocitem target="architec" text="My Product Architecture" />
<tocitem target="feature1" text="About Feature One" />
<tocitem target="feature2" text="About Feature Two" />
<tocitem target="feature3" text="About Feature Three" />
<tocitem text="Learning My product">
<tocitem target="qtour" text="Quick Tour" />
<tocitem target="docguide" text="Guide to Documentation" />
</tocitem>
</tocitem>
<tocitem text="Step-by-step Procedures">
<tocitem text="Basic Tasks">
<tocitem target="task1" text="To..." />
<tocitem target="task2" text="To..." />
<tocitem target="task3" text="To..." />
</tocitem>
<tocitem text="Working with ...">
<tocitem target="task4" text="To..." />
<tocitem target="task5" text="To..." />
</tocitem>
</tocitem>
</toc>
This definition produces the following TOC hierarchy:
Introduction to My Product
About My Product
My Product Architecture
About Feature One
About Feature Two
About Feature Three
Learning My Product
Quick Tour
Guide to Documentation
Step-by-step Procedures
Basic Tasks
To...
To...
To...
Working with ...
To ...
To ...
The index file is an XML file that describes the content and layout of the index. It is typically rendered as the Index tab.
Table 7-2 describes the elements used in the index file:
| Element | Description |
|---|---|
|
|
Defines the index. It can contain |
|
|
Defines an index item that appears in the keyword list. Nesting index_item_1 within index_item_2 defines index_item_1 to be hierarchically contained within index_item_2, listed and indented below index_item_2 in the index. Oracle Help currently supports only two levels of keywords. The index view collapses any nesting beyond two levels. If an index item has more than one topic associated with it, the topics should be listed as index entries defined in The
|
|
|
Defines an index entry displayed in the topics list when the parent index item is selected in the index list. This tag uses the following attribute:
|
This example defines a very short index file:
<?xml version='1.0' ?>
<index version="1.0">
<indexitem target="Add_Icon"
text="Add Icon Command">
<indexitem target="addtosheet"
text="Adding an icon to a sheet />
<indexitem target="addtoworkbook"
text="Adding an icon to a workbook" />
</indexitem>
<indexitem target="Sheet_Background"
text="Adding a background to a sheet" />
<indexitem text="Adding a new sheet to a workbook">
<indexentry target="New_Sheet_command"
text="New Sheet Command />
<indexentry target="Add_new_sheet"
text="To add a new sheet to a workbook" />
</indexitem>
<indexitem target="Add_item_to_sheet"
text="Adding an item to a sheet" />
</index>
The file in the example above produces this index list:
Add Icon Command
Adding an icon to a sheet
Adding an icon to a workbook
Adding a background to a sheet
Adding a new sheet to a workbook
Adding an item to a sheet
If a user selects Adding a new sheet to a workbook from that list, a list of the following topics will be displayed:
New Sheet Command To add a new sheet to a workbook
This topic list appears at the bottom of the index pane, as opposed to indented topics, Adding an icon to a sheet and Adding an icon to a workbook, which show up in the keyword list at the top of the index pane.
Selecting a keyword that does not have index entries but has a directly associated target (for example, Adding an item to a sheet) displays the same text in the topics list as it does in the keyword list. Because of the way Oracle Help displays the index, it is a better practice never to use targets in the <indexitem> tags. Instead, always use the <indexentry> tags to specify topics associated with an <indexitem> -- even when there's only one target for a keyword.
In other words, the following code:
<indexitem text="sheet backgrounds">
<indexentry target="Sheet_Background" text="adding a background to a sheet" />
</indexitem>
...is better than the following code:
<indexitem target="Sheet_Background" text="adding a background to a sheet" />
The search index file is used when a user performs a text search in Oracle Help, ordinarily from the Search tab. This file uses a proprietary binary format. Any third-party help authoring tool that supports Oracle Help should be able to generate this file. In addition, the OHJDK includes two utilities that generate a search index file:
The Helpset Authoring Wizard provides limited authoring support, including generating search indexes. For more information, see Chapter 10, "Authoring Oracle Help Systems".
The Text Search Indexer is a Java command-line tool that generates search indexes. For more information, see Chapter 12, "Using the Text Search Indexer".
The link file is an XML file that defines link IDs and associates them with multiple topic IDs (which are defined in the map file). A link ID, or a link keyword, can be used with the alink protocol in a topic file to display a list of links to the topics associated with the ID. In other words, associative links make it possible to associate an HTML link with multiple targets. The user can then choose which target to follow.
Table 7-3 describes the elements used in the link file:
| Element | Description |
|---|---|
|
|
Defines the link file. The |
|
|
Defines the associative link. The
|
|
|
Defines an entry in the list of links displayed when an associative link is clicked. This element supports the following attributes:
|
The following example defines two associative links:
<?xml version='1.0' ?>
<link version="1.0">
<linkitem topic="dog_links">
<linkentry target="about_dogs" text="About Dogs" />
<linkentry target="dog_species" text="A List of Dog Species" />
<linkentry target="dog_stories" text="Dog Stories" />
<linkentry target="dog_lore" text="Dog Lore" />
</linkitem>
<linkitem topic="cat_links">
<linkentry target="about_cats" text="About Cats" />
<linkentry target="cat_species" text="A List of Cat Species" />
<linkentry target="cat_stories" text="Cat Stories" />
</linkitem>
</link>
Using the first link ID from that example, you could define a link <a href="alink:dog_links">dogs</a>. When a user selected the dogs link, the following list of links would be displayed:
Clicking About Dogs would display the topic mapped to the about_dogs ID in the map file.