Oracle Help File Formats	Contents	Previous	Next

Index File

The index file is an XML file that describes to the index navigator (typically rendered as the Index tab) the content and layout of the index. The following table describes the elements used in the index file:

Element Description

<index> Defines the index. It can contain <indexitem> and <indexentry> tags.

Element	Description
`<index>`	Defines the index. It can contain `<indexitem>` and `<indexentry>` tags.
`<indexitem>`	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 `<indexentry>` elements. The `<indexitem>` element has the following attribute: `target` - The topic ID (defined in the map file) of the topic to display when the entry is chosen by the user.
`<indexentry>`	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: `target` - The topic ID (defined in the map file) of the topic to display when the entry is chosen by the user.

<indexitem>

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

The <indexitem> element has the following attribute:

target - The topic ID (defined in the map file) of the topic to display when the entry is chosen by the user.

<indexentry>

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:

target - The topic ID (defined in the map file) of the topic to display when the entry is chosen by the user.

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.

Note that selecting a keyword that does not have index entries but instead has a directly associated target (for example, "adding an item to a sheet") will display the same text in the topics list as it does the keyword list. Because of the way Oracle Help displays the index, it is better practice never to use targets in <indexitem> tags and instead always use <indexentry> tags to specify topics associated with an <indexitem> -- even when there's only one target for a keyword.

In other words, this...


  <indexitem text="sheet backgrounds">
    <indexentry target="Sheet_Background"
        text="adding a background to a sheet" />
  </indexitem>

...is better than this:


  <indexitem target="Sheet_Background"
      text="adding a background to a sheet" />