Version 1.7.0.0

Version 1.7.0.0 was released on June 2nd, 2008.

• Potential Breaking Changes
• Non-breaking Changes in Behavior
• Conceptual Content Support
• Additional Content Models Deprecated
• Other Changes in This Release
• Documenting Website Projects

• The default configuration for all cached build components has changed. They no longer store their cache files in the help file builder folder. Instead, they store them in the %APPDATA%\EWSoftware\Sandcastle Help File Builder\Cache folder. This removes the need to run the help file builder as an administrator under Vista x64 when using the cached build components. If you are using them, you must remove them from the project and re-add them so that they pick up the new default configuration. You can also delete the cache files from the old location. You can find them in the .\BuildComponents\Cache folder under the main help file builder installation folder.

• The default configuration for the Cached Framework Comments Index Data custom build component has changed. If you are using it, you must remove it from the project and re-add it so that it picks up the new default configuration. You can also delete the Comments.cache file as the naming method has changed and the old version is obsolete. You can find it in the .\BuildComponents\Cache folder under the main help file builder installation folder or in the new folder noted above if you moved the cache files.

• A new insertConceptual configuration option was added to the build component definition configuration file. It is used to define a build component's placement within the conceptual.config file. The existing insert option will continue to be used for the reference build configuration file (sandcastle.config). If either element is omitted from a component's definition, it will not be merged into the given configuration file. This is a change from prior behavior which inserted the component at the start of the configuration file if a placement option was not specified.

• Components defined in the project's ComponentConfigurations property will be merged into the appropriate configuration files based on the presence of the insert and insertConceptual configuration elements. As such, the settings will be shared and the conceptual content will match the reference content in appearance.

• A distinction is now made between JScript and JavaScript in the code colorizer to match the usage in Sandcastle. JScript now has its own rule set and is considered to be JScript.NET. JavaScript is regular JavaScript. Code examples using "JScript" or one of its variants as the language will be connected to the JScript language filter. Code examples using "JavaScript" or one of its variants as the language will be connected to the JavaScript language filter.

• "XAML" has been added as a separate language in the code colorizer rules so that it can be correctly connected to the XAML language filter.

• To support conceptual content, the following changes have been made to the build steps:

  • The CreateConfig build step has been renamed CreateBuildAssemblerConfigs. This step will now create the conceptual.config file as well.

  • The BuildHelpTopics build step has been renamed BuildReferenceTopics. This builds the reference (API) help topics.

  • Added the build steps CopyConceptualContent, CreateConceptualTopicConfigs, MergeTablesOfContents, and BuildConceptualTopics.

  • The BuildHelpTopics.bat script file has been renamed BuildReferenceTopics.bat. A new script file, BuildConceptualTopics.bat, was added to build the conceptual help topics.

  • If both conceptual content and additional content are included in a project, conceptual content will take precedence. Any additional content will appear after the conceptual content in the table of contents. Likewise, if specified, the default topic and split TOC topic in the conceptual content will take precedence. The equivalent settings in the additional content will only be used if not specified in the conceptual content.

• A bug in the standard ResolveConceptualLinksComponent causes any specified inner text on <link> tags to be ignored and instead it always uses the title. I have reimplemented the component to fix that bug and added a couple of new features (see below). As such, any links you may have in your conceptual content files will start showing the inner text when built with the help file builder. You may need to review your documentation and either remove or update the inner text to something more appropriate on your links.

• The requirement that an XML comments file be associated with an assembly has been removed and the build behavior has changed for cases where the XML comments file for an assembly is blank. In such cases, the XML comments file is ignored and no comments will be associated with the assembly. This allows you to build a help file for an assembly without a comments file and is useful in a couple of the new plug-ins.

• Wildcards are now supported in the AssemblyPath and XmlCommentsPath properties on each of the documented assemblies. This allows you to add one entry that will include multiple assemblies and/or comments files for documenting. This is also useful for documenting website projects in which the last part of the assembly names and comments files can change each time the website is published.

• The behavior of the console mode builder's -assembly and -comments command line options has been adjusted accordingly to account for the new wildcard support.

