MSDN 集合集成指南

Kirk Stowell

4.92/5 (17投票s)

2001年1月25日

495759

4994

将您的帮助文件与 MSDN 集成

引言

如果您和我一样，有时会因为缺乏文档而感到非常沮丧。花费数百小时构建代码并完善应用程序还不够，现在还要无休止地搜索，试图找到一个本应已记录但却不存在的答案！这就是我在尝试将 HTML Help 与 MSDN Collection 集成时遇到的问题。我最终解决了这个问题，但这并非易事，历经了无数小时的研究。希望我的沮丧和研究能让正在为此主题寻找帮助的您受益。

入门

MSDN 将用于 HTML Help 文件的信息存储在一个称为“collection”（集合）的文件中。集合是一个 XML 格式的文件，其中包含有关将与 MSDN 一起使用的每个帮助文件的信息。集合使用两个文件：msdnxxx.col 和 hhcolreg.dat。msdnxxx.col 文件是实际的集合。它包含要与该集合一起使用的所有 HTML Help 标题的列表。该文件的名称通常以“msdn”开头，以“.col”结尾。 2000 年 10 月的集合文件名是 MSDN030.COL。hhcolreg.dat 文件是集合的注册表。该文件存储每个集合标题的具体详细信息，例如 HTML Help 和索引文件的位置以及版本号。我们需要做的第一件事就是找到这两个文件。

查找 msdnxxx.col 文件

我们需要在系统注册表中查找 msdnxxx.col 文件的位置，您可以使用 regedit 进行此操作。如果您安装了 MSDN Library，您会找到以下注册表项：

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\HTML Help Collections\Developer Collections

微软在这里存储了其帮助集合的位置。在此注册表项下，您会注意到一个 Language（语言）条目。此注册表项的值指定集合使用的语言。通常值为 0x0409 表示英语，但可能会因您的语言设置而异。下一个注册表项是 Preferred（首选）。此值告诉我们哪个集合是 MSDN 当前首选使用的集合。通常此值可能为 0x039a24110 ，但也可能有所不同。在此注册表项下，我们会找到一个 Filename（文件名）条目。此值是 msdnxxx.col 文件在硬盘上的实际位置。

查找 hhcolreg.dat 文件

下一个需要关注的文件是 hhcolreg.dat。与集合文件一样，这也是一个 XML 格式的文件，其中包含有关您集成的帮助文件的具体信息。在 MSDN Library 的旧版本中，此文件位于 Windows\Help 目录。在较新版本中，它已移至 .\Documents and Settings\All Users\Application Data\Microsoft\HTML Help\。从 shell32.dll 版本 4.71 开始，我们可以使用 CSIDL_COMMON_APPDATA 标志调用 SHGetSpecialFolderPath(...)。但是，根据 Internet Explorer 的版本，此函数可能已移至 ShFolder.dll。因此，我们创建了自己的函数版本，称为 GetSpecialFolderPath(...)。我们还可以使用 msdnxxx.col 中的 collectionnum 标签来确定 hhcolreg.dat 文件的位置。通常，如果此值小于 10000，则该文件位于 Windows/Help 目录中。

编辑集合文件

现在我们已经找到了 msdnxxx.col 和 hhcolreg.dat 文件，我们需要检查这些文件以正确集成我们的数据。我们要查看的第一个文件是 msdnxxx.col 文件。使用文本编辑器打开此文件。您会在文件开头看到两个标签：masterlangid 和 collectionnum。它们对我们的集成非常重要。masterlangid 标签告诉我们集合使用的语言，collectionnum 标签指示我们正在处理哪个集合。这些标签的典型值是：

<masterlangid value=1033/><collectionnum value=10001/>

集合中的每个条目都以 <Folder> 标签开头，并以 </Folder> 结尾。有三个值需要您注意。其中两个是 TitleString 标签，一个是 LangId 标签。第一个 TitleString 标签的值是您在运行 HTML Help 时选择“Contents”（目录）选项卡时看到的内容。第二个 TitleString 标签的值是我们的集合标识符。此值必须是集合中唯一的，并将用于 hhcolreg.dat 文件。第三个标签值是 LangId。此值将设置为文件开头找到的 masterlangid 标签值。

