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

Question

I want to produce a number of separate output CHM files (for separate libraries, so I have a separate shfbproj for each), but that have a number of conceptual topics in common.

I would like to be able to put the .aml files for these topics in one place and then import them into each of the projects, to avoid duplication.

Ideally, I'd like to have a common .content file in this central location as well, and import this as children of a specific parent topic node in the "real" project's .content file, to avoid duplicating that too.

Is there any way to do this? Trying to add existing files to the project results in either creating copies of the files, or making the project unloadable if manually edited to point at files outside of the project's folder.

(I also tried making a shfbproj for the common content and then referencing this in the "real" project, but this appears to have no effect.)

Answer 1

Ok, there are a couple of tricks to get this to work as desired; thanks to help-info.de's answer for inspiration on the Link elements.

Firstly, in the common docs folder, create 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>

Next, edit the main shfbproj file and add the following below the existing PropertyGroup elements:

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

This is the relative path from the folder with the shfbproj to the common docs folder.

Also add the following just above the existing Import element:

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

And finally (this part you can do in the GUI), split the existing .content files up into multiple files such that anything you want to appear before the common content is named with a number lower than 100 and anything afterwards with a number higher than 100. (Apparently multiple content files are sorted alphabetically before merging.)

(You can use a different number for the common content if most of the content will normally be added before it, but for my case it was the other way around.)

---

The CommonContentDir property is mildly annoying; I wanted to use $(MSBuildThisProjectDir), but it appears that the SHFB build doesn't recognise this and tries to find the files in the main shfbproj's folder instead.

Another downside of this method is that when you want to add a new file to the common topics, you will have to edit the CommonDoc.targets file manually. But once you do that, it will automatically appear in every help file that references that file, without having to update each shfbproj individually.