Sandcastle (software)
Developer(s) | Microsoft |
---|---|
Initial release | 2006 |
Stable release | 2.6.10621.1
/ June 23, 2010 |
Microsoft Public License | |
Website | ewsoftware |
Sandcastle is a
Overview
Sandcastle is a set of
Sandcastle currently features a lightweight
The Visual Studio SDKs for 2005 and 2008 include older CTP versions of Sandcastle,[2] although the latest release is available on GitHub.
Sandcastle tools
Sandcastle consists of several programs, not all of which are used in the typical help build process. Commonly used tools are listed below.
- MrefBuilder uses Common Compiler Infrastructure (CCI) to reflect against managed assemblies and generate an output file.
- XslTransform applies XSL transformations to an XML file. Typically, the specified input file is or derives from a file that is generated by MRefBuilder.
- BuildAssembler executes a build component stack, once for each topic defined in an XML manifest. A build component stack is defined in an XML file with a .config extension. Sandcastle provides several build components that are used in build component stacks to perform tasks such as generating in-memory data indexes, resolving links, including shared content, executing XSL transformations and saving the final output to a file.
Community tools
Because in its current state Sandcastle by itself is rather complex to use, people have come up with tools and scripts that can automate the task for them. This section contains a list of such tools and scripts.
- Sandcastle Help File Builder
- DocProject (Visual Studio 2005/2008)
- Batch file
- PowerShell script
- MSBuild script
- Sandcastle Visual Studio Add-In
- XML Schema Documenter for Sandcastle Help File Builder
Output
Sandcastle produces XML-based HTML files in a chosen presentation style. (This does not mean, however, that the files are XHTML-compliant.) The HTML is defined by XSL transformation files that are included in the particular presentation style being used. A build normally uses only one presentation style at a time.
The HTML files that Sandcastle produces are either conceptual (user) documentation, being the result of a transformation from Microsoft Assistance Markup Language (MAML) topics, or they are reference documentation, which is automatically generated from reflection data and XML documentation comments. These two different types of HTML output share the same presentation style and may be compiled together to produce mixed user/reference documentation.
The processes for building conceptual documentation and reference documentation are similar, with one of the main differences being that conceptual documentation does not require the MRefBuilder program to be used.
Conceptual documentation consists of topics written using a MAML document type schema such as how to, walk-through, troubleshooting and several others. Sandcastle provides a conceptual build component stack (conceptual.config) that resolves shared content and links, and uses XSL files to transform MAML elements into HTML.
Reference documentation is generated automatically for managed
Compiled help
Sandcastle does not produce compiled help output itself (although, the HTML files that it produces can be used as input to HTML help compilers such as the HTML Help Workshop and Microsoft Help 2).
For example, the typical Help 1.x build process starts by running MrefBuilder.exe to produce an XML reflection file for one or more assemblies. The reflection file is then processed by the XslTransform.exe tool multiple times to apply various XSL transformations that add data such as a "doc model" and optional version information. Next, an XML-based topic manifest is generated and used by the BuildAssembler.exe program, which generates HTML topic files from the reflection data and XML documentation comments. An XML-based table of contents (TOC) file is generated and used by CHMBuilder.exe, along with the HTML files produced by BuildAssembler, to generate HTML Help Workshop project, index and TOC files. Finally, the HTML Help workshop is used to generate a compiled help file (.chm).
Some tools are used multiple times during a single build, like XslTransform and BuildAssembler. Depending upon the requirements, other tools and XSL transformations may be used at various stages during the process to modify Sandcastle's output.
Background
The Sandcastle application was developed by
Sandcastle averaged 217 downloads per day [5] during the month of September 2010, making it one of the top 25 most downloaded projects on CodePlex.
On June 6, 2008 the SandCastle project was removed from CodePlex website[6] after a discussion thread on the CodePlex site pointed out that source code was not available; despite CodePlex requiring this and the SandCastle project being touted as "open source".[7] On July 2 the project returned to CodePlex and the source code was published.[8]
History
- July 29, 2006 — the July 2006 CTP version was released, this version mainly focused on performance and scalability. No GUI was present yet, the application did not contain a feature to resolve GACDLLs yet.
- August 28, 2006 — the August 2006 CTP version was released, the bugs fixed in this release seem to primarily for fixing crashes of the application. HTML output of the application is now compatible with Firefox. Some changes were made to the command line interface.
- October 1, 2006 — the September 2006 CTP version was released, bug fixes primarily seem to focus on fixing bugs in the output, and adding better support for some XML comment tags.
- November 11, 2006 — the November 2006 CTP version was released, along with bug fixes other items being supported are a few nDoc tags, and also transforms support Firefox.
- December 10, 2006 — the December 2006 CTP version was released, providing a DXROOT environment variable used by configuration files, an API "ripping" feature, pass-through HTML, and presentation updates that included support for Firefox in the VS 2005 style.
- March 6, 2007 — the March 2007 CTP version was released, adding 4 new and removing 3 XSL transformations, a batch build script and performance improvements.
- March 17, 2007 — the March 2007 CTP Technical Refresh version was released, fixing the "ripping" feature and a utility bug, and including a file that was missing from the previously released installer.
- June 19, 2007 — the June 2007 CTP version was released, providing an ORCAS", a new build component, new executable utilities, and several other enhancements.
- June 27, 2007 — the June 2007 CTP Refresh version was released, renaming the previously released "VS MSDNwas going to continue to be built in the VS 2005 presentation style.
- October 1, 2007 — the September 2007 CTP version was released, with the first appearance of the CHMBuilder, VersionBuilder and DBCSFix tools, a Windows PowerShell build script, presentation style updates (most notably to the VS 2005 style), and without the .NET Frameworkreflection files that were normally included in previous installers.
- October 30, 2007 — the October 2007 CTP version was released, including the .NET Framework files that were missing from the previous release, a new conceptual documentation build process requiring Microsoft Assistance Markup Language (MAML) topics as input, and also improved Firefox support.
- January 16, 2008 — the Sandcastle 2.4.10115 version was released, being the first official non-CTP version of Sandcastle released to the web (RTW). An example graphical user interface (GUI) was provided, including an XSL transformation for Script# and the option to output an ASP.NET website.
See also
References
- ^ Sandcastle Help
- ^ Announcing Sandcastle: Sandcastle blog
- ^ Sandcastle – Microsoft CTP of a Help CHM file generator on the tails of the death of NDoc
- ^ NDoc 2 is Officially Dead
- ^ Sandcastle stats
- ^ Sandcastle project removed from Codeplex
- ^ "Sandcastle 'open source'?". Retrieved 2008-07-02.
- ^ "Sandcastle Source Code published in Codeplex". 2008-07-02. Retrieved 2008-07-02.