Click or drag to resize
Sandcastle Help File BuilderTopic File Transformation

This topic describes the topic file transformation option.

Caution note Caution

Deprecated

The additional content model of adding extra content to a help file has been deprecated. While it will continue to be supported and will not be removed, it will not receive any more features or updates. Going forward, conceptual content is the preferred method of adding non-reference content to the help file. The additional content feature can still be used to override stock content and add supporting files to the help file.

Topic File Transformation

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.

The Default Transformations

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

Element

Description

topic

This is the root element and there should only be one in the file. All other elements are children of this one.

title

This element defines the title for the topic.

headerTitle

This is an optional element that defines the text that appears above the topic title. If not defined, the help file's title is used as defined by the project's HelpTitle property.

logoFile

This element can be used to add an optional logo to the topic. If you do not want a logo, you can omit this element. The filename attribute defines the path to the logo file. This path is the actual path relative to the root of the generated help content. The file itself should be defined as additional content so that it is copied to the appropriate location. For topics in folders, you do not need to add relative path indicators (i.e. ../) as a variable is passed to the transform that will set the appropriate path to the root automatically (see below). The height and width attributes can be used to specify the height and width of the image. If omitted, the image will be displayed using its actual size. By using these attributes, you can scale a larger image down or scale a smaller image up to get a better fit. The altText attribute lets you specify some alternate text that can appear for the image. The placement attribute allows you to specify where the image is placed (to the left, to the right, or above the topic title). When set to above, the alignment attribute specifies how the image is aligned (left, right, or centered).

styleSheet

This element can be used to define an additional style sheet to include in the transformed topic. This is useful for adding styles for HTML tags that are not present in the selected presentation style's default style sheet such as h1, h2, etc. The filename attribute identifies the style sheet and the same comments above regarding the logo file's path and inclusion as additional content apply here as well. If no additional style sheet is needed, you can omit this element.

xml

This element is used to add an optional XML data island to the topic that defines the MS Help 2 collection attributes. If omitted, no data island will be added to the topic. The content of this element is user-defined. Add any necessary MS Help 2 attributes that you need for your help file.

bodyText

This element is used to define the body text for the page. It should contain the HTML for the topic's main content.

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:

Example Topic File
<?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 &nbsp; 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 pathToRoot Variable

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:

Example use of pathToRoot
<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>
Project Properties and Shared Content

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.

See Also