System Requirements
-------------------
In order to use Sandcastle and the Sandcastle Help File Builder (SHFB) you will need the following tools:

    Required:
        - .NET Framework 4.0 (Needed to run the Sandcastle and SHFB tools)

    Optional:
        - HTML Help Workshop (Used for building Help 1 CHM files)
        - HTML Help 2 Compiler from the Visual Studio 2005 or 2008 SDK (Used for building Help 2 HxS files)

In order to build the source code you will need the following tools:

    Required:
        - .NET 4.5.1 (Used to build the reflection data)
        - Visual Studio 2010 SP1 or later (Used to build the C# projects for the tools)
        - NuGet Package Manager Extension (Required to download the NuGet packages used by the main projects)

    Optional:
        - Visual Studio 2010 SDK SP1 or later (Required for VSPackage development)
        - VSPackage Builder Extension (Required by the VSPackage project, VS2010 only)
        - Wix 3.x Toolset (Used to create the MSI installer).


Folder Layout
-------------
Deployment - This folder contains the deployment resources (the installer and all related files).  These are
used when creating the distribution package for SHFB.

Documentation - This folder contains documentation projects for Sandcastle and SHFB as well as related
documentation projects for such things as the MAML Guide.

SHFB\Deploy - This folder contains some supporting files and will contain the SHFB and the Sandcastle tools and
their configuration files once they are built.  All of the projects place their build output here so that the
entire toolset can be tested in a common location that matches the release build folder layout.  Some of the key
folders beneath it are listed below.

SHFB\Deploy\Data - This folder contains the reflection data files for the core .NET Framework.  These are used
during the BuildAssembler step to insert information about the base .NET Framework class members.  A script is
included to rebuild this information as it is not included with the source code.  It is currently set to build
using the .NET Framework 4.5.1 assemblies.

SHFB\Deploy\Extras - This folder contains optional tools that are not part of Sandcastle or SHFB such as the
HTML to MAML converter and the web project code providers.

SHFB\Deploy\PresentationStyles - This folder contains the presentation style files used during the
BuildAssembler step to apply formatting to the API and conceptual topics.  The content of this folder is
generated by the Presentation Styles project in the source code folder.

SHFB\Deploy\ProductionTransforms - This folder contains various XSL transformations used during the build to
alter the reflection file data, produce build manifests, table of contents files, etc.  The content of this
folder is generated by the XSL Transform project in the source code folder.

SHFB\Deploy\Schemas - This folder contains the XML schemas for the reflection data file and the MAML topic
files.  Note that Sandcastle does not strictly conform to the MAML schema.  Where necessary, it has been updated
to reflect these differences and to extend it to provide additional features that make using MAML with
Sandcastle better. The MAML schema files can be copied to the Visual Studio XML schema folder to provide
IntelliSense within Visual Studio for MAML topic files.

SHFB\Deploy\Snippets - This folder contains Visual Studio snippet files used to insert common block and inline
MAML elements.  These can be copied to the Visual Studio snippets folders in your My Documents folder for use
from within Visual Studio.

SHFB\Source - This folder contains the source code for SHFB and the Sandcastle tools.  All output is sent to the
SHFB\Deploy folder.  Some aggregate solutions exist in this folder that can be used to load groups of related
projects.  The individual Sandcastle tool projects have their own solution files in their project folders to
allow working with them individually as well.

TestCaseProject - This folder contains a test project with various test cases and test documentation projects.


Running SHFB and the Sandcastle Tools with the Source Code Version
------------------------------------------------------------------
When you install SHFB and the Sandcastle tools, it creates a system environment variable called SHFBROOT that
points to the release version (typically C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder).  To
use the source code version of the tools, you must edit your system environment variables to point SHFBROOT at
the SHFB\Deploy folder of the source code installation.  For example, set it to C:\CP\TFS01\SHFB\SHFB\Deploy\.
Your location may differ based on where you extracted the code.  This will allow you to run the source code
version of the tools while leaving the release build in place in the standard location.  You can freely make
changes to the tool source code and presentation style files and test them as needed.  Pointing SHFBROOT back at
the standard location for the release version of the tools will let you run it to compare the results against
your changed version.

Before using the source code version, you will need to build the tools and the reflection data files.  To do
this, open a command prompt, change into the root folder and run the MasterBuild.bat script.  This will build
the tools and place them in the SHFB\Deploy folder ready for use.  By default, the Release version is built.
To build a debug version, pass in the command line parameter Debug.  Once that completes, change into the
SHFB\Deploy\Data folder and execute the BuildReflectionData.bat script.  This will generate the reflection data
files for the .NET Framework into a temporary folder.  Rename the folder it creates to ".NETFramework".

Reflection data can be built for other frameworks as well but you must have the latest version of the framework
and all of the requisite tools and supporting SDKs installed as well.  Other supported frameworks include
.NETCore, .NETPortable, .NETMicroFramwork, Silverlight, WindowsPhone, and WindowsPhoneApp.  To build the
reflection data for a different framework, pass its name on the command line.  For example:

    BuildReflectionData .NETCore
    BuildReflectionData .NETPortable
    BuildReflectionData WindowsPhoneApp

Once built, rename the folder by removing the version number on the resulting output folder.