XLinks
Unlike Html Help 1, which uses HTML <A> links, Html Help 2 uses an implementation of XLinks to reference topics in external help titles. An XLink is much like an HTML <A> link but allows for additional linking meta-data and more complex types of links. Html Help 2 uses XLinks to look-up topic by keyword, rather than by file name. This de-couples the link from the physical layout of the target help title.
NDoc generates XLinks to topics in the .NET framework. The following is an NDoc generated link to the Framework SDK topic on System.Void:
<MSHelp:link
keywords="frlrfSystemVoidClassTopic"
indexMoniker="!DefaultAssociativeIndex"
namespace="ms-help://MS.NETFrameworkSDKv1.1">void</MSHelp:link>
Example XLink
The three attributes on the above link tell the Html Help 2 system exactly how to resolve the desired topic. The first item required is a namespace. Each help collection registered on a machine has a unique namespace. The namespace above identifies the .NET Framework 1.1 SDK documentation. The indexMoniker identifies a specific type of index within that namespace. There can be numerous types of indices within a help collection, but the DefaultAssociativeIndex is used to create associations between topics. Finally, the keyword attribute identifies the specific topic desired within the index.
Keywords are defined within a help topic as part of the embedded XML data that is generated in the HTML header. The keyword for System.Void is declared as follows within the Html Help for that topic:
<MSHelp:Keyword Index="A" Term="frlrfSystemVoidMembersTopic"/>
Links to Framework Topics
Framework keywords are generated from the full name of the type or member. NDoc generates links to framework topics, either through inheritance or via the <see> tag, by determining the keyword identifier from the item being linked to and within the framework SDK help namespace.
Links to Non-Framework Topics
It is also possible to create links to your own Html Help 2 titles using the same XLinking mechanism. For NDoc to properly generate an XLink to an external title, it needs to know both the help namespace and the keyword value within the DefaultAssociativeIndex.
When NDoc generates an Html Help 2 topic, it includes an XML data island that includes an associative index term similar to those that appear within framework topics. Since NDoc can document private and internal members, the index generated is slightly more complicated than framework keywords, but the keyword value is generated deterministically.
The thing that cannot be determined is the value of the help namespace. The mapping between managed type names and help namespaces is provided by specifying a mapping file via the UseHelpNamespaceMappingFile setting. This setting points to an XML file that conforms to the namespace map XSD schema.
<namespaceMap xmlns="urn:ndoc-sourceforge-net:documenters.NativeHtmlHelp2.schemas.namespaceMap">
<helpNamespace ns="ms-help://companyX.sharedhelpcollection">
<managedNamespace ns="CompanyX"/>
</helpNamespace>
<helpNamespace ns="ms-help://companyX.producthelpcollection">
<managedNamespace ns="CompanyX.Product1"/>
<managedNamespace ns="CompanyX.Product2"/>
</helpNamespace>
</namespaceMap>
This file specifies the managed namespace to help namespace mapping that will be used when creating XLinks to managed types that are not part of the documentation set being processed. Each helpNamespace entry can contain 1..n managedNamespace entries. When resolving the help namespace of a managed type, the most specific managedNamespace entry will be used to select the appropriate help namespace.
The managed type CompanyX.Product2.Class1 would map to ms-help://companyX.producthelpcollection, while CompanyX.Core.Class1 would map to ms-help://companyX.sharedhelpcollection.