- If you haven’t already done so, install the Sandcastle December CTP.
The scripts rely on a completly unmodified installation, so don’t make
any changes to it (especially not the sandcastle.config file).
- Unzip the contents of Sandcastle.zip to your MSBuild folder (usually c:\Program Files\MSBuild)
- Unzip the contents of SandcastleTest.zip to wherever you like to keep your sample projects.
- Open up the SandcastleTest.sln solution file and build the project.
- Open a Visual Studio 2005 Command prompt, navigate to the SandcastleTest folder and run the one of the following commands:
- MSBuild Documentation.proj
To build both a CHM and an HxS file
- MSBuild Documentation.proj /t:DocumentationHelp2
To build an HxS file.
- MSBuild Documentation.proj /t:Documentation
To build a CHM file.
- MSBuild Documentation.proj
- Cross your fingers, and when the process is finished, look for the Help\SandcastleTest.chm and/or the Help\SandcastleTest.HxS files!
- In order to actually view an HxS-file you’ll need to register it with MSHelp. Or, an easier way (just to see that it works) is to use the free H2Viewer-utility.
Frequently Asked Questions
How do I change the format of the generated .htm-files?
The Sandcastle installation (as of Dec 2006) supplies two versions, the “Prototype” version and the VS2005-like version. When using the MSBuild-script for Sandcastle, VS2005 is selected by default. However, you can change this by adding the following tag to the PropertyGroup-node of your Documentation.proj-file:
It is also possible to create your own format. The easy way would probably be to take a copy of either the Prototype or the VS2005 directory (found under “C:\Program Files\Sandcastle\Presentation”) and make the changes you want. Just put the name of your own directory in the <Presentation>-tag.
How do I replace the copyright notice at the bottom of each page?
How do I remove the “This is pre-release documentatio” notice at the top of each page?
How do I add my own header/footer to each page?
The header and footer added to all generated pages and some other common content is found in a file called shared_content.xml (located in “C:\Program Files\Sandcastle\Presentation\prototype\Content” or “C:\Program Files\Sandcastle\Presentation\vs2005\Content” depending on which presentation style you’ve selected.)
You can provide your own version of this file by adding the following tag to the PropertyGroup node of your Documentation.proj-file:
Can I switch between friendly file-names and using GUIDs?
Why, of course you can! The default is to use GUIDs as they are the most safe.
If you want to use friendly-style file names, simply add the following tag to the PropertyGroup node of your Documentation.proj-file:
Can I use the new member-file support from the December CTP?
Yes, but it seems to be fairly buggy at the moment.
Add the following tag to the PropertyGroup node of your Documentation.proj-file:
When using this with the VS2005-like presentation format, the BuildAssembler tends to take forever (at least it does for me). Also, there are missing items in reference_content.xml that you’ll have to add manually, see this comment on the Sandcastle blog.