This topic describes the additional tools that are required to use the Sandcastle Help File Builder along with some general configuration information.

Guided Installation

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.

Download the latest Sandcastle Help File Builder Guided Installer

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.

Requirements

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 Microsoft's Sandcastle (currently the June 2010 release as of January 30, 2012).

    Note

    This is the set of documentation tools created by Microsoft. The help file builder uses them to produce the help file topics.

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

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:

  1. Check the user environment variables. If you see a copy of the DXROOT environment variable there, delete it.

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

  3. 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\Sandcastle unless you installed it in an alternate location.

Note

You may need to reboot the system in order for any environment variable changes to take effect.

Recommended Additions

The following tools and patches are optional but you will find them useful and it is highly recommended that they be installed as well.

  • Download the latest community-maintained patches for the Sandcastle presentation styles from the Sandcastle Styles CodePlex project site. This is essential if you will be producing conceptual content as it fixes a number of bugs and adds many new features that will make your conceptual content appear much better.

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

  • To register MS Help 2 files both for testing and as part of your product installation, download the shareware tool H2Reg.exe from The Helpware Group.

  • If you are going to document website projects, download the Custom Web Code Providers. These make it easy to document website projects by extracing the XML comments files to a location of your choice when the website is deployed.

Optional Items

The following items are not required to use Sandcastle or the help file builder but you may find them useful.

See Also