Version 1.8.0.0 (Alpha)

Version 1.8.0.0 was released on October 20th, 2008.

A New Project File Format and a New Look

The main goal of this release was to rework the help file builder project file format and build engine to ready them for use in a Visual Studio package that will provide full Visual Studio integration in a future release. This resulted in a number of major changes.

  Note

Although Visual Studio integration is planned for a future release, the standalone GUI will still be produced and supported for those who do not use Visual Studio.

  • The help file builder now uses an MSBuild project file to store its settings. Along with the associated MSBuild tasks and target definition file, this allows you to build help file builder projects using MSBuild. It also makes it possible to create a Visual Studio package that will let you work with help file builder projects from within Visual Studio just like any other project in a solution file (planned for a future release).

  • A SHFBROOT environment variable is now used to locate the root help file builder folder for various tools. The value should point to the root installation folder. The installer will create the environment variable automatically but you may need to reboot in order for it to take effect. You will also need to manually define it on any system to which you manually copy the help file builder tools.

  • With the use of an MSBuild project file format, SandcastleBuilderConsole.exe was rendered obsolete and has been removed. Use MSBuild, Team Build, or another such tool to build a help file project from the command line or in automated scripts.

  • Due to the change in format, help file builder projects from prior versions will need to be converted before use with the latest release. Once converted, they cannot be changed back or used with prior versions of the help file builder.

  • Several project properties have been removed or altered and their functionality has moved elsewhere in the standalone GUI. See the Where Did That Feature Go? section below for details.

  • The NDoc-style GUI has been replaced by one that looks more like Visual Studio. This was required as by moving to an MSBuild project format, the conceptual content and supporting files are now part of the project and appear in the project file as build items. The new GUI provides a Project Explorer window that lets you manage these items. The Properties window retains the NDoc-like property grid and is used to edit the various non-file project properties.

  • The underlying namespace in the code for the GUI changed so any prior user preferences will not be carried forward when you first open the new version. You can set them up again via the File | User Preferences menu option.

      Note

    It is no longer necessary to define external editors in the User Preferences dialog to edit files such as XML files, style sheets, HTML files, etc. Common text-based file types recognized by filename extension will be edited within the GUI by default. As such, you do not need to add any custom editor associations for them in your user preferences.

  • Assemblies to Document are now referred to using the more generic term Documentation Sources. A documentation source can be an individual assembly (executable or DLL), an individual XML comments file, a Visual Studio project file (C#, VB.NET, or J#), a Visual Studio solution file containing one or more of the noted project types, or a wildcard item that results in a list of one or more of the previously mentioned file types. Documentation sources are now managed using the Documentation Sources project node in the Project Explorer window.

      Tip

    Given that solutions and projects are supported as documentation sources, you may find it easier to add them as documentation sources instead of the assemblies, comments, and references that they contain. When a solution or project is used, these items are imported from them automatically at build time.

  • A Configuration and a Platform option can be defined to determine which assemblies are used in solution and project documentation sources.

  • Dependencies are now referred to using the term References. The old Dependencies property has been removed from the Properties window. They are now managed via the References project node in the Project Explorer window. References can be GAC entries, assembly files, COM objects, or Visual Studio project files.

      Note

    While COM references are supported in the project file and will be handled correctly at build time, they cannot be added to the project via the standalone GUI. An alternative is to add the COM-callable wrapper assemblies as references instead.

  • All build step script files (.bat) have been replaced with MSBuild project files (.proj) with corresponding build tasks. This allows for better extensibility either directly or through plug-ins. In addition, it allows for support of Unicode values in such properties as the help filename.

  • The code has been heavily refactored and some project option collection classes and property names have been changed to reflect their purpose in relation to the MSBuild project file format. Others have been removed as they are no longer relevant. As such, expect build errors in any custom plug-ins that you have created. Most of the affected objects and properties are listed below.

    Old Item

    New Item

    DependencyItem

    Replaced by ReferenceItem (GAC or file), COMReferenceItem (COM object), and ProjectReferenceItem (Visual Studio project).

    DependencyItemCollection

    Replaced by ReferenceItemCollection.

    DocumentAssembly

    Replaced by DocumentationSource.

    DocumentAssemblyCollection

    Replaced by DocumentationSourceCollection.

    SandcastleProject.Assemblies

    Renamed SandcastleProject.DocumentationSources.

    SandcastleProject.Dependencies

    Renamed SandcastleProject.References.

    BuildStep.CopyDependencies

    Deleted as it was no longer relevant.

    BuildStep.ValidatingAssemblies

    Renamed BuildStep.ValidatingDocumentationSources.

Where Did That Feature Go?

Several features and project options were removed and their functionality is now handled in a different manner. The following items will help you locate the old feature and determine how to do the same thing in the new version of the help file builder.

The Console Mode Builder (SandcastleBuilderConsole.exe)

With the use of an MSBuild project file format, SandcastleBuilderConsole.exe was rendered obsolete and has been removed. Use MSBuild, Team Build, or another such tool to build a help file project from the command line or in automated scripts.

Assemblies to Document

This has been replaced by a more generic term: Documentation Sources. These are added to the Documentation Sources project node in the Project Explorer window.

Project and Namespace Summaries

Edit these via the Project Properties window. The NamespaceSummaries and ProjectSummary properties can be found in the Comments category. Click the "..." button to the right of each property to open the expanded property editor.

The AdditionalContent Property

Additional content files are now handled as project file items. They should have a BuildAction value of Content. The folder structure of the items determines their location in the compiled help file and, for HTML and .topic files in the absence of a site map file, their order and layout in the table of contents. Items at the root level end up in the root level of the help file and projects in subfolders end up in like-named subfolders in the compiled help file. For control over how the files appear in the table of contents, add a site map file to the project and use it to arrange the additional content files.

The AdditionalContent.ContentSiteMap Property

Site map files are handled as project file items. They should have a BuildAction value of SiteMap. Multiple site map and content layout files (used for conceptual content) can be specified in a project. The SortOrder property on them determines in what order their content is merged into the table of contents.

The AdditionalContent.TopicFileTransform Property

Topic file transformations used for .topic files are handled as project file items. They should have a BuildAction value of TopicTransform. Note that only the first TopicTransform item found during a build will be used. All others will be ignored.

The ConceptualContent Property

All conceptual content file types are handled as project file items. See the following items for details.

The ConceptualContent.CodeSnippets Property

Code snippets files are handled as project file items. They should have a BuildAction value of CodeSnippets. Multiple code snippets files can exist in a project and all will be included in the build.

The ConceptualContent.Images Property

Conceptual content image files are handled as project file items. They should have a BuildAction value of Image. Image properties such as their ID and alternate text are managed via the project file item properties.

The ConceptualContent.Tokens Property

Tokens are now handled via token files which are project file items. They should have a BuildAction value of Tokens. Multiple token files can exist in a project and all will be included in the build.

The ConceptualContent.Topics Property

Conceptual topic files are handled as project file items. They now have an extension of .aml and should have a BuildAction value of None. Content layout files determine which topics are compiled into the help file and their order in the table of contents. They have a .content file extension and a BuildAction value of ContentLayout. As noted above, multiple site map and content layout files can be specified in a project. The SortOrder property on them determines in what order their content is merged into the table of contents.

  Note

Topics added via the content layout editor are automatically added to the project file. In addition, topics are now tracked by their ID number so you are free to rearrange the files in the project folders without having to update their location in the content layout file.

The Dependencies Property

Dependencies are now referred to as References. References can be GAC entries, assemblies, COM objects, or Visual Studio project files. They are added to the References project node in the Project Explorer window.

Editing Conceptual Content Layout and Related Topic Properties

Add a Content Layout file to the project. This lets you edit the layout of the conceptual topics and manage their properties much like the conceptual content editor in prior versions of the help file builder. See also: The ConceptualContent.Topics Property

Inserting Image, Token, and Code Snippet References Into Topics

Image, token, code snippet, and code entity references are now all handled by the Entity References window. Select the type of entity to insert in the window's dropdown. Then drag and drop or double click the item to insert it into the topic. A Refresh button is available to update the available items if you make changes to their related project files.

New Project From NDoc Project/Visual Studio Project

The option to create a new project from an NDoc project (or various other project types) can be found in the File | New Project from Other Format menu option. The option to create a project from a Visual Studio solution or project has been removed. Visual Studio 2005/2008 solution and project files are supported natively as documentation sources.

Locating Third-Party Custom Build Components, Plug-Ins, and User-Defined Templates

To be Vista-compliant by not making changes to the installation folder, all files such as third-party custom build components, custom plug-ins, build component data cache files, and user-defined template files should now be located in subfolders under the EWSoftware\Sandcastle Help File Builder folder in the Common Application Data or Local Application Data folder. See the Special Folder Locations topic for more information.

  Note

Performing a build using one of the cached data components will create the root local application data folder automatically. However, if you need to place files there before then, you will need to create the folder manually.

Bug Fixes

  • Fixed a couple of bugs in the Hierarchical TOC plug-in that caused the namespaces to be nested incorrectly.

  • Fixed the Code Block Component so that nested code blocks in conceptual content are imported correctly.

  • Fixed a bug in the Split TOC option that caused the TOC items to be excluded if it was set on the first content item.

  • Exceptions in the namespace generation step in partial builds are now ignored so that you can get into the Namespace Comments dialog to fix the issue.

  • Fixed a bug in the HTML extract tool that caused it to fail on nodes without an associated file.

Other Changes and New Features

  • Documented assemblies and reference (dependency) assemblies are no longer copied to the working folder for the build. Instead, they are resolved and parsed in place at their given location. This prevents issues with similarly named assemblies overwriting each other in the working folder.

  • XML comments files are still copied to the working folder as they may be modified. Duplicates are given a unique name if a file by the same name already exists in the working folder. This prevents the loss of comments due to XML comments files in different projects that use the same name.

  • The project used by the build process is a clone of the active project. As such, it can be modified without affecting the active project.

  • All tool/build engine warnings and errors are now reported with a code and in a format compatible with the Visual Studio Error List tool window. The warning and error codes are documented and provide information about what the error means along with possible solutions.

  • Just prior to building a Help 1 (CHM) file, warnings are issued if the working path, the HTMLHelpName property, or any filename contains ".h" or a comma. Paths or files containing ".h" or a comma can cause odd compiler crashes. If you see this warning and the help compiler fails, change the names of the paths or files listed in the warning(s).

  • Added an allowMissingSource option to the Code Block Component to allow missing source code files/regions to generate warnings rather than errors. It also gives a more descriptive error when it fails to find a required attribute.

  • Added All and None buttons to the Namespace Comments dialog to check or uncheck all namespaces at once.

  • The default presentation style in new projects has changed from Prototype to VS2005.

  • Implemented basic find and replace support in the topic editor window (Ctrl+F and Ctrl+H). Also added Goto Line (Ctrl+G) and expanded the number of elements that can be inserted from the tool bar.

  • All help windows are now opened non-modally.

  • Thanks to Golo Roden for the Python keywords and code colorizer rule definitions. Use the language ID python or py to colorize a code block as Python code.

  • In the code download, all help file builder solutions and projects are now in Visual Studio 2008 SP1 format.

  • The help file content has been converted to MAML and uses the VS2005 style.

See Also