|
|
|
Understanding Mapping Files in HTML Help
Implementing context-sensitive help requires 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, a mapping file is similar to the following sample file:
#define IDH_WINDOW_CPRINTERS 1000
#define IDH_WINDOW_CSERVICES 1010
#define IDH_WINDOW_CSHARES 1020
In this example, IDH_WINDOW_CPRINTERS is a topic ID, and 1001 is the corresponding 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_.
The help is also built with an alias file that maps each topic ID to a filename. The mapping file assigns a number to a topic ID in both the help and the application. The alias file then defines the file associated with that topic ID. ePublisher generates the alias file based on markers inserted into source documents. For Microsoft HTML Help, an alias file is similar to the following sample file:
IDH_WINDOW_CPRINTERS=Computer-PrintersTab.htm
IDH_WINDOW_CSERVICES=Computer-ServicesTab.htm
IDH_WINDOW_CSHARES=Computer-SharesTab.htm
In this example, IDH_WINDOW_CPRINTERS is a topic ID and Computer-PrintersTab.htm is the path to the .htm file that you want the application to call for context-sensitive help.
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 and alias 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, but ePublisher does generate the alias 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.