• The log file will list all assemblies and XML comments files copied during the ValidatingAssemblies build step so that you can verify it found the correct files. Warnings are also issued if duplicate files are copied that overwrite previously copied files in the working folder.

• The PurgeDuplicateTopics project property has been removed as duplicates are now handled via the MergeDuplicates.xsl Sandcastle transformation immediately after MRefBuilder has been executed.

• The Additional Content property category is now called Additional and Conceptual Content.

• The ContentSiteMap and TopicFileTransform properties are now sub-properties of the AdditionalContent property. You must expand it to see them. This change was made to make their association with the additional content clear and to avoid incorrectly associating them with the new ConceptualContent property which does not make use of them.

• The AdditonalContent and ContentSiteMap properties now share a common property editor to make it easier to edit their settings together and to make their association more apparent.

• The help file builder will now include the necessary .NET Framework comments files based on the setting of the FrameworkVersion property. This ensures that all of the necessary comments files are included when using the .NET 3.0 and .NET 3.5 Frameworks.

• The CachedCopyFromIndexComponent used for the comments index now names its cache files after the language and framework version.

• Renamed the SyntaxFilters.ScriptSharp value to JavaScript as that is what it renders and this makes it more apparent that it can be used for other projects such as those that use the AjaxDoc plug-in. The old value will be translated to the new value automatically when an older project that contains it is loaded.

• Added a customized version of the JavaScript declaration syntax generator component that will correctly document normal JavaScript. It will only convert the first letter of each member name to lowercase when documenting a Script# project.

• The ShowMissingComponent messages are now localized. The messages appear in each of the SharedBuilderContent_[lang].xml files in the help file builder's .\SharedContent folder. The component also inserts the "missing namespace" message as well rather than the build process. A contentFile configuration option was added to the component that is used to specify the file containing the localized messages. If omitted, it defaults to using the English message text.

• Due to a significant change in the way the language filters work in the Hana and Prototype presentation styles, the PostTransformComponent no longer connects example code blocks to the language filter in those presentation styles. Given the way they are implemented, this feature would be better handled in the transformations and script files themselves.

• The default topic transformation files now contain a default set of MSHelp:Attr elements for (name/value) DocSet/NetFramework, DocSet/{@HtmlHelpName}, Locale/{@Locale}, and TargetOS/Windows where the replacement tags will be replaced with the appropriate project option at build time. Any additional XML data island elements from the transformed topics will be merged with the default set.

• Generate1xIndex.bat, Generate1xTOC.bat, GenerateWebsiteTOC.bat, and TocToWebContents.xsl have been removed. In their place is a new script template, ExtractHtmlInfo.bat, that runs a new tool that extracts TOC and keyword information from the HTML files to produce a better index and TOC with proper encoding support for foreign languages for the HTML Help 1 file and a TOC for websites.

• If a new project is created from a Visual Studio 2008 solution or project, the FrameworkVersion property will be set based on the highest target framework specified within the Visual Studio project. This also applies to Visual Studio projects imported by the console mode builder.

• Support for building conceptual content in addition to reference (API) content has been fully integrated into the build process. The new ConceptualContent property in the Additional and Conceptual Content property category allows you to manage the conceptual content.

• The current conceptual content editor allows you to add, edit, and delete tokens, images, and conceptual topics in the project. The layout of the conceptual topics in the editor will determine their layout in the table of contents when built similar to how the site map works for additional content. Enhanced design support will be added in a later release.

• Full support for colorized code blocks is included. Simply specify the code elements as you would in XML comments using all of the same options. This include support for imported code blocks.

• The post-transform component is also supported and thus logos can be added to the conceptual topic headers. The conceptual build shares the same component configurations as the reference build so they will maintain the same look.

• Documentation for conceptual content and its use with the help file builder is rather sparse at the moment. This will also be addressed in a future release.

