7.10.1 Understanding how CSH works
When an application program calls on a Help system to display a topic, the program might pass a number to the Help system to identify the requested topic; this is usually the case for HTML Help, and always for WinHelp. The Help system, however, uses a name to identify a topic; in fact, a topic can have any number of names. In the application for which you are creating CSH, each click of a Help button calls a number (a numeric ID), and each number has to be mapped to a Help topic name (a symbolic ID). A map file provides the necessary links from program to Help system; for some Help systems, an alias file associates each symbolic ID with the name of the Help file:
![[spacer]](1p.gif){kind=small}
For HTML Help, the program can pass a file name instead of a number, eliminating the need for map and alias files, but this is rarely done. For JavaHelp, Oracle Help for Java, and OmniHelp, the program can pass a name instead of a number.
A numeric ID is usually an integer. You might specify the numeric IDs for the developer of the application program, or the developer might specify them; which way depends on development tools and project work flow. If the application program is developed in Visual Basic, the developer enters the numbers on a form; if in Visual C/C++, what the developer does depends on which API call variant is in use.
A symbolic ID consists of the following:
• a special prefix, either IDH_ or HIDC_, that identifies the symbolic ID as a CSH destination
• a name, usually furnished by the application developer, for the application feature involved (such as a button, dialog, or text box).
Each symbolic ID must be unique in your Help project.
Compilers have built-in support for IDH_, so use that prefix if possible. If the developers are using Microsoft Foundation Classes, HIDC_ works also. For HTML Help and OmniHelp, you specify in the configuration file which prefix(es) you are using. WinHelp also uses prefixes, IDH_ in particular; and reports any such entries in your map file for which you did not provide a destination in a topic.
A map file is an ASCII file that contains a line for each link from program to Help system. In some programming environments, such as Visual C/C++, this file is produced for you; in others, such as Visual Basic, you create the map file yourself. For C or C++ the map file is usually named resource.h. For JavaHelp and Oracle Help for Java, Mif2Go creates the map file (with extension .jhm), and writes the symbolic IDs to the file. No map file is needed for OmniHelp.
An alias file is an ASCII file that contains a line for each symbolic ID, associating that ID with the name of the Help file that contains the relevant CSH destination. For HTML Help and OmniHelp, you identify each symbolic ID as an alias, which gets listed in the alias file; Mif2Go can generate the alias file for you. WinHelp links automatically, without an alias file; no additional author actions are required. Help Workshop provides the prefixes.
> 7 Producing on-line Help > 7.10 Setting up Context Sensitive Help (CSH) > 7.10.1 Understanding how CSH works