Due to the way, how MS Help Viewer handles topics, you may encounter a situation when your topics get in a conflict. This happens when you register multiple MSHC packages that contain topics with the same titles. For example, a custom topic named "Overview" or the same documented namespace, which is included in more than one MSHC. In such a case, when you click on such topics in TOC, no matter to which MSHC it belongs, only one topic is always shown (usually the one that was registered as the first). Or you can see classes from multiple packages under the namespace topic.

Topics in MS Help Viewer are uniquely identified by their ID. The ID must be unique among topics in the catalog that have the same locale setting. In another topics, links to this topic are constructed by using this ID. Each MSHC package generated by VSdocman is always placed under the "VS" catalog. This ensures that the package is visible in VS help viewer. The problem is that VSdocman cannot guarantee that all topic IDs be unique.

Let's demonstrate the situation on the following example. We have two VS projects for two components named Component1 and Component2. Each component is implemented in a single class. Each project has just one custom topic named "Overview" and then API documentation. The generated TOC structure will be as follows:

Overview (Y:overview)
MyCompany namespace (N:MyCompany)
 Component1 class (T:MyCompany.Component1)


Overview (Y:overview)
MyCompany namespace (N:MyCompany)
 Component2 class (T:MyCompany.Component2)

VSdocman automatically generates IDs for the topics, shown above within the braces. Red color indicates the IDs that are in conflict when both help packages are registered. As you can see, when a new custom topic is created, VSdocman generates a default ID from its name. In our case it is "overview" (the Y: prefix is added automatically during compilation). You can solve the problem by manually changing the ID in custom topics properties. However, you cannot control how IDs for code members are generated. VSdocman follows the standards and generates IDs in cref syntax. For example, MyCompany namespace has ID "N:MyCompany". This way it's possible to easily create links to this topic from other help packages, similarly as VSdocman generates links to e.g. System.String topic.

Fortunately, MS Help Viewer uses another topic attribute - version. It is the version of the topic when multiple versions exist in a catalog. Because a topic Id is not guaranteed to be unique, this attribute is required when more than one version of a topic exists in a catalog. By default, VSdocman generates version value 10 for each topic. You can set your own version number for a project in Custom variable 1 field in Misc properties. The $CUSTOM-VAR1$ macro is recognized and used in MS Help Viewer output template during compilation.

If you generate multiple help packages and there is a chance of the conflict described above, specify a different version for each project. For example, leave the field empty for Component1 project; the default 10 will be used. Enter 11 for the Component2 project. That way you can safely register both help packages and they will correctly coexist in the VS help.

See Also