Duplicates are forbidden in publish time merging, which is the only available merge mode for all output formats except HTML Help (CHM). Duplicate topic IDs and help context numbers in modules merged at publish time will cause link failures and other errors because they are all in the same output help file.

Duplicate topic IDs and help context numbers are actually not a problem in CHM projects merged at runtime. Since the output consists of separate help files there are no conflicts and all links will work normally. However, it is still a good idea to avoid duplicates within projects because then you can always switch to publish time merging without any problems if you need to.

Help+Manual has a feature that makes preventing duplicate topic IDs very easy. In each project you can automatically add a unique prefix to your topic IDs when you create a new topic. Then even topics with the same basic ID will actually be different. For example, with an auto-prefix the ID Introduction could be Master_Introduction in one project and Mod1_Introduction in another project.

1.Go to Configuration > Common Properties > Miscellaneous.

2.Enter a prefix for your topic IDs in the Topic ID Prefix: field. It's helpful to add an underline character after the prefix, this makes the IDs easier to read in the various ID lists displayed in Help+Manual. For example, the topics in this help file all use the prefix HM_.

3.Repeat for each project you want to include in your modular help system.

If you assign a unique prefix to each project used in your help system and make sure that it is used for all modules you won't have any problems with ID conflicts.

Since you can't add prefixes to help context numbers you have to avoid conflicts here by assigning a predefined range of numbers to each project in your help system. This is effectively the same as a prefix, you just have to make sure the ranges are far enough apart so that they can never overlap.

1.Choose a range of numbers for each of your modules. Make sure that the range is large enough to avoid overlaps even if you add a lot more topics to your project than you initially expect to use! Help context numbers can have a value of 1 – 4294967295 (unsigned 4-byte integer) so there are plenty of ranges to choose from.

2.Go to Project Explorer > Configuration > Common Properties > Miscellaneous.

3.Enter the starting number for the range assigned for the current project in the Start with: field.

4.Enter a reasonable number for the Increment by: value. This should be large enough to allow you to add topics between existing topics but small enough so that you won't go out of your assigned context number range even if you add a lot of topics to your project.

5.Repeat for every project you want to include in your modular help system.

The above methods are fine for new projects. However, when you want to include existing projects in a modular help system you may already have duplicates conflicts that you need to deal with.

1.Check your projects to see whether the context number ranges and IDs used have potential conflicts. The Project Reports tool can be a helpful aid here.

2.Use the Help Context Tool to assign new context numbers to your individual modules.

Remember that when you change help context numbers your programmers must also change the corresponding calls to your topics made from your application!

3.Edit your topic IDs to eliminate the conflicts. Introduce a prefix naming scheme for IDs with a different prefix for each module. This must be done manually. You cannot search and replace topic IDs in the Help+Manual editor.

4.After doing this use the Help Context Tool and the Project Reports tool to export lists of the new context numbers and topic IDs for your programmers.

5.Check whether any scripts or plain HTML code objects inserted in your project contain references to the old topic IDs. These are not updated automatically and need to be checked. The same applies to any links to the old IDs from other projects and help files.

The operations described below are only possible with the Professional and Floating license versions of Help+Manual and are for advanced users only. If you don't feel comfortable with editing source code directly you should not try this. Even if you do, please make a backup copy of your entire project folder before starting!

Note that the risk of damaging your project when you do this is relatively high because it is easy to make mistakes, particularly if you are performing multiple replaces without a manual check for every instance. You have been warned!

Adding prefixes to topic IDs globally:

You need a tool that can rename multiple files and a text editor that can perform search and replace on multiple files for this operation. Without these tools it would be just as fast to edit your topic IDs manually.

1.If your project is not already saved in uncompressed XML format select Save As... in the File menu and save it in an empty folder with the Help Project (uncompressed XML) option. This will create a directory of plain-text XML files that contain all the components of your project.

2.Using your multiple file renaming tool rename the topic files in the Topics folder to add the prefix you want to have to the filenames – the topic IDs are the topic filenames.

3.Open the table of contents file in the Maps folder and add the prefix to all the topic IDs in the href= attributes so that the match the new filenames created in step 2 – make sure that upper and lower case match. This is necessary to make the TOC entries point to the new topic filenames.

4.Open the .hmxp project file in a text editor and locate the section between the <helpcontext-numbers> tags. Add the prefix to all the topic IDs in the href= attributes that assign the help context numbers to specific topics so that the entries match the filenames created in step 2. (This will only be necessary if help context numbers are defined in your project.)

5.With your multi-file search and replace tool search all the topic files in the Topics folder for type="topiclink" href=" and add your prefix after the href=" – you must search for this entire string, otherwise you will add prefixes to file links, Internet links and script links as well, and that would break them.

Warning:
Doing this will break links to topics that are not in the current project and you will need to repair them afterwards. Broken links are highlighted in red. If you have a lot of cross-project topic links you may not want to do this.

Changing context numbers globally:

You can also use the same method to change your context numbers globally. Here you just need to add new number to the beginning of all existing context numbers to "shift" them into a different range. You can do this by editing the .hmxp project file, which is where the context numbers are stored:

1.Save in uncompressed XML mode and open the .hmxp project file in a text editor.

2.Locate the section between the <helpcontext-numbers> tags and add the "shift" number to the beginning of all the context numbers. That's it.