Creating and Assigning Identifiers

The first steps in developing context-sensitive Help (CSH) for your project are to add a header file and add an alias file. After this, you need to work on creating identifiers (IDs) for the header file.

A CSH ID is text (i.e., name) or a number (i.e., value) that connects a particular topic or micro content response with the corresponding part of the software interface. You do not need to use both the ID name and value; one is enough. By pointing to the ID (instead of the full path of the topic or micro content), you can be assured that the link will always work in case the documentation file is later renamed or moved.

  • If it is decided that you are responsible for creating the header file in CSH, you need to open the Alias Editor to create and assign IDs to topics or micro content phrases.
  • If it is decided that the software developer is responsible for creating the header file in CSH, you only need to assign the IDs, which should already be contained in the header file that the developer provides for you. Before assigning the IDs to topics or micro content phrases, you must first import the header file from the developer so that it is located in the Advanced folder in the Project Organizer. See Importing Header Files.

How to Automatically Generate IDs

You might use these steps if you are just getting started with a header and alias file, and you need to create IDs for all or many topics or phrases.

  1. Open the alias file that you created.
  2. (Optional) You can set options for new IDs in advance. This will supply some of the information (e.g., starting value, prefix, include topic in ID name, assign skin) for you automatically as you create new IDs. See Setting Identifier Options.
  3. Do one of the following:
    • In the local toolbar of the Alias Editor click .
    • Right-click in the Identifiers side of the editor, and from the context menu select Auto Generate.

    The Generate Identifiers dialog opens.

  4. In the Header File area on the left, select whether to create a new header file from a template or choose an existing header file.
  5. (Optional) On the right side, in the Identifier Options area, you can override values that are already set in the Identifier Options dialog (see Step 2).

    Starting Value

    Enter the starting value for IDs that you create. Additional IDs that are created will be incremented automatically based on that starting value.

    Prefix

    Specify a prefix to be added at the beginning of each new ID that you create (e.g., ID_, Dialog, Module1).

    Include File or Phrase Name in Identifier Name

    Select this check box if you want the names of the assigned topics or micro content phrases to be included automatically in the names of the new IDs. Flare will add underscores if a name or phrase has more than one word.

    Capitalize Identifier Names

    Select this check box if you want the name that is automatically added for new IDs to use all caps.

    Skins

    Specify which skin should be assigned by default to new IDs that are created. You can always manually select a different skin for any ID afterward, but when you first create a new ID, it will initially be assigned to the default skin that you specified. This option applies to topics only, not to micro content phrases.

    Value Format

    Specify whether the ID values should use a decimal or hexadecimal format. Using hexadecimal values does not affect your CSH in a different way; it's simply another option in case your developers prefer that format.

  6. In the Generate Identifiers for field, select one of the options, depending on whether you want to create IDs for all topics and/or micro content, or only for those that are not yet assigned to IDs.
  7. If you selected one of the "All" options in the previous step, choose one of the following in the Existing Identifiers field:

    • Keep Select this if you want to keep the IDs that you already have in the header file. As a result, you will have some topics that are assigned to multiple IDs (i.e., the old ID and the new one).
    • Delete Select this if you want to delete the existing IDs in the header file, creating new ones instead. This way, you will not have any topics that are assigned to multiple IDs.
  8. Click Create. In the Alias Editor, the header file is automatically selected in the local toolbar. Also, new rows are added in the Alias Editor with (instead of ) next to them. The green icon indicates that the IDs are assigned to topics.
  9. (Optional) If you want a certain ID to point to a specific bookmark or header in the assigned topic, do the following:
    1. Select the ID row.
    2. Click the button located above the ID list.
    3. In the dialog that opens, select a bookmark or header within the topic.
    4. Click OK.
  10. (Optional) If you want to make changes (e.g., modify the ID name or number), click in the appropriate cell and type the new information.

    Note Make sure you use underscores between words because spaces are not allowed.

  11. Click Save the active file. to save your work.

How to Create and Assign a New ID Manually

You might use these steps if you already have a header and alias file that you've been working on for some time. Instead of creating lots of new IDs automatically, you can just create them manually as necessary.

  1. Open the alias file that you created.
  2. (Optional) You can set options for new IDs in advance. This will supply some of the information (e.g., starting value, prefix, include topic in ID name, assign skin) for you automatically as you create new IDs. See Setting Identifier Options.
  3. If you have more than one header file in your project, click the down arrow on the left side of the Alias Editor toolbar, and select the header file for which you want to create IDs. Otherwise, you can just leave (all identifiers) in the field.

    What if you have multiple header files in your project and you do not select a header file, leaving (all identifiers) shown in the drop-down field? In that case, the changes you made in the Alias Editor are applied to the primary header file that you have selected when setting ID options. See Setting Identifier Options.

  4. Do one of the following:
    • On the left side of the editor, select a topic or micro content phrase, and click the Assign to a new identifier button located above the file list.

    • On the left side of the editor, right-click a topic or micro content phrase, and select Assign to New Identifier.

    A new row is added with (instead of ) next to it. The green icon indicates that the ID is assigned to a topic or micro content phrase.

  5. (Optional) If you want the ID to point to a specific bookmark or header in the topic, do the following:
    1. Select the ID row.
    2. Click the button located above the ID list.
    3. In the dialog that opens, select a bookmark or header within the topic.
    4. Click OK.
  6. (Optional) If you want to make changes (e.g., modify the ID name or number), click in the appropriate cell and type the new information.

    Note Make sure you use underscores between words because spaces are not allowed.

  7. Click Save the active file. to save your work.

