Understanding Context-Sensitive Help in FrameMaker
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:
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 use in context-sensitive help, see the ePublisher Design Guide.
For more information about configuring Filename and TopicAlias markers for context-sensitive help links, see the following topics:
For more information about configuring Filename and TopicAlias markers for use in context-sensitive help, 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 FrameMaker” on page 128.