Context-Sensitive Help in Word
Context-sensitive help links provide content based on the context of what the user is doing. In many cases, this help content is based on the window that is open and active. For example, the Help button on a window in a software product can open a specific Help topic that provides important information about the window:
  • What the window allows you to do
  • Brief concepts needed to understand the window
  • Guidance for how to use the window
  • Descriptions about each field on the window, valid values, and related fields
  • Links to related topics, such as concepts and tasks related to the window
The Help topic can also be embedded in the window itself, such as an HTML pane that displays the content of the Help topic. Providing this content when and where the user needs it, without requiring the user to search through the help, keeps the user productive and focused. This type of help also makes the product more intuitive by providing answers when and where needed.
There are several methods for creating context-sensitive Help. In addition, output formats use different mechanisms to support context-sensitive Help. You can reference a topic in the following ways:
File name
Use a Filename marker to assign a file name to a topic. Each topic can have no more than one Filename marker by default. However, you can create a custom mapping mechanism using file names. Then, you can open the specific topic with that file name. However, if your file naming changes, you need to change the link to the topic. This file naming approach delivers context-sensitive help capabilities in output formats that do not provide a mapping mechanism.
Internal identifier (topic alias)
Use a TopicAlias marker to define an internal identifier for each topic. The benefit of using an internal identifier is that it allows file names to change without impacting the links from the product. The writer inserts this marker in a topic and specifies a unique value for that topic. Then, the mapping mechanism of your output format determines how that internal identifier is supported. Some output formats, such as HTML Help, use a mapping file that defines these topic aliases.
To simplify the coding of your source documents, the Stationery designer can also configure your Stationery to define both the file name and the topic alias for each topic file.
Before you begin to insert Filename markers or TopicAlias markers into your source documents, consult with your Stationery designer. Confirm that your Stationery supports context-sensitive help links, and discuss with your Stationery designer the type of marker you should use to define context-sensitive help link in your source documents.
For more information about configuring Filename and TopicAlias markers for context-sensitive help links, see the following topics:
If you generate Eclipse Help output, you also can choose the topic description you want to display for each context-sensitive link. When you use a TopicAlias marker to create context-sensitive links, Eclipse creates a contexts.xml file that lists all of the context IDs for the Eclipse Help system you created using TopicAlias markers. In the contexts.xml file, Eclipse also provides a description of the context-sensitive link. By default, the description Eclipse provides for the context-sensitive link is the text of the first paragraph of the topic. However, if you want to specify a different description for the context-sensitive link, you can do this by using the TopicDescription marker. For more information about using the TopicDescription marker, see Specifying Context-Sensitive Help Links in Word.
Planning for Context-Sensitive Help in Word
Creating context-sensitive help requires you to collaborate with application developers. Because topic IDs and map numbers must be embedded in both the software application and in your source documents, you and the application developers must agree in advance on the values to use.
Before you create context-sensitive help topics, first confirm with your application developers that the application supports context-sensitive help. Then 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 manually 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 help system and mapping 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.
Note: Because of the way Microsoft Word uses markers with the Transit menu, in order for ePublsher to best pickup a marker such as a TopicAlias, please place this marker after the heading and not before.
Was this helpful?
Last modified date: 01/28/2026