How to Assign IDs

You might use these steps if the developer initially created the header file and you imported it. The IDs therefore already exist. You just need to assign them to the correct topics or micro content phrases.

  1. Open the alias file that you created.
  2. (Optional) If you want to see only the IDs that are not yet assigned to topics, click in the local toolbar of the Alias Editor. This hides IDs that are already assigned to topics in the editor until you click the button again.
  3. On the right side of the Alias Editor, select an ID that you want to assign to a topic or phrase.
  4. On the left side of the Alias Editor, find a topic or micro content phrase that you want to assign to the ID.

  5. Do one of the following:
    • Double-click the topic or phrase.

    • Click the button located above the file list.

    • Right-click the topic or phrase, and select Assign to Selected Identifier from the context menu.

    The topic or phrase name is added to the ID row on the right side of the Alias Editor, and a green icon (instead of ) is displayed next to it. The green icon indicates that the ID is assigned.

  6. (Optional) If you want the ID to point to a specific bookmark or header in the topic, do the following:
    1. Select the ID row.
    2. Click the button located above the ID list.
    3. In the dialog that opens, select a bookmark or header within the topic.
    4. Click OK.
  7. Click Save the active file. to save your work.

How to Associate Skins With IDs

You can use these steps for IDs assigned to topics only, not micro content phrases.

  1. Open the alias file that you created.
  2. Select the ID row(s). You can hold the SHIFT key to select a range, or you can hold the CTRL key to select individual items.
  3. Do one of the following:
    • Click the arrow in the Select skin button (located above the ID list) and choose a skin from the drop-down.

    • Right-click somewhere in the list. From the context menu select Assign Skin and then from the submenu choose the name of the skin.

  4. Click Save the active file. to save your work.

Button and Context Menu Explanations

Following are explanations of the various buttons and context menu options in the Alias Editor, some of which have been included in the steps above.

Option

Description

Hide IDs that already have topics or phrases assigned to them. By doing this, you can concentrate solely on unassigned IDs.

Create a new ID.

Note You can also perform this task by right-clicking in the Identifiers side of the editor, and from the context menu selecting New Identifier.

Delete the selected ID.

Note You can also perform this task by right-clicking a selection in the Identifiers side of the editor, and selecting Delete Identifier from the context menu.

Automatically generate new IDs for all or many of the topics or phrases in your project.

Note You can also perform this task by right-clicking in the Identifiers side of the editor, and from the context menu selecting Auto Generate.

Specify options in advance for how new IDs are created. See Setting Identifier Options.

Note You can also perform this task by right-clicking in the Identifiers side of the editor, and from the context menu selecting Options.

This lets you see if there are any issues with IDs in the editor, such as IDs that are not yet assigned to topics or phrases.

This highlights the previous ID in the list that has an issue.

This highlights the next ID in the list that has an issue.

Assign the topic or phrase to an ID.

Note You can also perform this task by right-clicking on the topic or phrase, and from the context menu selecting Assign to Selected Identifier.

Create a new ID and assign the topic or phrase to it at the same time.

Note You can also perform this task by right-clicking on the topic or phrase, and from the context menu selecting Assign to New Identifier.

Open

Open the selected topic or micro content file.

Note You can also perform this task by right-clicking on the topic or phrase, and from the context menu selecting Open.

This displays all header files where the selected topic or phrase is assigned to an ID.

Note You can also perform this task by right-clicking on the topic or phrase, and from the context menu selecting Locate the in Header Files.

Unassign the topic or phrase from the ID.

Note You can also perform this task by right-clicking in the Identifiers side of the editor, and from the context menu selecting Unassign.

Select a bookmark in the selected topic.

First you can select an ID row that has already been assigned to a topic and then click this new button. A dialog opens, letting you select a bookmark within that topic.

Note You can also perform this task by right-clicking in the Identifiers side of the editor, and from the context menu selecting Select Bookmark.

You can click the down arrow in the Select Skin button and choose the appropriate skin for the ID.

This icon displays next to any IDs that are not assigned to a topic or phrase.

This icon displays next to any IDs that have already been assigned to a topic or phrase.

This icon displays next to any IDs with broken links.

What’s Noteworthy?

Note If you are generating Eclipse Help, there are additional steps that you need to complete in Eclipse. See Additional Steps for Eclipse Help.

Note You can move IDs from one header file to another by using the right-click context menu. See Moving Identifiers to Different Headers.

Note You cannot have the same identifier more than once in the same alias file.

What’s Next?

Associating an Alias File With a Target