指向其他文档集合的 XLinks

XLinks

HTML Help 1 直接使用 HTML <A> 标记表示超链接。Microsoft Help 2 引入了新的 XLinks 机制 (是微软对 W3C XLinks 的一个实现)，来表示指向其他文档集合的超链接。一个 XLink 很像 HTML <A> 链接，但包含额外的元数据用于表示复杂的链接。Microsoft Help 2 使用 XLinks 不直接使用路径/文件名，而根据在“索引”表中检索特定的关键字查找。

NDoc 为指向 .NET Framework 类型/成员的链接（包括成员列表中指向基类型的链接、以及使用 <see> 标记加入的指向 .NET Framework 或第三方类库中的类型/成员的显式链接），制作 XLinks 链接。下面是一个指向 System.Void 的示例 XLink:

<MSHelp:link

keywords="frlrfSystemVoidClassTopic"

indexMoniker="!DefaultAssociativeIndex"

namespace="ms-help://MS.NETFrameworkSDKv1.1.CHS">void</MSHelp:link>

上面 XLink 的三个属性指示了查找这个帮助主题的方法。属性 namespace 指示在哪个文档命名空间中查找(每个帮助文档集合都需要在机器中注册一个唯一的命名空间，如上面的 ms-help://MS.NETFrameworkSDKv1.1.CHS 表示 .NET Framework SDK 类库文档的帮助文档集合)。属性 indexMoniker 指示使用哪种类型的“索引”(Microsoft Help 2 索引可以有很多类型，其中，DefaultAssociativeIndex 常用于创建帮助主题之间的关联)。最后，keyword 指示要指向哪个帮助主题页面。

每个页面头部的嵌入 XML 数据岛中都包含若干 Keywords，您可以在 .NET Framework SDK 类库文档中查看 System.Void 页面中，包含如下的一行:

<MSHelp:Keyword Index="A" Term="frlrfSystemVoidMembersTopic"/>

这个 frlrfSystemVoidMembersTopic 就是在 .NET Framework SDK 类库文档中，用 DefaultAssociativeIndex 类型的“索引”中的 keyword。

链接到 .NET Framework SDK 类库文档

指向到 .NET Framework SDK 类库文档的超链接，不需要您费心，NDoc 已经可以做的很好。您尽管从 .NET Framework 的基类型继承、创作您的子类型，或者使用 <see> 等标记加入这些链接，NDoc 自动处理这些关于 XLinks 的事情。

链接到第三方类库文档

NDoc 允许您创建指向到第三方类库文档的超链接，不过也需要严格按照上面介绍的 XLinks 体制来做。首先找到该文档集合的命名空间，和要指向的帮助主题 HTML 页头部中的 keyword，做好准备。(如果那个文档集合也是用 NDoc 1.3 生成的，则页面头部的 XML 数据岛已经按要求写好了 keyword。)

因为 NDoc 只能找到子类型的父类型的名称，<see> 标记中最终 NDoc 看到的也只是要指向的类型/成员的完全名称；NDoc 不知道这些类型/成员的文档存在哪个文档集合中。您需要告诉 NDoc：哪些类型/成员的帮助文档在哪个文档命名空间，而另一些类型/成员在另一个文档命名空间，也就是各 .NET 类型/成员和 Microsoft Help 2 帮助文档命名空间之间的映射关系。这就需要您指定 NamespaceMappingFile 了（请参见 VS.NET 2003 文档引擎的 UseHelpNamespaceMappingFile 配置项）。NamespaceMappingFile 是一个 XML 文件，它必须符合 NamespaceMapping XSD 架构(请右击“另存为...”)。

<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>

NamespaceMappingFile 的一个实例:

<?xml version="1.0" encoding="utf-8"?>
<namespaceMap xmlns="urn:ndoc-sourceforge-net:documenters.NativeHtmlHelp2.schemas.namespaceMap">
    <helpNamespace ns="ms-help://MS.NETFrameworkSDKv1.1.CHS">
        <managedNamespace ns="System" />
        <managedNamespace ns="Microsoft" />
    </helpNamespace>
</namespaceMap>

上面的例子表示指向 System 和 Microsoft 命名空间的类型/成员的链接，将被指向 ms-help://MS.NETFrameworkSDKv1.1.CHS 帮助文档命名空间。

指定了 NamespaceMappingFile 之后，其他的工作都可以交给 NDoc 来做了。

请参见

VS.NET 2003 文档引擎, Namespace Mapping XSD 架构