18.11.3 Specifying and generating a map file for CSH links

If the developers of the application for which you are providing context-sensitive help use HH_HELP_CONTEXT and specify topics by ID number, ask them for the file that maps symbolic IDs to numeric IDs. (You cannot go directly from numbers to files; you have to go through the symbolic names used in the map and alias files.) For C or C++, the map file is usually named resource.h, and contains entries such as the following:

#define IDH_Export 1090
#define IDH_CnvDsgnr 1080

The map file must be named in the [MAP] section of your .hhp file, and must be located in or below the directory that contains your .hhp file. For example:

[MAP]
#include "resource.h"

Quotes are required around each #included file name.

Instead of editing the [MAP] section of your .hhp file, you can specify the file name in a configuration setting; and you can have DITA2Go generate an initial map file for you.

Specify a map file

To specify the name of the map file:

[MSHtmlHelpOptions]
; CshMapFile = name of file to #include in .hhp [MAP] for CSH support
CshMapFile = resource.h

This way you will not lose the information if DITA2Go rewrites the .hhp file. However, if you need to reference more than one map file, you must specify any additional map files in the .hhp file, and you must prevent DITA2Go from rewriting the .hhp file. See §18.3.8 Regenerating the HTML Help project file.

Generate a map file

While the map file normally comes from the developers, it might be necessary for the writer to produce the first one, to let the developer know what IDs are available.

To have DITA2Go generate a map file for CSH links:

[MSHtmlHelpOptions]
; MakeCshMapFile = No (default) or Yes (generate a map file)
MakeCshMapFile = Yes
; CshMapFileNumStart = Starting number for numeric IDs, default 10000
CshMapFileNumStart = 10000
; CshMapFileNumIncrement = Increment between values, default 10
CshMapFileNumIncrement = 10

DITA2Go creates a map file of the name you assign to CshMapFile, overwriting any existing file of the same name, and assigning an incremental numeric ID to each of the symbolic IDs included in your document.

Previous Topic:  18.11.2 Determining whether you need map and alias files

Next Topic:  18.11.4 Creating an alias file for CSH links

Parent Topic:  18.11 Setting up CSH for HTML Help

Sibling Topics:

18.11.1 Inserting CSH destinations in your document

18.11.2 Determining whether you need map and alias files

18.11.4 Creating an alias file for CSH links

18.11.5 Understanding alias-file entries

18.11.6 Producing a list of aliases and associated topic titles

Table of ContentsIndex