|
|
|
Understanding Mapping Files in HTML Help
Implementing context-sensitive help requires close cooperation between the help author and the developer of the application that displays the context-sensitive help topics. In a Microsoft Windows application, all user interface controls, such as windows and tabs, have both symbolic and numeric identifiers. These identifiers are also known as topic IDs and map numbers, respectively.
Each topic ID is associated with a map number in a mapping .h file. When an application calls a context-sensitive help topic, it uses the topic ID to display the correct topic. Therefore, both the help and the application must be built with the same mapping file that associates a map number with each topic ID. If the topic IDs and map numbers do not match, the application displays either the wrong topic or no topic.
The mapping .h file lists topic IDs and map numbers. This mapping file is also referred to as a header file. For Microsoft HTML Help and Microsoft WinHelp, a map file is similar to the following sample file:
#define IDH_NEW_PROJECT_WINDOW 1010
#define IDH_ADD_DOC_WINDOW 1020
#define IDH_STYLE_WINDOW 1030
In this example, IDH_NEW_PROJECT_WINDOW is a topic ID that is associated to the 1010 map number. The marker in the appropriate topic has the IDH_NEW_PROJECT_WINDOW value. To use the error checking in HTML Help Workshop, all topic alias values start with IDH_.
When you implement context-sensitive help, you need to work with your application developers to decide how to choose the topic ID for each context-sensitive help topic:
You choose the topic IDs
You can choose a set of topic IDs and embed them in your source documents using TopicAlias markers. When you generate output, ePublisher can generate a mapping file using those topic IDs and assign a unique number to each topic ID. You can provide the generated mapping file to your application developers, who can embed the topic IDs in the application code. You can then maintain this mapping file, or you can allow ePublisher to generate a new file each time you generate the help. Remember to give the updated file to your application developers each time.
Your developers choose the topic IDs
Your application developers can choose a set of topic IDs and embed them in the application code. Then, you can get a copy of the mapping file from your application developers, specify this mapping file in your project settings, and embed the topic IDs in your source documents using TopicAlias markers. In this case, ePublisher does not generate the mapping file.
Before you begin to implement context-sensitive help, meet with your application developers to select one of these methods for assigning the topic IDs to use for context-sensitive help links. Once you choose a set of topic IDs, embed them in your source documents using TopicAlias markers and do not change them.