Coding Insomnia

6 responses to “Sandcastle August CTP Released”

1. 

   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

   Reply
2. 

   anders

   September 29, 2006 at 7:09 am

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

   /Anders

   LikeLike

   Reply
3. 

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

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

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

   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