Using Context-Sensitive Help in HTML Help
Context-sensitive help links allow you to open a specific help topic. For example, the Help button on a window in a software product can open a specific help topic that describes the window and provides links to related topics. The help topic can also be embedded in the window itself, such as an HTML pane that displays the content of the help topic.
You can reference topics in HTML Help using the file name or an internal identifier called a topic ID or topic alias. To use file names, use a Filename marker to assign a file name to a topic. Then, you can open that specific topic with that name. However, if your file naming changes, you need to change the link to the topic. Before you can reference topics in HTML Help using file names, you must enable Filename markers in your Stationery. For more information, see “Defining Filename Markers for Context-Sensitive Help Links”.
To reference topics in HTML Help using an internal identifier, use a TopicAlias marker to define the identifier for each topic. The benefit of using this approach is that it allows file names to change without impacting the links from the product. The writer inserts a TopicAlias marker in a topic and specifies a unique value for that topic. Then, HTML Help uses a mapping file that defines these topic aliases and maps them to the file generated for that topic. Before you can reference topics in HTML Help using topic aliases, you must enable TopicAlias markers in your Stationery. For more information, see “Defining Filename Markers for Context-Sensitive Help Links”.
To simplify the coding of your source documents, you can use the same marker to define both the name and the topic alias for each topic file. In Style Designer, set the Marker type option for the marker you want to use to Filename and topic alias. However, if you change the value of this marker, you need to change the application that uses this value.
To use context-sensitive help in HTML Help
Determine whether you want to manually create and maintain the mapping file, or you want ePublisher to automatically create and maintain the mapping file. For more information, see “Understanding Mapping Files in HTML Help”.
In your source documents, use TopicAlias markers to identify the internal identifier for each topic.
If you want to create and maintain the mapping file, complete the following steps:
Work with your application developer to determine who will create and maintain the mapping file.
Store the mapping file in the Files folder in your project. Make sure to keep this file up-to-date with the latest version of this file. Both the application and the help must be built using the same version of this file so the help links open the correct topics.
Set the mapping options to define your mapping file, such as whether you want ePublisher to generate the mapping file or you want ePublisher to use the mapping file in the Files folder in your project. For more information, see “Setting Mapping File Options for HTML Help”.
Generate output from your project and test your context-sensitive help links. For more information, see “Testing Context-Sensitive HTML Help”.