典型的集合条目可能看起来像这样：

<Folder>
   <TitleString value="Codejock Software"/>
   <FolderOrder value=2/>
   <Folder>
      <TitleString value="=xtreme_toolkit"/>
      <FolderOrder value=1/>
      <LangId value=1033/>
   </Folder>
</Folder>

编辑注册表文件

接下来，我们将更新 hhcolreg.dat 文件。使用文本编辑器打开该文件。您会注意到每个条目都以 <DocCompilation> 标签开头，并以 </DocCompilation> 结尾。这里有六个标签需要我们关注。DocCompId 标签包含与集合中提到的第二个 TitleString 值相同的值。此值对集合是唯一的，必须完全匹配！DocCompLanguage 标签包含与集合中提到的 LangId 值相同的值。此值必须与 masterlangid 标签匹配。ColNum 标签是集合编号。此值必须与 msdnxxx.col 中找到的 collectionnum 标签匹配。TitleLocation 标签包含您的 *.chm 文件所在位置的完整路径。IndexLocation 标签包含您的 *.chi 文件所在位置的完整路径。最后一个标签是 Version 标签。这是您帮助文件的当前版本。

典型的注册表条目可能看起来像这样：

<DocCompilation>
   <DocCompId value="xtreme_toolkit"/>
   <DocCompLanguage value=1033/>
   <LocationHistory>
      <ColNum value=10001/>
      <TitleLocation value="[full path]Xtreme.chm"/>
      <IndexLocation value="[full path]Xtreme.chi"/>
      <LocationRef value=""/>
      <Version value=2/>
   </LocationHistory>
</DocCompilation>

让一切正常工作

您需要为 HTML Help 文件生成 .chi 索引和二进制目录。这两者都是 MSDN 集合的要求。要执行此操作，您需要在 .hhp 文件的 [OPTIONS] 部分下添加“Create CHI file=Yes”和“Binary TOC=Yes”。还建议您将 .chm 和 .chi 文件放在 MSDN 集合目录中，但这并非集合正常工作的必要条件。完成编辑集合文件后，打开 MSDN Library 集合。选择索引选项卡以生成帮助标题的索引。将出现一个对话框，告知您索引正在生成中。

创建 HTML Help 的工具

在开始 MSDN 集成之前，您需要先创建 HTML Help 文件。为此，您必须在机器上安装 HTML Help Workshop。此程序会将您的 HTML 文件编译成 .chm 文件。此程序是免费的，可以从 Microsoft 下载。

我还发现了一个极好的实用程序，它为我节省了数百小时的 HTML Help 文档创建时间。我强烈建议您查看 Helpware Group 创建的 FAR 应用程序。此共享软件价格合理，可以通过此链接下载。

MSDN 集成实用程序

如果您在看完以上所有内容后感到完全困惑，请不要担心，我们还有一张王牌……MSDN Collection Integration Utility！此程序实际上会为您集成 HTML Help 文件！浏览到您的 .chm 和 .chi 文件所在的位置，提供要在集合中使用的标题字符串，并为您的帮助文件定义一个唯一的标识符。您可以使用任何您想要的字符串作为唯一 ID，但最安全的方法是使用 GUID 来确保唯一性。您可以按“Gen. GUID”按钮自动创建一个。您还可以选择设置帮助的版本标签。定义完必需字段后，只需按“Integrate with MSDN collection”按钮，该实用程序就会完成剩余的工作！

您可以下载可执行文件和完整的项目源代码。所有集成代码都已封装到一个名为 CMSDNIntegration 的类中。您可以在任何 MFC 应用程序中使用此类来创建自己的集成实用程序。下载中包含一个 HTML Help 文件，您可以使用它来测试程序。该帮助文件是 CMSDNIntegration 和 CLoadLibrary 类的完整参考。CLoadLibrary 类是一个包装器，用于加载 DLL 并确定版本号。

……尽情享用！