Oracle® Fusion Middleware Developer's Guide for Oracle Help 11g Release 2 (11.1.2.2.0) Part Number E16280-03 |
|
|
PDF · Mobi · ePub |
This chapter describes the help information files (table of contents, index, and link files) used by OHJ and OHW. Help information files contain information about the content of the help system.
This chapter includes the following sections:
Help Information files can be categorized into three types, Table of Contents files, Index files, and Link files. All these files are XML files.
The Table of Contents (TOC) file is an XML file that describes the content and layout of the table of contents, and it is typically rendered as the Contents tab. Note that each helpset jar file must have one Table of Contents file.
If a helpset jar file contains several child helpsets, use the master Table of Contents file to control the content and layout of parent helpset's table of contents.
Table 6-1 describes the elements used in the table of contents file:
Table 6-1 TOC File Elements
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" image="prodIcon"> <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" image="prodIcon"> <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 ...
A master table of contents file controls the TOC structure of all child helpsets, and manages other table of contents files. You must declare the master table of contents before declaring helpset files.
To use a master table of contents, you must first configure the Oracle Help for the Web configuration file.
Declare master table of contents helpset file in the Oracle Help for the Web configuration file.
The following example shows a code extract from the configuration file:
<books> <helpSet id="master" location="master/src/helpset/master.hs"/> <helpSet id="ohguide" location="ohguide/src/helpset/ohguide.hs"/> <helpSet id="blafdoc" location="blafdoc/src/helpset/blafdoc.hs"/> <helpSet id="shake" location="shakespeare/src/helpset/shakespeare.hs"/> </books>
In the above example, the following code declares a master table of contents helpset file:
<helpSet id="master" location="master/src/helpset/master.hs"/>
Note that the master table of contents helpset file must be declared first before any other helpset files.
Create a master helpset file.
The entry for master table of contents helpset looks similar to any other TOC entry, as shown in the following code extract example of master.hs
file.
<view> <type>oracle.help.navigator.tocNavigator.TOCNavigator</type> <data engine="oracle.help.engine.XMLTOCEngine">toc.xml</data> </view>
Create a master table of contents XML file that defines the structure of all table of contents.
This master table of contents XML file looks similar to any other toc.xml
file, but it contains <tocfile>
elements. The <tocfile>
elements define the location of child table of contents XML files, as shown in the following example.
<toc version="1.0"> <tocitem text="Root"> <tocitem text="Some random node"> <tocfile location="ohguide/toc.xml" /> <tocfile location="javadoc/toc.xml" /> </tocitem> <tocfile location="blafdoc/toc.xml;shakespeare/shakespeare.hhc" /> </tocitem> <!-- All helpset toc files not explicitly declared in this file will be inserted under the following node. This includes toc files that are located in a subhelpset. --> <tocitem text="Extension Help Content"> <tocfile location="*" /> </tocitem> </toc>
Note that the master table of contents file controls the structure of the content, you must define your content through helpset files.
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 6-2 describes the elements used in the index file.
Table 6-2 Index File Elements
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 multiple topics 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 is 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 appears 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 9, "Authoring Oracle Help Systems".
The Text Search Indexer is a Java command-line tool that generates search indexes. For more information, see Chapter 11, "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 6-3 describes the elements used in the link file:
Table 6-3 Link File Elements
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.