1

我想生成许多单独的输出 CHM 文件(对于单独的库,所以我有一个单独shfbproj的),但它们有许多共同的概念主题。

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

理想情况下,我希望.content在这个中心位置也有一个公共文件,并将其作为“真实”项目文件中特定父主题节点的子节点导入.content,以避免重复。

有没有办法做到这一点?尝试将现有文件添加到项目会导致创建文件的副本,或者如果手动编辑以指向项目文件夹之外的文件,则使项目无法加载。

(我也尝试shfbproj为公共内容制作一个,然后在“真实”项目中引用它,但这似乎没有效果。)

4

2 回答 2

1

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

正如您在 CHM 屏幕截图中看到的那样,我的 BMI 类文档上方有一个词汇表主题。该主题不在项目中,而是在另一个目录中。

CHM 帮助文件

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

可以以通常的方式在 Visual Studio 中添加链接项。选择添加现有项目的选项,然后在文件选择对话框中,而不是单击添加按钮,单击其上的下拉箭头并选择添加为链接选项(如下所示)。

解决方案资源管理器和添加项目对话框的屏幕截图

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

作为下一步,您需要双击您的 egContentLayout.content文件并手动编辑结构。

在此处输入图像描述

从 Sandcastle 帮助文件生成器文档中引用的附加信息:

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

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

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

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

于 2019-09-25T17:57:33.710 回答
1

好的,有几个技巧可以让它按需要工作;感谢help-info.deLink元素的启发。

首先,在 common docs 文件夹中,创建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>common\100-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 的文件夹到 common docs 文件夹的相对路径。

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

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

最后(这部分您可以在 GUI 中执行),将现有.content文件拆分为多个文件,以便您希望在公共内容之前出现的任何内容都以低于 100 的数字命名,之后以高于 100 的数字命名。 (显然,多个内容文件在合并之前按字母顺序排序。)

(如果大多数内容通常会添加到公共内容之前,您可以为公共内容使用不同的数字,但对于我来说,情况正好相反。)


CommonContentDir物业有点烦人;我想使用$(MSBuildThisProjectDir),但似乎 SHFB 构建无法识别这一点,而是尝试在 shfbproj 的主文件夹中查找文件。

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

于 2019-10-02T05:36:08.797 回答