The following are the known issues and limitations in the current release of Sandcastle and the help file builder.
Microsoft Help Viewer
Full Microsoft Help Viewer support has been implemented within the Sandcastle Help File Builder. However, please note that only the VS2010 and VS2005 presentation styles contain the necessary resources and XSL transformations to output the necessary metadata. This was Microsoft's decision as noted in the June 2010 release:
The Hana presentation is not supported because its support was already dropped in the latest Sandcastle code before our changes. The Prototype presentation is not supported because we consider it outdated, existing only for compatibility purposes even in the earlier Sandcastle versions.
Support for the Hana and Prototype styles is present in the help file builder but the Sandcastle transformations and resource files will need updating in order to support the generation of Microsoft Help Viewer files with them. There are no plans to do this and it is recommended that you switch to the VS2010 or VS2005 presentation style.
The Hierarchical TOC plug-in is not compatible with MS Help Viewer output and there is currently no fix available. The problem is that the table of contents is generated off of the help topics when the help viewer file is installed and, since there are no physical topics for the namespace nodes added to the intermediate table of contents file by the plug-in, they do not appear in the help file. Updating the plug-in to support help viewer output would have required more work than time would allow. If building other output formats in which you want to use the plug-in, build them separately from the MS Help Viewer output. Support for MS Help Viewer may be added in a future release.
The deprecated raw HTML additional content model, site maps, and file system-based table of contents generation is not supported for help viewer output. All additional topics must be in the form of MAML conceptual content and must be defined in a content layout file. There are too many requirements of the format to support raw HTML files and the deprecated additional content options. The installer for the Sandcastle tools contains an HTML to MAML converter utility if you need one.
Microsoft's Help Viewer Power Tool introduces some changes that are incompatible with content that uses the SelfBranded=True attribute that Sandcastle will emit in the VS2005 presentation style.
Microsoft Help Viewer content generated with the VS2005 presentation style will produce content that in some contexts produces two vertical scrollbars.
The VS2010 presentation style is new as of the Sandcastle 18.104.22.168 release. As it is a brand new style, it has not been fully tested so expect to see some issues. These will be resolved as they are found.
Sandcastle Help File Builder
Not all build errors and warnings have been documented yet. You will recognize these by a TODO: comment where the introduction should be or in the topic body. If you need help for one of these errors or warnings, please ask in the Discussion area of the Sandcastle Help File Builder project at CodePlex.
The standalone GUI does not support source control providers.
Linked items (file items in which the physical file is located in a folder outside the project's folder) are supported but cannot be added from the standalone GUI.
COM object references are supported in the projects but they cannot be added from the standalone GUI.
Due to their non-standard format, managed C++ projects from Visual Studio 2008 and before are not supported as documentation sources or project references. Add the targets and references individually. Visual Studio 2010 and later use a standard MSBuild format for C++ projects and they are supported as documentation sources.
The display of editor windows, the Properties window, or the Preview window sometimes gets corrupted such that the content area disappears or is not sized correctly in the tabbed area of the standalone GUI. Selecting a different file tab and switching back to the affected tab, closing and reopening the affected file/window, or resizing the width of a docked window to force a repaint will work around the issue.
Renaming a folder or file in the Project Explorer in the standalone GUI will not rename any open document editors associated with the renamed folder or file. If necessary, do a File | Save As to save it in the right location or just close and reopen the file if it has not been changed.
A standard tree control is used in the Project Explorer window in the standalone GUI and does not allow selection of multiple tree nodes. As such, all operations within it only affect the currently selected node.
When doing search and replace in a text editor window in the standalone GUI, the highlight on the found text is not always retained when doing a subsequent search/replace. The cursor is positioned correctly though.
In the standlone GUI, when using the dropdown on the editor window's "various elements" toolbar button (shows alert as the default action when first opened), the cursor occassionally disappears from the editor window after the dropdown closes even though it has the focus and text can be entered. Change the focus to another window and back to restore it.