This topic describes the additional tools that are required to use the Sandcastle Help File Builder along with some general configuration information.
Due to the number of products that need to be installed to get a working build environment, a guided installation package has been created to simplify the process. The guided installer contains most of the necessary parts and various optional components. For those parts that cannot be distributed such as the help compilers, it contains instructions on where to get them and how to install them if you need them.
When using the guided installation, you can skip the Requirements section below as it takes care of all of the required steps. See the Recommended and Optional sections for additional tools not included in the guided installation that you may find useful.
The latest version of the Sandcastle Help File Builder can always be found at the Sandcastle Help File Builder CodePlex project site. In addition, you will need the following:
The .NET Framework 4.0.
The latest version of the Sandcastle tools (currently the April 2013 v22.214.171.124 release as of April 7, 2013).
This is the set of documentation tools originally created by Microsoft. The help file builder uses them to produce the help file topics. Microsoft officially discontinued development in October 2012. The Sandcastle tools have been merged with the Sandcastle Help File Builder project and are developed and supported there now as part of that project.
In order to use the help file builder, the following additional tools are required based on the types of help files that you want to produce. Each must be installed prior to building a help file of that particular type:
The HTML Help Workshop for building HTML Help 1 (.chm) help files.
The MS Help 2 compiler for building MS Help 2 (.HxS) help files. This must be downloaded and installed as part of the Visual Studio 2005 SDK v4.0 or the Visual Studio 2008 SDK v1.0. Note that the latest version of the Visual Studio 2008 SDK does not contain the Help 2 compiler so you must download the 1.0 version. The latest release can be installed after it if you need it.
The Help Library Manager and Help Library Agent for installing and viewing MS Help Viewer (.mshc) help files. These are installed as part of Visual Studio.
The tools can be installed in any order. However, be aware that if installing the Visual Studio 2005 or 2008 SDK to obtain the Help 2 compiler that both contain outdated versions of Sandcastle. This can cause the DXROOT environment variable used to locate the Sandcastle tools to be incorrect. After installing either SDK, do the following:
Check the user environment variables. If you see a copy of the DXROOT environment variable there, delete it.
If there is a user copy of the PATH environment variable, remove any path to the SDK version of Sandcastle that it contains. If that is all it contains, it can be deleted.
Check the system environment variables to ensure that a DXROOT environment variable does exist and that it points to the correct location of the Microsoft Sandcastle tools (not the help file builder). Usually this will be C:\Program Files (x86)\Sandcastle unless you installed it in an alternate location.
You may need to reboot the system in order for any environment variable changes to take effect.
The following tools are optional but you will find them useful and it is highly recommended that they be installed as well.
To view MS Help 2 files without registering them, you can use the H2 Viewer (free for personal use). You can configure the help file builder to use it for viewing Help 2 output via the User Preferences dialog.
To view MS Help Viewer files with a full table of content and index support rather than in the default browser, you can use the H3 Viewer (free for personal use). You can configure the help file builder to use it for viewing MS Help Viewer output via the User Preferences dialog.
If you are going to document website projects, install the Custom Web Code Providers included as part of the Sandcastle tools installer. These make it easy to document website projects by extracting the XML comments files to a location of your choosing when the website is deployed.
The following items are not required to use Sandcastle or the help file builder but you may find them useful.
If you are documenting .NET 1.1 applications and need the Help 2 compiler tools, you can download the Visual Studio .NET Help Integration Kit 2003.
For a Visual Studio add-in used to create XML comments automatically, check out SubMain's GhostDoc.
If you need to convert HTML additional content topics to MAML, you can use the HTML to MAML Converter utility included with the Sandcastle tools installer.