Renaming topics

This month's tip provides some guidelines on how to successfully rename HTML topics so that the topic and all its references are converted to a new name.

A typical HTML topic has three identical pieces of information when it is created. Each piece of information is used by the help system and by the users to identify the topic. The Title element, for example, may be the single most important piece of information stored in Help topic. When you change a topic name, you must also change all the references in the help system that use the <title> element when a link is created.

For example, when you view the Search tab in a Help file, you are displaying the <title> elements from topics. The <title> element also appears in Topics Found dialog boxs, Link Control buttons, and also when you drag and drop a link to create new hyperlinks, Table of Contents and Index entries.

The <title> tag is stored in the <head> section of the HTML topic, as below.

As the topic is created, the <title> element is used to create the <h1> headline in the <body> section of the HTML topic, as above. The user, however, sees only the <h1> tag when they display the topic, as below.

It makes sense to rename both the <title> and the <h1> tags whenever you change the name of the topic. If you click a link called Blue Duck, the heading you should see when you display the topic should also be Blue Duck.

In addition, it is recommended that the filename be changed to a similar name. For example, the three identical pieces of information created on all new topics are:

File name -- Changing_Topic_Names.htm
Topic Title -- <title>Changing Topic Names</title>
Heading 1 -- <h1>Changing Topic Names</h1>

It doesn't make much sense to change only two of the three elements to new names.

The challenge when renaming a topic is not only to keep these three elements in synch, but to successfully change all references to the topic. Here's a list of items that may be affected when you rename a topic.

You must develop a systematic approach to completely transform a topic from one name to another name.

When renaming a topic, consider each of the items below and how they may become affected if you change the name of your topic.
Item Changed	Notes
Topic	Change the file name, <title>, and <h1> to the same name.
Jumps/Popups	Change the hotspot text appearing on the link
Topic Title	Change the Title in Topic Properties
Topic Heading	Change the Heading appearing on the topic
Buttons & Link Controls	Change the references in the button properties to the new topic title
Index	Index keywords are automatically reassociated to the new topic, but the text the user sees, may need to change.
TOC	TOC links are automatically reassociated to the new topic, but the text the user sees in the TOC may need to be changed.
Image maps	Hotspot regions change automatically in HTML Help.
MAP Ids	Examine the Map ID of the topic. A very important step that is often overlooked. If you rename the topic file name, you may also need to rename the information in the Alias (.ALI) file and Map (.H) file. For example, if you rename the topic to Blue_Duck.htm, RoboHelp automatically uses the old Topic ID (Changing_Topic_Names) to link to the new file name in the Alias, such as: A very important step that is often overlooked. If you rename the topic file name, you may also need to rename the information in the Alias (.ALI) file and Map (.H) file. For example, if you rename the topic to Renamed_Topic.htm, RoboHelp automatically uses the old Topic ID (Changing_Topic_Names) to link to the new file name in the Alias, such as: #define Changing_Topic_Names 1001 (map file) but updates the Alias file to the following: Changing_Topic_Names=Blue_Duck.htm (alias file) This could become extremely confusing if you have a lot of renaming to do. The best recommendation is to unassign the old Map ID, run the Remove Unused Map IDs command, and create a new Map ID, and reassign it to the topic in the Alias list.

That's it for this month's tip.

Rob Magrino

Certified XxxxXxxx Instructor