Sandcastle August CTP Released 6

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 thoughts on “Sandcastle August CTP Released

  1. Don Eddleman Sep 28,2006 15:16

    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

    Main()

    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
    ShowUsage
    WScript.Quit(0)
    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.”
    ShowUsage
    WScript.Quit(1)
    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)
    Next

    ‘ 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
    Next

    ‘ 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
    xmlSourceNode.appendChild(contentNode)

    ‘ 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
    Next

    ‘ 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”
    xmlSourceNode.appendChild(contentNode)

    ‘ 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
    xmlSourceNode.appendChild(dataNode)
    Next

    If outFile = “” Then
    ‘ If no outfile was given, StdOut is used
    WScript.StdOut.Write xmlDoc.xml
    Else
    ‘ Otherwise, save the file
    xmlDoc.save 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

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


    c:\Program Files\Sandcastle
    $(SandcastlePath)\ProductionTools
    $(SandcastlePath)\ProductionTransforms
    $(SandcastlePath)\Presentation


    C:\Program Files\HTML Help Workshop


    C:\Program Files\Visual Studio 2005 SDK\2006.09\VisualStudioIntegration\Archive\HelpIntegration


    Test
    $(SandcastleOutputStructure)\content\reference_content.xml
    $(SandcastleOutputStructure)\content\shared_content.xml
    Help










    $(HelpOutputPath)\art\


    $(HelpOutputPath)\scripts\


    $(HelpOutputPath)\styles\


















































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

    Feel free to make available to all.

    Cheers,
    Don Eddleman

  2. anders Sep 29,2006 07:09

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

    /Anders

  3. Sebastian Sep 29,2006 14:28

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

  4. Ola Petersson Oct 5,2006 12:10

    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:
    MyPath\helpname.chm::/html/..\art\collapse_all.gif

    This is the end sequence of what I see when i select properties of a not working image link:
    MyPath\helpname.chm::/art/pubclass.gif

    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?

    /Ola

  5. Ola Petersson Oct 5,2006 12:11

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

    MyPath\helpname.chm::/art/pubclass.gif

  6. anders Oct 5,2006 12:13

    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..

Comments are closed.