• In the HelpFileFormat property, the HtmlHelp1x and HtmlHelp2x member values were renamed to HtmlHelp1 and MSHelp2 to match the common naming conventions. The combination values were removed since they were not used and were rather unwieldy. Existing projects using the old values will be updated to use the new values when opened and re-saved.

• Build component and plug-in changes:

  • Component configuration filenames are now required to have a .components extension.

  • Plug-in assembly filenames are now required to have a .plugins extension.

  • The separate Build Components and Plug-Ins folders have been combined into one common Components and Plug-Ins folder under the Application Data folder.

  These changes allow plug-ins and build components that share dependencies to reside in the same folder. It also prevents the help file builder from scanning assemblies and configuration files that are not related to plug-ins and build components. The help file builder will scan its own installation folder for component configuration files and plug-in assemblies. You may also place them there to support non-standard installations of the help file builder (i.e. XCOPY deployments to build servers). See the Special Folder Locations topic for more information.

• The type of the SyntaxFilters project property has been changed from an enumerated type to a string. This was done to allow custom syntax filter generators (see below). The value is a comma separated list of syntax generator IDs. The designer still uses a dropdown control that lets you pick multiple values from the available generator IDs. In addition, the following special values can be entered in the designer:

  • None - No syntax filters will be included.

  • Standard - The standard syntax filters will be included (C#, VB.NET, and C++).

  • All - All syntax filters will be included.

  • AllButUsage - All syntax filters will be included except those with "Usage" in their ID (i.e. VisualBasicUsage and XamlUsage).

  Entering or selecting a set of filters that match one of the above special values will result in that value appearing as the property's value. In addition, entering various alternate language names in the designer property editor will automatically translate them to the appropriate syntax filters. For example, entering "cs, vb" will get translated to "CSharp, VisualBasic". Unknown ID values will be ignored.

• Syntax filter generators are now defined using an external XML file which allows you to add custom syntax filter generators to the help file builder without having to modify its code and template files. Filter definition files should have a .filters extension and should be located in the custom build components and plug-ins folder. They can also be located in the help file builder's installation folder if you need XCOPY deployment for a build server. See the default filters file in the help file builder installation folder for an example (SandcastleBuilder.filters).

An unofficial release of Sandcastle was made available in July 2009 as a source code only download. Support for it in this release of the help file builder only includes using the XSL transformations and the related resource files from it. The executables from the last official Sandcastle release (May 2008) should be used with them rather than the ones built from the source code. Fully supporting the July 2009 executables requires some modifications to the help file builder source code itself which would break compatibility with the existing official release. The help file builder source code is available if you want to rebuild it for use with the July 2009 executables. However, this is not necessary.

The current release of the Sandcastle Styles patch includes all changes from the July 2009 release in addition to all of the other bug fixes and updates ready for use with the May 2008 executables. You only need the updates from the July 2009 release if you want to include the F# syntax filter or if you want to create MS Help Viewer files. If not, you can continue using the May 2008 release with or without the Sandcastle Styles patch.

• Added support for .NET 4.0.

• F# projects created by Visual Studio 2010 can now be used as documentation sources. However, they will most likely fail to load because they use MSBuild 4.0 specific attributes in their projects files. The help file builder is currently built to use MSBuild 3.5 and cannot interpret the newer attributes. If this happens, you must add the assembly, XML comments file, and references to the help file builder project individually.

• Added F# syntax rules to the code colorizer. Use fs, F#, FSharp, or FSScript as the language identifier on code XML comment elements.

• Added x86, x64, and Win32 as standard platform types in new help file builder projects. These can be added manually to existing projects if needed. Open the project file in a text editor and do the following:

  Copy

  <!-- Find these two property group definitions -->
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
  </PropertyGroup>
  
  <!-- Paste these property group definitions in after them -->
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|x86' ">
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|x86' ">
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|x64' ">
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|x64' ">
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|Win32' ">
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|Win32' ">
  </PropertyGroup>

• Fixed a bug in TOC.js that caused the content pane to disappear at certain zoom levels in Internet Explorer 8.

• Fixed a bug in the code colorizer that caused it to truncate the title if a single quote appeared within it.

• Fixed a bug in the API filter that caused excluded nested classes to appear in the help file if their parent class was included.

• Members of the API filter in which a majority but not all of the child elements are excluded now use a different background color to make them stand out and better indicate their mixed state.

• Added the ExtensionMethodAddIn add-in to the MRefBuilder configuration file template to generate the additional extension method reflection information used by the Sandcastle XSL transformations.

• Added an AutoDocumentDisposeMethods option to the ShowMissingComponent and a corresponding project property in the Show Missing Tags category. This is used to indicate whether or not dispose methods are automatically documented if they are missing the <summary> tag and for classes with compiler generated dispose methods. It will be False in existing projects but defaults to True in new projects.

• Added a new ResourceItems build action. A file with a .items extension will automatically receive this build action when added to a project. It is an XML file that contains resource item overrides that are used by the Sandcastle XSL transformations. The editor for resource item files will load all known resource items and let you edit their values. Changed items are saved to the project's resource item file.

• The ShowFeedbackControl project property has been removed. The new resource item file editor can be used to edit the related feedback control resource items to add it to a project if it is wanted.

• If a project file documentation source imports another project into itself that contains reference items, the reference items in the imported project are now ignored so that they do not prevent the documentation source project file from being parsed. If they are needed by MRefBuilder, the imported reference items can be added as reference items in the help file builder project.

• When viewing the log file in the Build Output window, the content can be filtered to show only warnings and errors in each build step. The filter setting is persisted across sessions. It is also used when viewing output from a failed preview topic build.

• Added ASP.NET as an option to the SyntaxFilters property (AspNet).

• Added F# as an option to the SyntaxFilters property (FSharp).

  Note
  This requires the XSL transformations and resource files from the July 2009 Sandcastle source code release. These changes are available for use with the May 2008 release by downloading and applying the Sandcastle Styles patch. A copy of the F# syntax declaration generator component is included with the help file builder that is compatible with the May 2008 Sandcastle release.

• Added the MSHelpViewer value to the HelpFileFormat property options. Preliminary support for building Microsoft Help Viewer files has been added.

  Note

  This requires the XSL transformations and resource files from the July 2009 Sandcastle source code release. These changes are available for use with the May 2008 release by downloading and applying the Sandcastle Styles patch. However, full MS Help Viewer support is not yet implemented since Sandcastle does not appear to add the necessary table of contents metadata to the topics yet. This will be fully implemented as the tools become available and changes are made in Sandcastle to support it.

Other Resources