• An improved version of the ResolveConceptualLinksComponent has been added with the following features and fixes:

  • Broken links use the None style rather than the Index style so that it is apparent that they do not work.

  • The inner text from the conceptual link is used if specified. See the Potential Breaking Changes section above as this may affect any existing conceptual content that you have.

  • On broken links, when the showBrokenLinkText option is true and there is no inner text, the target value is displayed.

  • Conceptual link targets can include an optional anchor name from within the target such as "#Name" (i.e. <link xlink:href="3bdb6eb5-5e23-51c2-0051-3e224f82c201#Section2" />).

  • Unnecessary whitespace is removed from the link text.

  • If the companion file contains a <linkText> element and no inner text is specified, its value will be used for the link text rather than the title. This allows for a shorter title or description to use as the default link text.

See the Conceptual and Additional Content topic for details.

• Added support for the <inheritdoc /> XML comments tag.

• Added the GenerateInheritedDocumentation build step to handle generation of inherited documentation.

• Added the FeedbackEMailLinkText project property. If specified with a feedback e-mail address, the text in this property will be used as the link text. If left blank, the e-mail address will be used.

• The BinaryTOC and IncludeFavorites properties are now found in their own category in the property grid (HTML Help 1).

• Added the MS Help 2 property category containing the following new project properties:

  • CollectionTocStyle - This defines the collection table of contents style used when plugged into an MS Help 2 collection.

  • HelpAttributes - A collection of additional help attributes to add to the XML data island in each generated API topic.

  • HelpFileVersion - Specify the version number that should be applied to the help file.

  • IncludeStopWordList - Indicate whether or not to include the stop word list used to identify words to omit from Help 2 full text search index.

  • PlugInNamespaces - Specify a comma-separated list of namespaces that the collection will be plugged into when deployed using H2Reg.exe.

• When performing a build that includes producing an MS Help 2 file, a valid set of collection files and a configuration file for H2Reg.exe are now produced as well. They are located in the output folder with the help file.

• Added the project property BuildLogFile that allows you to specify an alternate location and name for the build log file. If not set, it defaults to the filename LastBuild.log and stores it in the output folder identified by the OutputPath project property.

• The log file is now in XML format to allow for running it through an XSL transform to make it more readable. A default XSL transform is supplied with the GUI (Templates\TransformBuildLog.xsl) and it is used in the GUI's log viewer dialog.

• Added the IndentHtml project property as a debugging aid. When set to true, the HTML rendered by BuildAssembler is indented to make it more readable. Leave it set to false to produce more compact HTML.

• Added a "-vsimport=solution|project,configName" option to the console mode builder that lets you specify a Visual Studio solution or project file from which to import the assemblies and XML comments files to document for the named configuration.

• Added a "-helpattr=name,value" option to the console mode builder that lets you specify additional MS Help 2 help attribute name/value pairs to add to the XML data island in each API topic.

• The Namespace Summaries dialog box has been completely reworked. It now uses a partial build to gather the namespace information which will prevent the "assembly not found" errors that could occur due to nested dependencies that could not always be properly detected. In addition, namespaces can now be filtered by assembly and/or by some search text or a regular expression. A list of assemblies in which the selected namespace appears is also shown.

• If comments for a class called NamespaceDoc within a namespace appear in the XML comments files, those comments will be used as the namespace comments. To keep the class from being included in the help file, leave off the public keyword and mark it with a CompilerGenerated attribute. See the Using NamespaceDoc and NamespaceGroupDoc Classes help topic for details.

• Added a new keepSeeTags option to the Code Block Component that allows <see> tags that appear within the code to be passed through as-is so that they are rendered as clickable links to the referenced help topic (project topics or online MSDN topics). This option is also supported in additional content files on colorized <pre> tags but will only resolve links to project help topics.

• Added a new filter option to the Code Block Component that allows you to specify whether or not a code block is connected to the appropriate language filter. If omitted or set to true, it will be connected. If set to false, it will not be connected.

• The attribute name language is now recognized by the colorizer and the code block component as an acceptable alternative for the lang attribute name.

• The CodeBlockComponent and PostTransformComponent where reworked to allow their use in conceptual content builds. This allows code blocks in conceptual content files to be colorized using the same options as in reference content builds.

• Added the MS Help 2 Attributes component which is used to insert additional help attributes into the XML data island in each generated API topic. Support for this component is built into the help file builder via the HelpAttributes project property.

• Abstract classes that implement the IPlugIn interface are now ignored when looking for plug-ins to load.

