Web Help - Index Entries

Index Entries

An index is a valuable addition to a Web-based help system. You can include entries for topics that users need to know about, and link them directly to the most appropriate paragraph in the help.

The following procedure describes how to add an index to a help system. This is designed to meet the following objectives:

Index entries are embedded in the source of the help pages, so even if text is edited at a later stage, the index will still work correctly.
Each index entry encloses text in the document that will be highlighted when the user clicks the index entry.

Inserting index entries

The approach I've used here is to use standard "a name=" tags to encode the index entries. The advantage of this is that the tags are recognised by Web development tools, like Dreamweaver, and don't require any special JavaScript to make the index work.

The index entry encoding scheme I propose allows three different types of index entry to be inserted:

Single index entry

To add an entry into the index for text occurring in the document, enclose the text in a "a name=" tag. For example, suppose you had the heading:

<h2>Defining spots</h2>

you could add an entry "Defining spots" by changing this to:

<h2><a name="a05-1" id="a05-1">Defining spots</a></h2>

Note that we set both the name parameter and the id parameter to the same, unique identifier for the index entry. I use the file number followed by an incremented index entry number, so the entries for file 05 are:

a05-1, a05-2, a05-3, ... etc.

The a prefix is required because ids cannot start with a digit.

Note that if you insert the anchor from a web design tool, such as Dreamweaver, you'll probably end up with an empty anchor like this:

<h2><a name="a05-1" id="a05-1"></a>Defining spots</h2>

This has the same effect as far as the browser is concerned, but doesn't allow us to define what text we want to have highlighted when going to the anchor; see below.

Hidden index entries

To add an entry into the index that doesn't occur in the document enclose the entry in:

<span style="display:none;">...</span>

For example, it would be more useful to index the section "Defining spots" under the entry "Spots, defining". We can do this as follows:

<h2>
  <a name="a05-1" id="a05-1">
    <span style="display:none;">Spots, defining</span>
  Defining spots</a>
</h2>

This will include an entry for "Spots, defining", linking to the heading.

You can include several hidden entries in one index entry; for example:

<h2>
  <a name="a05-1" id="a05-1">
    <span style="display:none;">Spots, defining</span>
    <span style="display:none;">Ads, showing</span>
  Defining spots</a>
</h2>

This will include entries for "Spots, defining" and "Ads, showing", both linking to the heading.

Adding hidden entries to text in the document

Finally, if you want to add hidden entries to text that actually occurs in the document, put the hidden entries after the text:

<h2>
  <a name="a05-1" id="a05-1">
    Defining spots
    <span style="display:none;">Spots, defining</span>
    <span style="display:none;">Ads, showing</span>
  </a>
</h2>

This will include entries for "Defining spots", "Spots, defining", and "Ads, showing", all linking to the heading.

Inserting the index entry

The index entry simply links to the anchor you have defined for the entry:

<p><a href="05-Spots.html#a05-1">Spots, defining</a></p>

In the frame-based Help system we need an additional target parameter:

<p><a href="05-Spots.html#a05-1" target="content">Spots, defining</a></p>

Compiling the index

To compile the index you need to:

Scan through all the topic files, locating the index entries and anchor ids.
Sort the index entries into alphabetical order.
Create the index as a list of "a href=" links.

Highlighting index entries

By default, the link to an anchor scrolls the anchor to the top of the page, but it is more user-friendly if we actually highlight the indexed text or heading in the document; for example:

This is achieved by setting the class of the "a name=" anchor to "hi", which is defined in the CSS file as follows:

.hi {
  background-color: yellow;
}

The way this is actually achieved depends on the application; see the description in each of the alternative implementations.