有什么办法可以在SHFB中导入外部项目或主题文件吗？

Question

我想生成一些单独的输出 CHM 文件（用于单独的库，所以我每个都有一个单独的 shfbproj），但它们有许多共同的概念主题。

我希望能够将这些主题的 .aml 文件放在一个地方，然后将它们导入到每个项目中，以避免重复。

理想情况下，我希望在这个中心位置也有一个通用 .content 文件，并将其作为 "real" 项目 [=12] 中特定父主题节点的子节点导入=] 文件，以避免重复。

有什么办法吗？尝试将现有文件添加到项目会导致创建文件的副本，或者如果手动编辑以指向项目文件夹外的文件，则会使项目无法加载。

（我也试过为公共内容制作一个shfbproj，然后在"real"项目中引用它，但是这似乎没有效果。）

Answer 1

解决方案在很大程度上取决于您的要求和生成的帮助文件的预期结构。使用 Visual Studio 插件和独立的 Sandcastle Help File Builder (SHFB) GUI 是不同的。

如您在 CHM 屏幕截图中所见，我的 BMI class 文档上方有一个词汇表主题。这个题目不在项目里，在别的目录里。

帮助文件生成器项目也支持链接项。 Linked 项目是出现在当前项目文件夹结构中但实际位于当前项目文件夹结构之外的位置的文件。一个例子是在多个项目之间共享一个令牌文件。如果在一个项目中编辑文件，这些更改会反映在其他项目中，在这些项目构建时它是链接项或实际项。

Linked 项目 可以用通常的方式添加到 Visual Studio 中。 Select 添加现有项目的选项，在文件 selection 对话框中，不要单击“添加”按钮，而是单击它上面的下拉箭头和 select 添加为 Link选项（如下图）.

我认为这是您附加内容的可能性。

下一步您需要双击您的例如ContentLayout.content 文件并手动编辑结构。

引用自 Sandcastle 帮助文件生成器文档的其他信息：

如果您没有 Visual Studio，创建链接项的唯一方法是在文本编辑器中手动编辑项目。为此，将构建项添加到项组。这是通过添加一个以构建操作命名的元素（即令牌文件的令牌）来完成的。 Include 属性指向文件的相对路径，该文件通常在当前项目的文件夹结构之外。添加嵌套在构建项中的 Link 元素，并将其属性值设置为项目在当前帮助文件构建器项目中的相对路径。例如：

<Tokens Include="..\SomeOtherProject\Tokens\SharedTokensFile.tokens">
  <Link>Tokens\SharedTokens.tokens</Link>
</Tokens>

上面的示例创建了一个链接的令牌文件。它的物理位置比另一个项目文件夹 (..\SomeOtherProject\Tokens) 中的帮助文件生成器项目文件夹高一级。它在当前项目中的虚拟位置将在名为 .\Tokens.

的文件夹中

Linked 项目将有一个删除选项而不是删除选项。这会将它们从项目中移除，但会将它们保留在磁盘上的原始位置，因为它们可能属于另一个项目。

Answer 2

好的，有几个技巧可以让它按预期工作；感谢在 Link 元素上的灵感。

首先，在常用文档文件夹中，创建CommonDoc.targets:

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="4.0">
    <ItemGroup>
        <Folder Include="common\" />
    </ItemGroup>
    <ItemGroup>
        <ContentLayout Include="$(CommonContentDir)100-common.content">
            <Link>common0-common.content</Link>
        </ContentLayout>
    </ItemGroup>
    <ItemGroup>
        <None Include="$(CommonContentDir)performance.aml">
            <Link>common\performance.aml</Link>
        </None>
        <None Include="$(CommonContentDir)security.aml">
            <Link>common\security.aml</Link>
        </None>
    </ItemGroup>
</Project>

接下来，编辑主 shfbproj 文件并在现有 PropertyGroup 元素下方添加以下内容：

<PropertyGroup>
    <CommonContentDir>..\..\Doc\</CommonContentDir>
</PropertyGroup>

这是从包含 shfbproj 的文件夹到常用文档文件夹的相对路径。

还在现有 Import 元素上方添加以下内容：

<Import Project="$(CommonContentDir)CommonDoc.targets" />

最后（这部分你可以在 GUI 中完成），将现有的 .content 文件拆分成多个文件，这样你想在公共内容之前出现的任何内容都以小于 100 的数字命名以及之后数字大于 100 的任何内容。（显然多个内容文件在合并之前按字母顺序排序。）

（如果大部分内容通常会添加在公共内容之前，您可以为公共内容使用不同的编号，但对于我来说，情况恰恰相反。）

CommonContentDir 属性有点烦人；我想使用 $(MSBuildThisProjectDir)，但 SHFB 版本似乎无法识别这一点，而是尝试在主 shfbproj 文件夹中查找文件。

此方法的另一个缺点是，当您想向公共主题添加新文件时，您将不得不手动编辑 CommonDoc.targets 文件。但是一旦你这样做，它就会自动出现在每个引用该文件的帮助文件中，而不必单独更新每个 shfbproj。

有什么办法可以在SHFB中导入外部项目或主题文件吗？

Is there any way to import an external project or topic files in SHFB?

c#

sandcastle

chm

shfb