Sandcastle August CTP Released

The team behind Microsoft Sandcastle released a new CTP of Sandcastle yesterday. A couple of changes have been made to the components that will make the previous version of my MSBuild Script for Sandcastle fail. Therefore, you’ll need to download the latest version of the scripts if you want it to work with the August CTP.

New features include:

  • Support for live links to MSDN documentation.
  • Index for CHM-builds.
  • Frontpage for CHM-builds.

Installation instructions are the same as before! And as always, your comments are appreciated!

6 responses to “Sandcastle August CTP Released”

  1. Hey, I hada need to drive the output location of the help files via a msbuild property. To do this I needed to update your script and the targets file for sandcastle. Here is the new script to do the mods to the sandcastle.config
    ‘ This script replaces some hard-coded paths in the sandcastle.config file


    Public Sub Main()
    Dim xmlDoc
    Dim fso
    Dim inFile, outFile, outputPath
    Dim nodeType, sandcastlePath, sandcastleExamplePath
    Dim sharedContentPath, refContentPath
    Dim xmlSourceNode

    Set fso = CreateObject("Scripting.FileSystemObject")
    If WScript.Arguments.Named.Exists("?") Then
    End If
    ' Grab arguments    
    nodeType = WScript.Arguments.Named("nodeType")
    sandcastlePath = WScript.Arguments.Named("path")
    sharedContentPath = WScript.Arguments.Named("shared")
    refContentPath = WScript.Arguments.Named("ref")
    inFile = WScript.Arguments.Named("in")
    outFile = WScript.Arguments.Named("out")
    outputPath = WScript.Arguments.Named("output")
    ' Check arguments
    If Not fso.FileExists(inFile) Then
        WScript.StdErr.WriteLine "ERROR: InFile '" + inFile + "' not found."
    End If
    ' Set defaults
    If nodeType = "" Then
        nodeType = "comments"
    End If
    If sandcastlePath = "" Then
        sandcastlePath = "C:\Program Files\Sandcastle"
    End If
    If sharedContentPath = "" Then
        sharedContentPath = sandcastlePath + "\Presentation\content\shared_content.xml"
    End If
    If refContentPath = "" Then
        refContentPath = sandcastlePath + "\Presentation\content\reference_content.xml"
    End If
    sandcastleExamplePath = sandcastlePath + "\Examples"
    ' Load original sandcastle.config file    
    Set xmlDoc = CreateObject("MSXML2.DOMDocument")
    xmlDoc.preserveWhiteSpace = true
    xmlDoc.load inFile
    ' Find all nodes that contain ..\..\ and ..\
    Set xmlNodes = xmlDoc.selectNodes("//@assembly|//@file|//@files")
    For Each xmlNode In xmlNodes
        ' Replace with full path to Sandcastle files
        xmlNode.text = Replace(xmlNode.text, "..\..", sandcastlePath)
        xmlNode.text = Replace(xmlNode.text, "..", sandcastleExamplePath)
    ' Remove all current content paths
    Set xmlNodes = xmlDoc.selectNodes("//component[@type='Microsoft.Ddue.Tools.SharedContentComponent']/content")
    For Each xmlNode in xmlNodes
        xmlNode.parentNode.removeChild xmlNode
    ' Replace them with new ones
    Set xmlSourceNode = xmlDoc.selectSingleNode("//component[@type='Microsoft.Ddue.Tools.SharedContentComponent']")
    Dim contentNode
    Set contentNode = xmlDoc.createElement("content")
    contentNode.setAttribute "file", sharedContentPath
    xmlSourceNode.appendChild contentNode
    Set contentNode = xmlDoc.createElement("content")
    contentNode.setAttribute "file", refContentPath
    ' Remove save output path node from element so we can add our replacement
    Set xmlNodes = xmlDoc.selectNodes("//component[@type='Microsoft.Ddue.Tools.SaveComponent']/save")
    For Each xmlNode in xmlNodes
        xmlNode.parentNode.removeChild xmlNode
    ' Replace the save path with the new one
    Set xmlSourceNode = xmlDoc.selectSingleNode("//component[@type='Microsoft.Ddue.Tools.SaveComponent']")
    Set contentNode = xmlDoc.createElement("save")
    contentNode.setAttribute "base", outputPath + "\html"
    contentNode.setAttribute "path", "concat(/html/head/meta[@name='guid']/@content,'.htm')"
    contentNode.setAttribute "indent", "false" 
    contentNode.setAttribute "omit-xml-declaration", "true"
    ' Find the parent node for the new data elements
    Set xmlSourceNode = xmlDoc.selectSingleNode("//index[@name='" + nodeType + "']")
    For Each arg in WScript.Arguments.Unnamed
        ' Add new data node
        Dim dataNode
        Set dataNode = xmlDoc.createElement("data")
        dataNode.setAttribute "files", arg
    If outFile = "" Then
        ' If no outfile was given, StdOut is used    
        WScript.StdOut.Write xmlDoc.xml
        ' Otherwise, save the file outFile
    End If

    End Sub

    Public Sub ShowUsage()
    WScript.StdErr.WriteLine “This script replaces some hard-coded paths in the sandcastle.config file.”
    WScript.StdErr.WriteLine “CScript.exe SandcastleConfigurator.vbs /in:””original config”” [/out:””new config””] [/output:””help output path”” [/path:””Sandcastle path””] “”Xml file 1″” “”Xml file 2″” …”
    End Sub

    Here is the new sandcastle targets config (I also updated the path to use the new vs2005 sdk for the help2 compiler

    c:\Program Files\Sandcastle

    <!-- Path to your HTML Help Workshop installation -->
    <HtmlHelpCompilerBin>C:\Program Files\HTML Help Workshop</HtmlHelpCompilerBin>
    <!-- Path to your HTML Help Workshop installation -->
    <HelpCompiler2Bin>C:\Program Files\Visual Studio 2005 SDK\2006.09\VisualStudioIntegration\Archive\HelpIntegration</HelpCompiler2Bin>
    <!--    Vs 2003 should use this path and install vs2003 help sdk
    <HelpCompiler2Bin>C:\Program Files\Microsoft Help 2.0 SDK</HelpCompiler2Bin> -->
    <!-- These properties should be overridden in your MSBuild file -->
    <HelpName Condition="'$(HelpName)'==''">Test</HelpName>
    <ReferenceContentFilePath Condition="'$(ReferenceContentFilePath)'==''">$(SandcastleOutputStructure)\content\reference_content.xml</ReferenceContentFilePath>
    <SharedContentFilePath Condition="'$(SharedContentFilePath)'==''">$(SandcastleOutputStructure)\content\shared_content.xml</SharedContentFilePath>
    <HelpOutputPath Condition="'$(HelpOutputPath)' == ''">Help</HelpOutputPath>




    <!-- Add some more data -->
    <!--<Exec Command="&quot;$(SandcastleBin)\XslTransform&quot; /xsl:&quot;$(SandcastleTransforms)\AddOverloads.xsl&quot; /xsl:&quot;$(SandcastleTransforms)\AddRoot.xsl&quot; /xsl:&quot;$(SandcastleTransforms)\AddGuidFilenames.xsl&quot; /out:reflection.xml"/>-->
    <Exec Command="&quot;$(SandcastleBin)\XslTransform&quot; /xsl:&quot;$(SandcastleTransforms)\AddOverloads.xsl&quot; /xsl:&quot;$(SandcastleTransforms)\AddGuidFilenames.xsl&quot; /out:reflection.xml"/>

    Finally, in an msbuild you just need to override the output path via a property:

    Feel free to make available to all.

    Don Eddleman


  2. Thanks Don! I’ll incorporate these changes in the next version!



  3. How i can generate only htm docs? i need for making documentation available online for my open source projects


  4. I am getting invalid image links when generating CHM documentation.

    This is the end sequence of what I what I see when i select properties of a not working image link:

    This is the end sequence of what I see when i select properties of a not working image link:

    I do use the September CTP release of SandCastle and had to fix a few small things from your August build scripts (file structure under SandCastle\Presentation was changed). Do you think it is related to this version difference?

    Other ideas?



  5. Sorry about the error in my previous comment. This is a WORKING image link:



  6. I’m afraid I haven’t had a chance to upgrade the scripts to the September CTP yet. I’ll try to get around to that in the next couple of days. It sounds quite likely that that is the problem here..


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

About Me

Consultant, Solution Architect, Developer.

Do note that this blog is very, very old. Please consider that before you follow any of the advice in here!


%d bloggers like this: