This is the second in a 3-part series on using the Sandcastle tools to produce great looking (and hopefully useful) internal documentation. In this post we provide an overview of the Sandcastle template system, which is what provides the look-and-feel of the final documentation.

In the Part I of this series we covered how to get up and running with Sandcastle and generate a CHM documentation file using the build.prof MSBuild project. By default, the MSBuild project that ships with Sandcastle generates the documentation with the vs2005 template. You can control the output style by adding one of the following options to the command line:

/property:PresentationStyle=vs2005
/property:PresentationStyle=hana
/property:PresentationStyle=prototype


Below you can view and compare screen shots of a VS2005, Hana, and Prototype formatted help files (click to see full-size images).

The templates themselves consist of a set of files (configuration and XSL transforms), and can be found under the \Presentation directory. Each template is in a separate directory, and has the following sub-folders:

• Configuration: contains Sandcastle config files (you probably won’t need to changes these);
• Content: XML files containing resource strings;
• Icons: images that are used in the resulting compiled HTML documentation;
• Scripts: javascript files that are used in the resulting compiled HTML documentation;
• Styles: CSS files containing formatting for the resulting compiled HTML documentation;
• Transforms: XSLT that convert the XML document file to HTML documentation.

Unless you are planning to develop your own template, which is definitely not for the faint-hearted and certainly outside of the scope of this blog post, you’ll want to contain yourself to editing the configuration and resource files. The following is an example of an edit that you might want to look at.

One of the things you might have noticed with the documentation that is produced using the VS2005 template is the really nice looking feedback form at the bottom of each page. This is shown below:

In order to get this to work properly, you need to set the target email address that will receive the feedback. Change directory to \Presentation\vs2005\Content and open the feedBack_content.xml file in your favourite text editor (mine is Notepad++). The second set of XML elements are what we are interested in. In particular, you can set the target email address by modifying the line as follows:

<item id="feedback_alias">myemail@example.com</item>

Once the help file is recompiled, clicking on the”Send Feedback” button will open a new email with the correct email address pre-populated.

There’s obviously plenty more to know about the Sandcastle template system. The aim of this post was simply to provide an overview and understanding of the templates.

Part III will cover how to generate documentation in the Microsoft Help 2 (HxS) format, which is the format that the Visual Studio help system uses.