Version 1.9.4.0
Version 1.9.4.0 was released on April 15th, 2012.
Potential Breaking Changes
The R:Project topic ID is now suffixed with the value of the project's HtmlHelpName property value to keep it unique so that MS Help Viewer output works correctly with a root namespace container. Any spaces in the value are replaced with underscores. This may break existing projects if you manage project summary comments in an external file. You will need to update the member ID of the R:Project entry to contain the help name used in the project (i.e. R:Project_MyHelpFileName).
Sandcastle 2.7.0.0 Support
The following changes were made to support the latest Sandcastle release:
Removed BuildReflectionData.bat as the script is now part of the Sandcastle file set.
Removed the SandcastleMRefBuilder project and assembly. The assembly binding redirection code has been moved into Sandcastle's AssemblyResolver class in MRefBuilder. The Assembly Binding Redirection plug-in has been updated to use the Sandcastle version now.
Removed the JavaScriptDeclarationSyntaxGenerator from the project and changed all references to use the new version in the Sandcastle SyntaxComponents assembly.
Removed ResolveConceptualLinksComponent from the project and changed all references to use the new version in the Sandcastle BuildComponents assembly as the changes have been merged into it.
Removed FixScriptSharp.xsl from the project templates. The changes it contained have been merged into Sandcastle's copy of that file.
A BuildAssemberVerbosity property was added to let you specify what messages the BuildAssembler tool will report. This can help to significantly reduce the build log size for large projects.
Updated the CodeColorizerLibrary and SandcastleComponents projects to .NET 4.0 as the Sandcastle tools are now built with .NET 4.0.
Thanks to Don Fehr for the changes needed to support the new Sandcastle VS2010 presentation style.
Help File Builder
Fixed a bug in the topic previewer that caused it not to navigate to the topic being edited when opened.
Fixed a bug in the build engine that caused it to not add the help library manager and install scripts to the list of MS Help Viewer files.
Fixed a bug in the HTML extract tool that caused it not to close the final index file element if it had children.
Fixed a bug in the conceptual content layout file editor that caused a crash when an empty container node was selected while adding a new topic to the file.
Reworked how the topic previewer and entity references windows load content layout files so that they do not cause open files to look like they have been edited when they contain items marked as invisible in the TOC.
Added a new XamlConfiguration build action value for use with XAML syntax configuration files. Also added the related XAML syntax item template. This is used to define XAML syntax configuration settings for the BuildAssembler XAML Usage syntax generator.
Added support for rendering links in token elements that are within relatedTopics elements in the topic previewer.
Added the BrandingPackageName property to allow specification of a branding package name for MS Help Viewer files.
Added an option to the Assembly Binding Redirection plug-in to allow using the GAC to resolve unknown assembly references. This may help in cases where a copy of the reference assembly is not available on the file system.
Added an option to the output deployment plug-in to rename the MSHA file to HelpContentSetup.msha.
The help viewer install and remove scripts produced as part of the MS Help Viewer build format have been temporarily modified to provide some support for installing and removing content from Help Viewer 2.0. They both call the Help Viewer 2.0 content manager tool directly to install or remove the content if the script is passed the command line parameter "H2". Full support will be built into the Help Library Manager Launcher tool in a future release.
Added support to the API build configuration files to resolve conceptualLink elements within XML comments files. This allows adding links to conceptual topics within XML comments that will work regardless of the help file format. To use them, add a conceptualLink element with a target attribute set to the GUID of the conceptual topic to which it should generate a link. Inner text is also supported. If omitted, the topic title will be used.
Thanks to Thomas Levesque for the following:
Additions to the website files to allow showing a direct link to the topics.
The suggestion to use the JavaScript serializer for the full text index files. The new JSON format reduces the size of the full text index files quite a bit compared to the binary format and makes it possible to implement other index and keyword search pages using alternate back ends such as PHP. The use of the new serializer does require a minimum framework version of .NET 3.5 for the ASP.NET website pages.
The PHP website files. To view the website via the PHP files, open the index.php page.
Sandcastle Tools General Changes
Version 2.7.0.0 was released on April 15th, 2012. This release was issued before officially being merged with the Sandcastle Help File Builder project. It fixed almost all of the known tool bugs and merged all changes from the Sandcastle Styles patch into the Sandcastle XSL transformations.
Rearranged the source project folders to match the installed folder layout. This makes testing a development build much easier as you can point DXROOT at the .\Sandcastle\Main folder and have it work like a release build.
Created separate solutions for each tool so that they can be loaded, built, and tested individually. Reflector was used to get the source code for the tools that were missing source code and projects were added for them too.
All tools are now built using .NET 4.0. This will allow taking advantage of newer features in the runtime added since .NET 2.0. This does not change the ability to run the tools against assemblies built with prior framework versions. That is still supported.
Removed all GlobalSuppressions.cs files from all projects. Many of us do not have a version of Visual Studio that supports code analysis within the IDE. Instead, individual FxCop projects have been created for each project. Some clean up has been performed based on the initial scans. Warnings still exist in several projects and have been left for review until later.
Signed all assemblies with a new key file and standardized the assembly attributes.
Added Data\BuildReflectionData.bat and Data\BuildReflectionData.proj to properly rebuild the reflection data files.
Updated the XSL style sheet version number to 2.0 in all XSL transformations. A bug in .NET 4.0 prevents the <xsl:sort> function from working when using XSL version 1.1.
Merged the Sandcastle Guided Installer, the Language Pack, Sandcastle MAML Guide, Web Code Providers, and the HTML to MAML Converter projects from Sandcastle Styles into the Sandcastle project. These are located under the .\Extras folder.
The Sandcastle Guided Installer has been rewritten as a WPF application. It uses flow documents rather than HTML resources for the pages which are much easier to extend and work with in the code.
Created a new setup project to install Sandcastle. This version includes the content from the .\Extras folder as additional installable options. This installer also gives Sandcastle a presence on the Program Files menu with links to the included help files, the project web site, and the example GUI. The setup project is located in the .\Extras folder too as it isn't part of the core Sandcastle code and uses the WiX tools.
Schemas
Added a new optional attribute to the reflection data schema for parameter elements. This is needed to properly document optional parameters that use OptionalAttribute and have no default specified using assignment.
Updated the MAML schemas to include all of the new elements and attributes added by the Sandcastle Styles patch and adjusted a few elements to reflect how Sandcastle uses them. This allows for proper validation of MAML topics in Visual Studio.
Command Line Library
Reworked the command line option classes to fix various FxCop warnings and to correctly implement support for required options.
MRefBuilder Tool
Moved the content of the CCI\ and Reflection\ folders into the MRefBuilder project and made them members of the project so that they are compiled directly into MRefBuilder.exe to match prior releases of Sandcastle.
Fixed ExtensionMethodAddIn.cs so that it doesn't add extension methods to enumerations and static classes (Sandcastle work item #8852).
Fixed ExtensionMethodAddIn.cs so that it ignores unexposed namespaces and types. This prevents it from scanning unnecessary namespaces and types and stops a crash caused by it scanning compiler generated types created by the code contracts post-processing tool (Sandcastle work item #11066).
Fixed Method.ImplicitlyImplementedInterfaceMethods in Nodes.cs so that it recognizes interface member matches when the return type is generic (Sandcastle work item #22970).
Fixed GetTemplateMember() and ParametersMatch() to properly check for template parameters when there are method overloads in which one uses a generic type and the other does not (i.e. Contains(T) and Contains(Guid)). This was Sandcastle work item #1908 and most likely fixed work item #7803 too as it looks similar and the test case works as expected now.
Fixed TypeNode.Attributes so that it will not get stuck in an endless loop if a type's attribute references the type being parsed (Sandcastle work item #2253).
Fixed TypeNode.NestedTypes so that it will not get stuck in an endless loop when a type contains a nested type that itself implements a nested type from within the containing type.
Fixed IsExposedMember() and IsExposedType() in ApiFilter.cs so that they ignore unrecognized type and member visibility values (Sandcastle work item #2967 and #2969).
Fixed IsExposedMember() so that it compares generic members using the Name<T> and Name{T} syntax so that it gets a match either way (Sandcastle work item #5593).
Fixed IsExposedExpression() in ApiFilter.cs so that it doesn't exclude a type in an attribute expression as long as the hidden type has exposed members thus exposing the type.
Fixed IsExposedNamespace(), IsExposedType(), and IsExposedMember() in ApFilter.cs so that they exclude members with names containing characters that are not valid in XML (i.e. obfuscated member names).
Fixed MemberDictionary.Contains() so that when checking for matching members it compares generic template parameters by name to match members with generic parameters correctly. This fixes an issue where it treats overridden members as overloads when they contain generic template parameters. This was Sandcastle work item #4553 and most likely fixed work item #11303 too as it looks similar and the test case works as expected now.
Fixed OrcasNamer.WriteTemplate() so that it uses the correct template parameter names which do not always match the base class's template parameter names (i.e. Collection<TControl> vs. Collection<T>). Sandcastle work item #5594.
I am not sure if one of the other changes fixed it or if it was fixed already in the source code, but Sandcastle work item #2903 (Spurious references to parameterized class with inner class) is fixed as the test cases in it work as expected.
Added a check for exposed members in unexposed types in IsExposedType() in ApiFilter.cs. Such cases effectively expose the type and it should be included whenever this check occurs for it. Without the check, it was incorrectly excluding types in several locations.
Added CompilerGeneratedAttribute check to IsExposedType() in ExternalDocumentedFilter.cs as public members can sometimes be compiler generated (i.e. generated types for public fields that use the fixed keyword). This was a new issue I found while testing the fixed keyword syntax issue.
Added FixedBufferAttribute to the default MRefBuilder.config API filter as an exposed attribute so that it gets passed through. This is needed in order to properly document fixed members in the syntax section.
Added OptionalAttribute to the default MRefBuilder.config API filter as an exposed attribute so that it gets passed through. This is needed in order to properly document optional parameters.
Added code to write out the new optional attribute for optional parameters. This is needed to properly document optional parameters that use OptionalAttribute and have no default specified using assignment. The syntax components and XSL transformations have been updated to make use of it to document optional parameters and their values (Sandcastle work item #9627).
Merged my changes into the AssemblyResolver class to provide support for assembly binding redirection. Added example configuration info for it to MRefBuilder.config (Sandcastle work item #1014).
BuildAssembler Tools
Added the proxy configuration settings that work around the HTTP 407 and HTTP 417 errors in comments to the BuildAssembler.exe.config file.
Added support for specifying a verbosity level on the configuration element. This can significantly reduce the build assembler output and makes it easier to see warnings as it is much less chatty. The default verbosity is Info so that its default behavior matches prior releases.
Build Components
Important
Custom build components that override Dispose() will need to be updated to override protected void Dispose(bool disposing) rather than public void Dispose() as the Sandcastle source code release correctly implements the IDisposable pattern.
Fixed ResolveReferenceLinksComponent2 so that it does not write out unnecessary parentheses on unresolved property elements (Sandcastle work item #1987).
Fixed ResolveReferenceLinksComponent2 so that references to enumerated field types are redirected to the containing enumerated type so as to produce a valid link target (Sandcastle work item #2221).
Fixed the C#, C++, VB.NET, F#, and J# syntax generator components so that they output numeric attribute values. In the event that an unrecognized attribute parameter type is encountered, the syntax generators write out the value as-is. Array parameters are also supported now but the reflection data does not contain the values. As such, it writes out the array type and a generic "{ ... }" placeholder where the values would go. The information is probably there but it would probably require changes to the CCI code to include it (Sandcastle work item #6779)
Fixed the XamlUsageSyntaxGenerator.WritePropertySyntax() so that it generates syntax for properties with abstract return types as long as there is a type converter for it (i.e. Brush) Sandcastle work item #5466.
Added support for a duplicateWarnings attribute that can be added to the data elements of the index element on the CopyFromIndexComponent. When set to false, it suppresses duplicate index key warnings. This is useful for comments files where there can be duplicate keys but it isn't an issue. The default is true if not specified to maintain the behavior from past releases and report the warnings (Sandcastle work item #11844).
Added support for optional arguments to the C#, C++, VB.NET, F#, and J# syntax generator components. I did not enclose them in brackets as it looked rather odd when attributes were present and the assignment is a dead giveaway that it is an optional parameter. As such, it uses the standard syntax but I did update the XSL transformations to include "(Optional") after the parameter name in the Parameters section of the topic (Sandcastle work item #9627).
Added support for attributes on property getter/setter methods to the C#, C++, VB.NET, F#, and J# syntax generator components (Sandcastle work item #973).
Made the unsafe code checks consistent across all syntax generators and added a check for the FixedBufferAttribute to the apiIsUnsafeExpression XPath expression.
Added fixed keyword support to the C# and C++ syntax generators (Sandcastle work item #10107).
Added interior_ptr<> support to the C++ syntax generator. Added a fix-up regular expression to the Sandcastle help file builder too so that the comments are included in the member page (Sandcastle work item #2299).
Merged my changes and bug fixes into the MSHCComponent. The changes include:
Support for a sortOrder option on the TOC elements to allow the sort order of the elements to be defined to set the proper placement of the TOC entries when parented to an entry outside of the help file and to parent the API content within a conceptual content folder.
Fixed a bug that caused a "duplicate key" error under certain conditions.
Fixed an incorrect XPath expression that was letting duplicate metadata through.
Added my JavaScriptDeclarationSyntaxGenerator to the SyntaxComponents assembly. Modified FixScriptSharp.xsl to include a scriptSharp element to indicate to the syntax generator that it should apply the casing rules to member names. This allows the added syntax generator to work with normal JavaScript and Script# projects alike (Sandcastle work item #1999).
Merged my changes and bug fixes into the ResolveConceptualLinksComponent (Sandcastle work item #2193):
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.
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".
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.
DBCSFix Tool
Updated the file masks to use *.htm? to find both .htm and .html files (Sandcastle work item #1072).
Fixed the incorrect check for LCID value (Sandcastle work item #1072).
Fixed SubstituteAsciiEquivalents() so that it actually performs the substitutions for encodings other than Windows-1252 (Sandcastle work item #1072).
Switched to using EnumerateFiles() which is more efficient for large projects.
ChmBuilder Tools
Switched to using EnumerateDirectories() and EnumerateFiles() which is more efficient for large projects.
Presentation Styles
This release added the new VS2010 presentation style developed by Don Fehr. Consider this a beta release as we work out the bugs. The following fixes and feature enhancements from the Sandcastle Styles patch and some unreported bugs from the discussion pages were applied to the presentation style files:
Sandcastle work item #6858: The omitVersionInformation parameter is missing from VS2005\transforms\main_sandcastle.xsl
Sandcastle work item #1943: ResolveArtLinksComponent is wrong in the configs
Sandcastle work item #6785: Enumerated type members no longer contain a description in VS2005 style
Sandcastle work item #2268: The sub-section toggles do not work in Hana and VS2005 because they are not given a unique ID
Sandcastle work item #2603: "this" argument modifier not shown for extension methods
Sandcastle work item #1965: XAML code samples cannot be hidden (VS2005 style)
Sandcastle work item #4476: Cannot link to overloads page
Sandcastle work item #938: Hana and VS2005 styles generate unnecessary Overloads pages and TOC entries
Sandcastle Styles work item #6572: Unresolved types don't show up in overloaded method signatures in TOC entries and topic titles
Sandcastle work item #2255: Remaining presentation Style Issues
Sandcastle work item #1249: Conceptual: codeEntityReference is sensitive to whitespace
Sandcastle work item #2034: Conceptual: XLinks in relatedTopics section requires explicit text
Sandcastle work item #6788: Support for definition list type is missing.
Sandcastle work item #2258: Conceptual: ddue:copyright processing is broken
Sandcastle work item #2264: ddue:list should support the "nobullet" style
Sandcastle work item #2949: Sections containing nothing but an image or a list of link elements are not rendered
Sandcastle work item #3652: MAML - XSLT Generates Self-Closing Tag for Bookmarks
Sandcastle work item #8879: Some pre elements are missing xml:space="preserve"
Sandcastle Styles work item #11465: FireFox website output issues
Sandcastle work item #2421 and #2435: Case of Presentation.css is not consistent in transformations. This causes case-sensitive web servers to miss the style sheet.
Sandcastle work item #2416: vs2005: summary from outer class ends up on inner class member page
Sandcastle Styles work item #5362: Help 1 Sticky Language Filter
Sandcastle work item #2274: Conceptual: Hana style, External link in a token not rendered in relatedTopics
Sandcastle work item #2951: JavaScript syntax section is not shown in the Hana style
Sandcastle work item #2260: Anchor tag styles need to be fixed
Sandcastle work item #2261: Conceptual: All three styles, normalize the space on the abstract
Sandcastle work item #2265: ddue:table handling needs fixing
Sandcastle work item #2266: Rendering of ddue:definitionTable isn't consistent in presentation styles
Sandcastle work item #2950: autoOutline displays "Related Topics" instead of "See Also"
Sandcastle work item #2275: Conceptual: ddue:math should apply templates to its inner text
Sandcastle work item #2060: Conceptual: Formatting is not applied to some in-line MAML elements
Sandcastle work item #2273: Support linkAlternateText and linkTarget in externalLink
Sandcastle work item #1854: Conceptual: Don't Display Summary in Topic
Sandcastle work item #2282: Prototype syntax sections have unnecessary leading whitespace
Sandcastle work item #939: Version Builder Issues
Sandcastle Styles work item #226453: Version Builder is broken in the June 2010 release
Sandcastle work item #2257: Conceptual: Hana does not wrap code blocks in <div class="code">
Sandcastle work item #998: Hana and Prototype styles need to add CHARSET attribute to topics
Sandcastle work item #2259: Conceptual: Hana and Prototype are missing some namespace declarations
Sandcastle work item 2267: ddue:schemaHierarchy and indent templates are missing from Prototype
Sandcastle work item 2272: The Prototype See Also section doesn't have a #seeAlsoSection anchor
Sandcastle work item #1613: seealso tags within an overloads tag not listed
Sandcastle work item #6787: Add missing resource items to Hana and Prototype styles
Sandcastle work item #1978: APIName Attributes Incorrect (Hana and Prototype)
Sandcastle work item #974: Support External Hyperlink Target with Appropriate Default
Sandcastle work item #6803: Support term element in bullet and number list types
Sandcastle work item #6789: Support starting number on numbered lists
Sandcastle work item #2948: Add address attribute support to several elements
Sandcastle work item #2270: Conceptual: Support NamedUrlIndex keywords in metadata
Sandcastle work item #2174: Conceptual: Pass-through HTML (using a markup element), supersedes Sandcastle work item #933
Sandcastle work item #6786: Enumeration topics should show the value of each enumeration member
Sandcastle work item #1835: Conceptual: Glossary Improvements
Sandcastle work item #1795: Better implementation of the <note> tag
Sandcastle work item #2256: Better implementation of the ddue:alert element
Sandcastle work item #2189: mediaLink and mediaLinkInline should be handled as separate templates
Sandcastle work item #2142: Conceptual: autoOutline Changes
Sandcastle work item #2082: Auto-generated Bibliography (No dependency on build components)
Sandcastle work item #6790: Add code contract support for VS2005 style
Sandcastle work item #2271: List formatting doesn't look good (all three styles)
Sandcastle work item #2947: style sheet updates needed to correct spacing and alignment
Sandcastle work item #1950: Conceptual: Glossary term requires termClass attribute
Sandcastle work item #2021: Conceptual: codeSection template ignores valid code languages
Unreported feature request: Replace conceptualLink elements in the reference content with anchor links to the actual MSDN pages
Unreported feature request: Support conceptualLink elements in code XML comments to allow linking to conceptual topics from API member docs
Unreported bug: VS2005 CommonUtilities.js fails under MS Help Viewer 2