Coding Insomnia

Installation instructions:

1. 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).
2. Unzip the contents of Sandcastle.zip to your MSBuild folder (usually c:\Program Files\MSBuild)
3. Unzip the contents of SandcastleTest.zip to wherever you like to keep your sample projects.
4. Open up the SandcastleTest.sln solution file and build the project.
5. 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.
6. Cross your fingers, and when the process is finished, look for the Help\SandcastleTest.chm and/or the Help\SandcastleTest.HxS files!
7. 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:

<Presentation>Prototype</Presentation>

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:

<SharedContentFilePath>c:\the\path\to\your\shared_content.xml</SharedContentFilePath>

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:

<FilenameStyle>Friendly</FilenameStyle>

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:

<DocStyle>VS</DocStyle>

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.