Known Issues and Limitations
The following are the known issues and limitations in the current release of Sandcastle and the help file builder.
.NET Core Builds
The following are the known issues with .NET Core builds. These will be addressed in later releases if possible.
If one is specified, the XSL transform in the Completion Notification plug-in currently fails on .NET Core. It can be cleared in the plug-in settings to send the raw log file in the meantime.
Microsoft Help Viewer
The deprecated raw HTML additional content model and site maps are 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 HTML to MAML Converter is available to help you convert legacy HTML content to MAML topics.
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 Issues area of the Sandcastle Help File Builder project on GitHub.
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 standalone 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 occasionally 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.