Creating and Assigning Identifiers

• Creating Topic IDs and Unique Numerical Values That Correspond to the Different CSH Help Topics That You Want to Include For example, if the software application that you are documenting contains a dialog called the "Properties dialog," you might have written a topic for it called "Using the Properties dialog." To connect the actual dialog with your topic, you might create a topic ID in the Alias Editor, naming it "Properties_Dialog." Furthermore, let's say that you have already created similar topic IDs for 157 other topics and dialogs. You have given each of those topic IDs a unique value from 1 to 157. So for "Properties_Dialog," you assign 158. Therefore, you end up with a topic ID and numerical value that looks like this: Properties_Dialog 158.
• Assigning a Topic (or Even a Bookmark Within a Topic) to a Topic ID That You Created For example, if you have created a topic ID called "Properties_Dialog," you need to somehow link it to the topic that you want users to see when they click the Help button in that dialog. Let's say you want to link that topic ID with your topic named "Using the Properties dialog." Therefore, in the Alias Editor you could select the topic ID and then double-click the topic. This "ties" the topic ID to that specific topic.
• (Optional) Assigning a Skin to a Topic ID That You Create For example, let's say that you want most of the topics in your Help system to open in a window that is 5 inches wide and 7 inches high (as well as other characteristics). Therefore, you create a skin that contains those specifications and name it "Main." However, for CSH topics that are opened from individual dialogs or windows, you want the Help window to be only 4 inches wide and 6 inches high (as well as other characteristics). So you create an additional skin containing those specifications and name it "Dialogs." In the Alias Editor, you can click and select the Dialogs skin in the Identifier Options dialog. Then, whenever you create a new identifier, it will automatically be associated with that skin. You can also assign skins manually to each identifier in the Alias Editor. If you are generating HTML5 output, make sure that all of your CSH skins are either enabled with responsive output or not enabled with it; you should not have some skins that have it enabled and others that do not.

The following steps show you how to complete these tasks. Use whichever set of steps best applies to your situation:

• How to Automatically Generate Identifiers for All Topics
• How to Create and Assign Identifiers at the Same Time
• How to Create Identifiers Only
• How to Assign Identifiers to Topics

1. Open the alias file that you created.
2. (Optional) You can set options for new identifiers 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 identifiers. 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 select one of the following, depending on whether you need to create a new header file or have an existing one you can select.

   • New from template This lets you choose either a factory template file or one of your own customized template files as a starting point. The new file will take on all of the settings contained in the template. See About Templates.

     1. If you want to use a factory template provided by Flare, expand the Factory Templates folder and click on a template file. If you want to use your own customized template file, expand the appropriate folder and click on a file.
     2. After selecting a template, use the File Name field to enter a name for the new header file.
     3. If you want the new header file to be placed at the root level (i.e., directly under the Advanced folder in the Project Organizer), leave the Folder field set to (root folder). If instead you have created a subfolder within the Advanced folder and want to place the new header file there, click and select that subfolder.
     note

     Note: In some dialogs and wizards you can click the Manage Templates button if you want to open the Template Manager. This lets you manage any of your template files (e.g., add new templates, enter descriptions for templates). See Managing Templates.

   • Choose Existing This lets you choose an existing header file in your project. To use this option, click the drop-down field and select a header file.

5. (Optional) In the Identifier Options area, you can override any of the values that are already set in the Identifier Options dialog (see Step 2).

   starting value

   You can specify the starting value for identifiers that you create, with the value for additional identifiers being incremented automatically based on that starting value.

   

   prefix

   You can specify a prefix to be added at the beginning of each new identifier that you create (e.g., ID_, Dialog, Module1).

   

   include topic name in identifier name

   You can specify that new identifiers should automatically include the assigned topic in the name.

   

   capitalize identifier names

   You can specify that the name that is automatically added for new identifiers should have all caps.

   

   skins

   You can specify which skin should be assigned by default to new identifiers that are created. Of course, you can always manually select a different skin for any identifier, but when you first create a new identifier, it will initially be assigned to the default skin that you specified.

   

   value format

   You can specify whether the identifier 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. Click in the Generate Identifiers for field and select one of the following:

   • Unassigned topics only Select this if you already have some identifiers in the header file that are assigned to topics. New identifiers will be created only for topics in your project that are not yet assigned to an identifier.

   • All topics Select this if you want new identifiers to be created for all topics in your project, whether some topics are already assigned to new topics or not.
