The compilers for many modern programming languages have facilities for automatically generating text files called "map files" containing the topic IDs and/or help context numbers for the components and controls used in the program. These files can save you a lot of work in Help+Manual.
Generating missing topics and context numbers:
Help+Manual can use these files both to assign missing help context numbers to existing topics and to automatically generate missing topics with the topic IDs and help context numbers. This second capability is particularly useful for generating the field-level popup topics used to document program components controls and controls with the right-click What's This? function and other similar functions. See Auto-generating field-level popups and The Help Context Tool for details.
Map file syntax:
By default, these files have a very simple syntax, which can be either #define syntax or INI syntax. When anchor IDs are used they must follow directly on the associated topic ID, separated by a # character:
Example of #define syntax:
#define IDH_DEFAULT 100001
#define IDH_OK_BTN 100002
#define IDH_CANCEL_BTN 100003
#define IDH_CLOSE#example 100004
#define IDH_HELP_BTN 100005
#define IDH_APPLY_BTN 100006
#define IDH_APP_HMB 100010
#define IDH_WHAT_IS_THIS_CMD 100011
#define IDH_WHAT_IS_THIS_POPUP 100012
Example of INI syntax:
AboutImage = 10172
AboutIMPICT = 10000
AddingCallout#example = 10236
AddingCursorsandDazzle = 10230
AddingDropShadow = 10167
AddingLensObject#example = 10234
AddingLinesandArrow = 10229
AddingMoreBitmap = 10225
Alternative map file syntax:
When you are exporting map files with the context tool you can also generate your own alternative syntax using the following variables:
<%TOPICID%> |
The topic ID of the topic being exported |
<%ANCHORID%> |
The anchor ID of the anchor being exported |
<%TOPIC_HELPCONTEXT%> |
The help context number |
Just select the Custom option in the export dialog to configure your own map file with these variables. You can place any text characters you need between the variables, they will be exported as-is.
Restrictions of map files:
Using map files to apply help context numbers to existing topics is very straightforward. However, there are two basic restrictions when you are using map files to generate topics that do not yet exist in your help project:
You cannot generate topic captions
Since the map file syntax only includes the topic ID and the help context number you cannot include captions (i.e. the names of the topics in the TOC) for the topics in the map file and you cannot use the map file to generate captions. All topics generated from map files use the topic ID as the caption.
You can only generate topics without TOC entries
This second restriction follows from the first. Since auto-generated topics cannot have captions they are always generated without TOC entries, as topic files in the Topic Files section of the Project Explorer.
This is generally not a problem since the primary purpose of this function is to auto-generate field-level popup topics for documenting program components. If you need to use the function to generate topics in the TOC you must create TOC items for them manually after importing them.
You cannot assign context numbers to anchors
Help+Manual's context tool can export the information about anchor links to map files but you cannot import context numbers to existing or new anchors from a map file.
See also:
