Publishing Context-Sensitive Help (CSH) with FrameMaker

You’ll need to do two things prior to publishing CSH with FrameMaker:

• Create CSH markers
• Create and edit a map (.h) file

To publish context-sensitive Help, you need markers in your documents that FrameMaker can use to create links in your output for your developers.

FrameMaker uses TopicAlias markers to store map ID information in your documents, and these markers, in turn, create named locations in your output. It’s worth noting here that the map ID isn’t shown directly in the HTML output but is tethered to the map number and named destination via the csh.js file.

A map file stores the static relationship between a map ID and its map number.

Placing a context-sensitive Help marker

1. Click to place the mouse cursor at the start of a paragraph (likely a heading).
2. Select Insert > Publish Markers > Apply CSH Marker.
3. Enter the map ID (ideally a text string without spaces) and click Create.

CSH markers are stored in FrameMaker as TopicAlias markers. The marker text is the unique map ID that you’ll also store in the map, or .h file.

important:   You cannot use whitespaces or the following special characters for the marker text of a CSH marker: ~!@#$%^&*()+-={}|[]\\:\”;'<>?,./

Creating and using a Context-Sensitive Help map file

CSH markers identify a specific help location in your FrameMaker document. A map file (with a .h extension) allows you to specify a unique map number for each map ID. Your application developers then use the map ID to hook specific parts of an application (for example, dialog boxes or menu items) to the corresponding help topics.

You may create a map file using any text editor. The file name must be the same as your source book or document file, but with a .h extension.

For example, the map file for sample.book would be sample.h. The map file for example.fm would be example.h.

If you output HTML5 output containing TopicAlias markers, you will find a .h file is created for you automatically. If you created your HTML5 from a book file, you may find that the .h file contains the base entries you need for the map numbers. By saving this .h file into the same folder as your book file you can speed creation of your .h file and then customize the map numbers as needed for your dev team.

Either way, the map file must be stored in the same folder as the source document or book file.

Place the map file in the FrameMaker source folder.

Each CSH marker in your document will require its own line in the map file, and gets written out as follows:

#define map-id unique-number

The map-id is a unique phrase without spaces, and unique-number is a unique whole number. Here is an example of a .h file, which includes the system map ID used above.

After you have added all the map IDs and numbers to your map file, provide the map file to the development team. The developers can use the unique identifiers that you have included in the file, or can edit the whole numbers as needed and return to you an updated file. If they update the map numbers, copy the updated map file into the directory containing your FrameMaker source files.

Publishing your CSH

Modify your Publish profile (HTML5, MS HTML Help) to include the .h file. Run the publish procedure. The CSH markers are now included as anchors in the published output, but will not have the same map ID you used in your TopicAlias markers. Instead, you’ll see code like <a name=CSH_1></a>. This named destination is connected to your map file via the csh.js file in your output folder.

You can now send the files to your dev team for testing.

Your dev team may want to review Context-sensitive Help information for developers in the Using RoboHelp guide for more information.

FrameMaker creates the javascript csh.js which represents the mapping between the Map IDs and the relative URL to the HTML topics starting from the location of index.html.

Now you’ve got the basic steps needed to publish CSH from FrameMaker 2019. For more details, see my FrameMaker Template Design workshop.