When copying additional content files, if a file with a .topic extension is encountered, an attempt is made to transform it into a .html file by running it through an XSL transformation. This allows you to apply a common look and feel to the additional content topics that matches the API topics. The build process tries to locate a file item in the project with a BuildAction of TopicTransform and will use it if found. If left blank, a default transformation is used that is based on the currently selected presentation style. It transforms the topics to give them the same style of header and footer as the API topics. Support is also included for adding a logo to the page header. Additional features such as the language filter are not supported. If you decide that you need to add additional features or replace the transformation, you can do so by creating a file and adding it to the project with a BuildAction of TopicTransform.

Three default transformations (Hana.xsl, Prototype.xsl, and VS2005.xsl) are supplied. The .topic files are XML files that contain the following elements.

If you create your own transformation file, you are free to define whatever structure you like for the topic files. The above is just a guideline. Below is an example of a typical topic file for the three default transformations:

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE bodyText [ <!ENTITY nbsp "&#160;"> ]>

<topic xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
    <!-- The page title -->
    <title>Welcome to the Sandcastle Help File Builder</title>
    <!-- Add a logo -->
    <logoFile filename="images/Sandcastle.jpg" altText="Test logo"
        placement="left" alignment="left" />
    <!-- Include an additional style sheet -->
    <styleSheet filename="Styles/Styles.css" />
    <!-- MS Help 2 data island -->
    <xml xmlns:msxsl="urn:schemas-microsoft-com:xslt">
        <MSHelp:Attr Name="AssetID" Value="Test" />
        <MSHelp:Keyword Index="K" Term="IndexKeyword1" />
        <MSHelp:Keyword Index="K" Term="IndexKeyword2" />
        <MSHelp:Attr Name="Locale" Value="en-us"></MSHelp:Attr>
        <MSHelp:Attr Name="Abstract" Value="An abstract for the file" />
    </xml>
    <!-- The body text for the topic -->
    <bodyText>
This is the <b>body text</b> for the additional content page.
    </bodyText>
</topic>

The .NET XML parser will not recognize many of the common HTML entities such as   and will throw an exception. In order to handle them, you can use the numeric form rather than the name form (i.e. #&160; for the non-breaking space). The other alternative as shown in the example above is to add a DOCTYPE declaration at the start of the file that defines the unknown entities and the value to which they should be converted. This allows you to use the name form in the body text. Note that you will need to add the DOCTYPE declaration to each topic file that contains the unknown entities.

The XSL transformation will be passed a variable called pathToRoot that defines the path to the help file's root folder. This allows you to add script, style sheet, and image tags that prefix the filename in the tag's attributes with the pathToRoot variables during the transformation. For example:

<link rel="style sheet" type="text/css"
    href="{$pathToRoot}styles/presentation.css" />

<img>
    <xsl:attribute name="src">
        <xsl:value-of select="$pathToRoot"/>
        <xsl:value-of select="@filename"/>
    </xsl:attribute>
</img>

Both the topic files and the XSL transformation files are treated like any other additional content file. As such, they can contain project property replacement tags and shared content item references that will be converted to the matching project property value or shared content item value at build time. See the Project Properties and Shared Content topic for more information.

Other Resources