One of the tool combinations that we find invaluable at OpenNETCF is Sandcastle and the Sandcastle Help File Builder. We’ve been using these tools to build our documentation for our products and I’ve come across a few limitations and workarounds for the December CTP that I’ve not seen discussed elsewhere so I’d like to share them here.
The biggest issue that I’ve found is the lack of support for setting the DocSet attributes in the help topic metadata. The particular attribute allows you to associate a set of help topics by assigning a name to the set. This is useful as you can use it to filter the topics displayed in the Content, Index and Search sections of the Document Explorer.
The DocSet attribute looks something like this when added to a help topic:
<MSHelp:Attr Name="DocSet" Value="NETCompactFramework" />
This XML fragment will assoicate a help topic with a Document Set (DocSet) called "NETCompactFramework". So if you filtered by documentation by the .NET Compact Framework option in the Visual Studio Help (note: this option is available only if you have the MSDN Library installed), then all the help topics with this DocSet attribute will be listed. As an example, below is a screenshot of the Visual Studio Help filtered to only show the Smart Device Framework documentation.
Sandcastle uses a series of XML transformations to turn your XML documentation generated by Visual Studio into something that can be integrated with the Visual Studio Help system. The XSL file responsible for setting the various metadata attributes is called utilities_metadata.xsl and can be found in %ProgramFiles%\Sandcastle\Presentation\vs2005\Transforms.
To get Sandcastle to correctly add the DocSet attributes to each help topic, I had to add the following lines just below the <xml> node in the insertMetadata template:
<MSHelp:Attr Name="DocSet" Value="OpenNETCF.SDF2" />
<MSHelp:Attr Name="DocSet" Value="NETFramework" />
<MSHelp:Attr Name="DocSet" Value="NETCompactFramework" />
If you are thinking that I'm hardcoding these attributes and that they will appear in each help topic I ever generate with Sandcastle, you are correct. I will need to modify the OpenNETCF.SDF2 DocSet attribute for each product that I generate help documentation for.
In the Sandcastle March CTP, things don't get a lot better as there is still no support for custom DocSet attributes.