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!
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
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
Thanks Don! I’ll incorporate these changes in the next version!
/Anders
How i can generate only htm docs? i need for making documentation available online for my open source projects
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
Sorry about the error in my previous comment. This is a WORKING image link:
MyPath\helpname.chm::/art/pubclass.gif
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..