7. If you selected the All topics option in the previous step, select one of the following inthe Existing Identifiers field:
   • Keep Select this if you want to keep the identifiers that you already have in the header file. As a result, you will have some topics that are assigned to multiple identifiers (i.e., the old identifier and the new one).
   • Delete Select this if you want to delete the existing identifiers in the header file, creating new ones instead. This way, you will not have any topics that are assigned to multiple identifiers.
8. Click Create and in the next dialog click OK. 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 identifiers are assigned to topics. If you have previously set identifier options (see Step 2), the identifier includes at least some of the appropriate information already.
9. (Optional) If you want a certain identifier to point to a specific bookmark or header in the assigned topic, do the following:
   1. Select the identifier row.
   2. Click the button located above the identifier list.
   3. In the dialog that opens, select a bookmark or header.
   4. Click OK.

10. (Optional) If you want to change an identifier name, click twice in the Identifier cell and type the name (e.g., Properties_Dialog).

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

11. (Optional) If you want to change the skin associated with one or more identifiers, do the following:
    1. Select the identifier row(s). You can hold the SHIFT key to select a range, or you can hold the CTRL key to select individual items.
    2. Do one of the following:

       • Click the arrow in the Select skin button (located above the identifier 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.

       

12. (Optional) If you want to change the numerical value for an identifier, click twice in the Value cell and type the new value.

    Note: You may need to use the horizontal scroll bar at the bottom of the editor to see this cell.

13. Click to save your work.

1. Open the alias file that you created.
2. (Optional) You can set options for new identifiers 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 identifiers. See Setting Identifier Options.

3. If you have more than one header file in your project, click the down arrow at the top-left side of the Alias Editor and select the header file for which you want to create identifiers. 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 identifier options. See Setting Identifier Options.

   

4. On the left side of the Alias Editor, select one or more topics that you want to assign to new identifiers.

   

   You can click the show and hide buttons to help you better locate topics. If you use the options to split the view into two halves, you can select multiple topics on the right side by holding down the SHIFT or CTRL keys as you click.

   

   	Shows all of the files in the project in a list in the area below. If you click the button again, it switches to a folder tree view. In the list, you can click the File, Type, or Path column headers to sort the list alphabetically by that column data.
   	Shows or hides the folders that the files are stored in.
   	Shows or hides the files. If you click this button when the Show Folders button is selected, the area splits into two. The folder is shown on the left side, and the files and subfolders within it are shown on the right.
   	If the Show Files button is the only one selected, you can click this button to move up one folder level.

5. Do one of the following:

   • Click the button located above the file list.

   • Right-click a topic on the left side of the editor, and select Assign Topic to New Identifier from the context menu.

   A new row is added with (instead of ) next to it. The green icon indicates that the identifier is assigned to a topic. If you have previously set identifier options (see Step 2), the identifier includes at least some of the appropriate information already.

6. (Optional) If you want the identifier to point to a specific bookmark or header in the topic, do the following:
   1. Select the identifier row.
   2. Click the button located above the identifier list.
   3. In the dialog that opens, select a bookmark or header.
   4. Click OK.

7. (Optional) If you want to change the identifier name, click twice in the Identifier cell and type the name (e.g., Properties_Dialog).

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

8. (Optional) If you want to change the skin associated with one or more identifiers, do the following:
   1. Select the identifier row(s). You can hold the SHIFT key to select a range, or you can hold the CTRL key to select individual items.
   2. Do one of the following:

      • Click the arrow in the Select skin button (located above the identifier 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.

      

9. (Optional) If you want to change the numerical value for the identifier, click twice in the Value cell and type the new value. You can enter a decimal or hexadecimal value. Using hexadecimal values does not affect your CSH in a different way; it's simply another option in case your developers prefer that format.

   Note: You may need to use the horizontal scroll bar at the bottom of the editor to see this cell.

10. Repeat these steps for each identifier that you want to add. Each entry will represent a different dialog or window in the software application.
11. Click to save your work.

1. Open the alias file that you created.

2. If you have more than one header file in your project, click the down arrow at the top-left side of the Alias Editor and select the header file for which you want to create identifiers. 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 identifier options. See Setting Identifier Options.

   

3. Do one of the following:

   • In the local toolbar click .

   • Right-click in the Identifiers side of the editor, and select New Identifier from the context menu.

   A new row is added with (instead of ) next to it. The yellow icon indicates that the identifier is not yet assigned to a topic. If you have previously set identifier options (see Step 2), the identifier includes at least some of the appropriate information already.

4. (Optional) If you want to change the identifier name, click twice in the Identifier cell and type the name (e.g., Properties_Dialog).

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

5. (Optional) If you want to change the skin associated with one or more identifiers, do the following:
   1. Select the identifier row(s). You can hold the SHIFT key to select a range, or you can hold the CTRL key to select individual items.
   2. Do one of the following:

      • Click the arrow in the Select skin button (located above the identifier 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.

      

6. (Optional) If you want to change the numerical value for the identifier, click twice in the Value cell and type the new value. You can enter a decimal or hexadecimal value. Using hexadecimal values does not affect your CSH in a different way; it's simply another option in case your developers prefer that format.

   Note: You may need to use the horizontal scroll bar at the bottom of the editor to see this cell.

7. Repeat the these steps for each identifier that you want to add (each one to represent a different dialog or window in the software application).
8. Click to save your work.

1. Open the alias file that you created.
2. (Optional) If you want to see only the identifiers that are not yet assigned to topics, click in the local toolbar of the Alias Editor. This hides identifiers 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 identifier that you want to assign to a topic.

4. On the left side of the Alias Editor, find a topic that you want to assign to the identifier that you selected in the previous step.

   

   You can click the show and hide buttons to help you better locate topics.

   

   	Shows all of the files in the project in a list in the area below. If you click the button again, it switches to a folder tree view. In the list, you can click the File, Type, or Path column headers to sort the list alphabetically by that column data.
   	Shows or hides the folders that the files are stored in.
   	Shows or hides the files. If you click this button when the Show Folders button is selected, the area splits into two. The folder is shown on the left side, and the files and subfolders within it are shown on the right.
   	If the Show Files button is the only one selected, you can click this button to move up one folder level.

5. Do one of the following:

   • Double-click the topic.

   • Click the button located above the file list.

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

   The topic name is added to the identifier 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 identifier is assigned to a topic.

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

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.

New	Description
	Hide assigned identifiers This hides the identifiers that already have topics assigned to them. By doing this, you can concentrate solely on the identifiers that need topics assigned to them.
	Create new identifier note 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 selected identifier note 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.
	Generate identifiers This lets you automatically generate new identifiers for all of the topics in your project. This is a good feature to use if you are creating identifiers in a header file for the first time. When you click this button, the Generate Identifiers dialog opens. In this dialog you can create a new header file or select an existing one. You can also see the identifier options—such as starting value, prefix, and skin—that will be applied to all of the new identifiers that are created. note 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.
	Change identifier options This lets you specify options in advance for how new identifiers are created. See Setting Identifier Options. note Note: You can also perform this task by right-clicking in the Identifiers side of the editor, and from the context menu selecting Options.
	Identifier warning This lets you see if there are any issues with identifiers in the editor, such as identifiers that are not yet assigned to topics.
	Previous warning This highlights the previous identifier in the list that has an issue.
	Next warning This highlights the next identifier in the list that has an issue.
	Assign topic to existing identifier note Note: You can also perform this task by right-clicking on the topic, and from the context menu selecting Assign Topic to Selected Identifier.
	Create new identifier and assign topic to it at the same time note Note: You can also perform this task by right-clicking on the topic, and from the context menu selecting Assign Topic to New Identifier.
	Open selected topic note Note: You can also perform this task by right-clicking on the topic, and from the context menu selecting Open.
	Locate topic in header file This displays all header files where the selected topic is assigned to an identifier. note Note: You can also perform this task by right-clicking on the topic, and from the context menu selecting Locate the Topic in Headers.
	Unassign topic from identifier note Note: You can also perform this task by right-clicking in the Identifiers side of the editor, and from the context menu selecting Unassign Topic.
	Select bookmark in selected topic First you can select an identifier 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 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.
	Select skin for identifier You can click the down arrow in the Select Skin button and choose the appropriate skin for the identifier.
	Not assigned This icon displays next to any identifiers that are not yet assigned to a topic.
	Assigned This icon displays next to any identifiers that have already been assigned to a topic.
	Broken This icon displays next to any identifiers that are linked to topics that don't exist.

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

Note: If you are importing FrameMaker documents, you can create topic alias markers in the source files as an alternative to creating identifiers in Flare. When you import the FrameMaker files, the identifiers will be created for you in Flare. See Creating Topic Alias Markers in FrameMaker for CSH.

After you create and assign identifiers, you need to do the following:

1. Associate the alias file with the target that you want to build. This is required if you have more than one alias file in your project. See Associating an Alias File with a Target.
2. Provide the developer with a copy of the header file, if you are responsible for creating it. See Providing a Developer with a Header File.
3. Build the output for the target and provide the developer with a copy of the output files. See About Building and Publishing Output.
4. Test the CSH. See Testing Context-sensitive Help.