Map files and map IDs

    About map numbers, map files, and map IDs

    Map number
    A numeric value associated with a topic ID. Map numbers and topic IDs are saved in map files. Map numbers are used with applications to specify a topic for calling context-sensitive Help. Whether application developers use map numbers, topics IDs, or both depends on the programming language they use.

    Map file
    A text file containing topic IDs and map numbers. You associate map IDs and map files with topics. As author, if you receive a map file from your developer, assign a map ID from the map file. If you manually create a map file, either auto-generate or manually create the map ID. A project can include multiple map files. Map files use the extensions .h, .hh, and .hm. The default map file is BSSCDefault.h.

    Map ID
    A string that pairs a topic ID with a map number. For example:

    #define ID_SetupScreen 101

    • ID_SetupScreen is the topic ID.

    • 101 is the map number.

    • ID_SetupScreen 101 is the Map ID.

    An Icon indicates the status of a map ID:

    • Blue icons  indicate that map IDs match topics.

    • Yellow icons  indicate that map IDs do not match any topics.

    • Locked icons  (blue or yellow) indicate that the map ID is in a map file that is locked. It cannot be assigned or unassigned.

    Create map IDs, auto-generate map IDs, or import map files to use map IDs. A unique map ID must be assigned to each topic ID. Assign a map ID to a Help topic to display the Help topic in context-sensitive Help.

    Mapping table
    A mechanism that maps fields and controls in dialog boxes to map numbers. The mapping table is programmed into the application to provide context-sensitive Help functionality.

    Managing map files

      Create a map file

      Map files are text files that include a map ID list. Map filenames use the .h extension. When creating filenames, use underscores instead of spaces, and avoid using these illegal characters: \ / : * ? < > | # ", $, &, [ ]

      Authors or developers can create the map file. If the developer creates the map file, the author then imports it.

      You can lock a map file to make it read-only.

      1. Open the Project Set-up pod.

      2. Expand the Context-Sensitive Help folder.

      3. Right-click the Map Files folder.

      4. Choose New Map File.

      5. Enter a name.

      6. Click OK. The file is added to the Map Files folder.

        Note: Obsolete files potentially contain map numbers used for updated files.

      Import a map file

      1. Do one of the following:

        • Click File > Import > Map File.

        • Expand the context-sensitive Help folder in the Project Set-up pod.

      2. Navigate to the map file. Make sure that it’s unlocked.

      3. Double-click the map file to add it to the project Map Files folder.

      Export a map file

      1. In the Project Set-up pod, expand the Context-Sensitive Help folder.

      2. Right-click the Map Files folder.

      3. Select Export Map Files.

      4. Select the programming languages to save the map files to.

      5. Specify a location for the map file. Click OK.

      When you export a map file, the original file remains in your project.

      Lock or unlock a map file

      Locked map files are read-only files. Do not add, remove, or change map IDs in locked map files. Do not modify the file if Remove Unused Map IDs is selected. If you do, you can possibly lose changes in the files. Imported map files are locked by default.

      1. Select View > Pods > Project Set-up.

      2. Expand the Map Files folder (or a custom folder in the Map Files folder).

      3. Right-click the map file.

      4. Select Properties.

      5. Select the Locked option. To unlock the file, deselect the Locked option.

      6. Click Close.

      Remove an obsolete map file

      Obsolete map files sometimes contain map numbers used for updated files. These map numbers can dynamically call a wrong topic. Delete unused map files to prevent this issue.

      1. Open the Project Set-up pod.

      2. Expand the Context-Sensitive Help folder.

      3. Expand the Map Files folder.

      4. Select the map file.

      5. Click Delete.

      Remove an unused map ID

      Your map files must be unlocked to use this option. To remove unused map IDs:

      • Expand the Context-Sensitive Help folder in the Project Set-up pod.

      • Right-click the Map Files folder.

      • Select Edit.

      • Do the following:

        Map Files
        Select the map files from which to remove unused map IDs.

        Select All
        Click to remove unused map IDs from all map files.

        Clear All
        Click to deselect all map files and not remove unused map IDs.

      Managing map IDs

        Create a map ID

        1. Open the Project Set-up pod.

        2. Expand the Context-Sensitive Help folder.

        3. Expand the Map Files folder.

        4. Double-click All Map IDs.

        5. In Map File, click the Down Arrow and select a map file to store the map ID.

        6. Click the Create/Edit Map ID button .

        7. In Topic ID, type a word or phrase to identify the topic.

        8. In Map Number, type a number.
          Note: You can create individual map IDs per topic or auto-generate using the Auto Map button. See Auto-generate a map ID

        Edit a map ID

        You can assign or unassign topic map IDs, create new map IDs and files, and automatically map (auto-map) IDs. You can sort the topics by column.

        1. Open the Project Set-up pod.

        2. Expand the Context-Sensitive Help folder.

        3. Right-click the Map Files folder.

        4. Select Edit Map IDs.

        5. Choose from the following options:

        Map File
        List available map files (including imported map files).

        <All Map Files>
        Display all map IDs.

        <Project Map File>
        Display map IDs in the default map file BSSCDdefault.h. The map IDs for deselected map files reside in BSSCDefault.h.

        Map file icon
        Click to open the New Map File dialog box and create a custom map file. Map numbers for custom map files are numbered automatically.

        Map #
        Display the map number of the topic ID. Map numbers reside in map files (.h, .hh, .hm).

        Topic
        Display the topic assigned to the map ID.

        Hide Used IDs
        Show unassigned map IDs.

        New icon 
        Create a map ID. The ID is appended to the map file selected in Map File.

        Edit icon 
        Edit the selected map ID.

        Delete 
        Remove the selected map ID. Before removing the ID, click Unassign to prevent a broken link to the topic.

        Options
        Customize topic auto-mapping.

        Assign
        Assign the selected topic to the selected topic ID. This button is available when a topic is selected on the right and a map ID is selected on the left.

        Unassign
        Disassociate the map ID from the topic on the right.

        Auto Map
        Assign a map ID in the custom or default map file (BSSCDefault.h). Select a map file and a topic. Click Auto Map. This button is available only when you select <Project Map File> or a custom map file. If you auto-map a map ID and a map file is not selected, the map ID resides in the default map file (BSSCDefault.h).

        • The program assigns the topic title or filename as the topic ID and assigns a map number. Click Options to customize auto-mapping.

        • You cannot assign multiple topics to a map ID. You can assign multiple map IDs to a topic.

        Topic
        Lists the project topics. To filter the list, click the triangle . Select All Folders, Top Level Folder, or a custom folder.
        Properties icon  
        Show all topic IDs assigned to the topic.

        Preview icon 
        Display the topic.
        Note: If you assign a map ID to a bookmark, you see a misleading error message indicating that the file does not exist. Disregard the warning. The topic does exist.

        Reassign a map ID

        Update the map ID if the Help topic doesn’t open, if the wrong topic opens, or if the developer changed the application that in way that affects the map IDs.

        1. Select a map file under Map IDs in the Edit Map IDs dialog box.

        2. Click Create/Edit Map ID.

        3. Do one of the following:

          • Reassign the map ID. Under Map ID, select the map ID. Click Unassign. Select another topic and click Assign.

          • Change the topic ID or map number. Double-click the map ID and change the desired value.

        Auto-generate a map ID

        You can generate map IDs using a custom map file or the default map file (BSSCDefault.h). Before you generate map files, check with the developer to determine naming conventions.

        1. In the Project Set-up pod, expand the Context-Sensitive Help folder.

        2. Expand the Map Files folder.

        3. Double-click All Map IDs.

        4. In Map File, click the triangle button.

        5. Select a map file.

        6. Set options for naming and numbering map IDs. By default, the application assigns the topic title or filename as the topic ID and assigns a map number.

        7. In the Topic field, select the topic.

        8. Click Auto Map to create a map ID.

        9. If necessary, double-click the map file to edit it.

        10. Provide a copy of the map file to the developer.

        Generate a map ID

        The IDs reside in the map file you select from the Edit Map IDs dialog box.

         Click Options in the Edit Map IDs dialog box.

        Prefix Map IDs With
        Select to enter a value at the beginning of each map ID.

        Make Uppercase
        Select for uppercase auto-generated map IDs.

        Start Numbering With
        Select to enter a starting number for map numbers.

        Notes:

        • Setting these options does not affect existing map IDs.

        • By default, the application assigns the topic title or filename as the topic ID and assigns a map number.

        • Auto-generating map IDs is available when you select <Project Map File> or a custom map file. If you auto-map a map ID and do not select a map file, the map ID resides in the default map file (BSSCDefault.h).

        • You cannot assign multiple topics to a map ID. You can assign multiple map IDs to one topic.

        Assign a map ID to a topic

        1. Open the Project Set-up pod.

        2. Expand the Context-Sensitive Help folder.

        3. Expand the Map Files folder.

        4. Double-click All Map IDs.

        5. In Map File, click the Down Arrow and select the map file that contains the map ID.

        6. Select the map ID to assign.

        7. Select the topic.

        8. Click Assign.

        9. Click Close.

        10. Generate the project.

        11. Test the window-level topics with the application.

        Unassign a map ID

        1. Open the topic.

        2. Click the Properties button .

        3. Click the Advanced tab.

        4. Click Assigned Map IDs.

        5. Select the map ID to unassign.

        6. Click Edit Map IDs.

        7. Click Unassign.

        8. Click Close.

        9. Generate the project.

        10. Test the window-level topics with the application.

        Note: If you assign map IDs to bookmarks and remove the bookmarks from the topics, manually unassign map IDs from the bookmarks.