7 Help Information Files

7.1.1 TOC Elements

Table 7-1 describes the elements used in the table of contents file:

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

7.2.1 Index Elements

Table 7-2 describes the elements used in the index file:

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

7.4.1 Link File Elements

Table 7-3 describes the elements used in the link file:

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:

About Dogs
A List of Dog Species
Dog Stories
Dog Lore

Clicking About Dogs would display the topic mapped to the about_dogs ID in the map file.