• Added the following new plug-ins:

  • Additional Reference Links Plug-In - This is used to add additional reference link targets to the Reflection Index Data and Resolve Reference Links build components so that links can be created to other third party help in a Help 2 collection or to other online MSDN content.

  • DBCS Fix for CHM Builds Plug-In - This is designed to modify the HTML files and alter the build so as to overcome the encoding issues encountered when building HTML Help 1 (.chm) files for various foreign languages.

  • Hierarchical TOC Plug-In - This is used to rearrange the table of contents such that namespaces are nested within their parent namespaces rather than appearing as a flat list of all namespaces at the root level.

  • Script# Reflection File Fixer - This is used to fix up the reflection file produced from assemblies created by the Script# compiler so that they are documented correctly.

  • Table of Contents Exclusion Plug-In - This is used to exclude API members from the table of contents via the <tocexclude /> XML comment tag.

• The AjaxDoc Plug-In now supports the ApiFilter property. Other plug-ins like it that generate their own reflection information can also apply the API filter manually by using the new ApplyManualApiFilter method on the BuildProcess object.

• The Completion Notification plug-in now supports an optional XSL transform filename option. If specified and the log file is to be attached to the e-mail, the log file is ran through the transform and the resulting HTML file is attached in its place. If not specified, the raw log file is attached. The default transform can be used by specifying {@SHFBFolder}Templates\TransformBuildLog.xsl.

• The Output Deployment plug-in now correctly supports relative file paths for the deployment locations. Relative file paths will be relative to the project file folder.

• The table of contents entries for additional content items can now be split such that some appear before and some after the API topics. The ContentPlacement property's setting will be ignored if the table of contents is split via a custom tag in one of the additional content files or a site map is defined that specifies a split table of contents. In such cases, items prior to the entry with the "split" option will appear before the API content. The item with the "split" option and all items after it will appear below the API content.

• Fixed a bug in the component configuration merging code that could cause the wrong component configuration to be replaced when more than one instance of the same component appeared in the project configuration.

• Fixed a bug in ShowMissingComponent that caused the link in auto-documented constructors to point to the constructor topic rather than the class topic.

• Updated the ShowMissingComponent so that it auto-documents constructors on the class's member and overloads list pages as well.

• Added the ShowMissingTypeParams project property. When set to true (the default), it will show a "missing" message if generic type or method type parameter documentation is missing. This maps to the equivalent parameter added to the ShowMissingComponent.

• The IntelliSenseComponent, PostTransformComponent, and VersionInfoComponent were updated to handle multiple assembly references in an API topic.

• Fixed a bug in the PostTransformComponent that caused the VS2005 member list pages to be laid out incorrectly when using a logo and the version builder's framework menu was present.

• Fixed a bug in the code colorizer rules for "//" style line comments that contained a "/*" which was incorrectly interpreted as the start of a block comment.

• Fixed the XML colorizer rules so that they recognize string literals that span lines.

• The code block component and additional content files can now extract commented regions from within XML, XAML, and SQL scripts. Just surround the snippet with comment lines containing #region and #endregion markers.

• All logo placement options are now supported by the default topic transformation files.

• If <MSHelp:Keyword Index="K" Term="[term]" /> tags exist in the XML data island in additional content files, the terms will now appear in the CHM file's index. The SHFB help file's additional content is now indexed using this method.

• Fixed a JavaScript error in the website output that occurred if the full text search did not find any results.

• The Index.aspx page now supports a topic query string parameter. If set to the path of a page in the website, it will display that page instead of the normal default topic page.

• Thanks to Ferdinand Prantl for supplying the code necessary to add a keyword index pane to the ASP.NET index page.

• Thanks to TimerLandChapel for providing additional translations for the Japanese content files.

• Added some more common problems and solutions to the FAQ.

• The entire project is now licensed using the Microsoft Public License (Ms-PL) to match the license used by Sandcastle itself.

A set of custom code providers is now available that simplifies obtaining XML comments files for C# and VB.NET website projects. In combination with the new wildcard support in the help file builder's Assemblies to Document list, producing a help file for websites is now a much simpler task. Use the custom code providers available as part of the Sandcastle Help File Builder.

Other Resources