Sandcastle August CTP Released

August 28, 2006

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!

Development

MSBuild, Sandcastle

Posted by:

codinginsomnia

6 responses to “Sandcastle August CTP Released”

Don Eddleman

September 28, 2006 at 3:16 pm

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

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

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

$(HelpOutputPath)\art\

$(HelpOutputPath)\scripts\

$(HelpOutputPath)\styles\

<!-- 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; reflection.org /out:reflection.xml"/>-->
<Exec Command="&quot;$(SandcastleBin)\XslTransform&quot; /xsl:&quot;$(SandcastleTransforms)\AddOverloads.xsl&quot; /xsl:&quot;$(SandcastleTransforms)\AddGuidFilenames.xsl&quot; reflection.org /out:reflection.xml"/>

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

LikeLike

anders

September 29, 2006 at 7:09 am

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

/Anders

LikeLike

Reply
Sebastian

September 29, 2006 at 2:28 pm

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

LikeLike

Reply
Ola Petersson

October 5, 2006 at 12:10 pm

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

LikeLike

Reply
Ola Petersson

October 5, 2006 at 12:11 pm

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

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

LikeLike

Reply
anders

October 5, 2006 at 12:13 pm

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

LikeLike

Reply

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!

Coding Insomnia