The configuration options consist of a framework label and a version number for the current project and a list of other projects that will be built and have their API information merged with the current project. Note that these will only produce a partial build, enough to generate reflection information. XML comments files for the documented assemblies are optional. In the configuration, each additional project is assigned a framework label and a version number to uniquely identify it. The framework labels can be identical to the current project or they can be unique or matched between the other projects. The framework label controls how the version information is grouped. Both are free-form text so you can enter any value to identify the framework and version. The order of the projects in the configuration is not relevant. Version information is sorted by version number in descending order within framework label at the time the help file is actually built. For example:

• Current project label: Windows Forms Controls, Version: 2.1
• Other Project 1 label: Windows Forms Controls, Version: 1.3.5
• Other Project 2 label: Compact Framework Controls, Version: 1.3.2
• Other Project 3 label: Compact Framework Controls, Version: 2.3.1

Depending on the presentation style selected, this would produce a Version Information section in each member topic similar to the following:

If the framework label is common to all versions being documented, you can leave it blank. However, this may affect the display of the version information in some styles such as Prototype which expect to have a framework label value.

If checked, the Remove old APIs no longer in latest versions option will cause the version builder tool to remove all API members that no longer appear in the latest version within each set of assemblies with a common framework label value. If left unchecked (the default), all members from all versions will be included in the help file.

Since the plug-in uses help file builder projects to generate the other version information, you are free to mix projects built against different .NET framework versions, ones that use different API filters specific to that version, ones that use a different set of dependencies, or that contain other project settings specific to the related version. As noted, the additional projects only go through a partial build, enough to generate reflection information. As such, the following project properties are ignored in the other projects:

• Build category: CleanIntermediates, ComponentConfigurations, HelpFileFormat
• Help File category: All properties
• HTML Help 1 category: All properties
• MS Help 2 category: All properties
• Paths category: HtmlHelp1xCompilerPath, HtmlHelp2xCompilerPath
• Show Missing Tags category: All properties

XML comments files from the other versions are included in the current project's build so that members not appearing in all projects are still documented correctly. Where there are XML comments common to multiple versions, those from the current project will always take precedence. As noted above, XML comments files are optional. If omitted, no comments will be associated with the given assembly.

In certain presentation styles such as VS2005, the list pages contain a framework filter in the page header. Hovering the mouse over the filter link displays a popup containing a list of the framework labels. The intended use is to allow you to filter the list to only show members related to the checked frameworks. However, as of the January 2008 release, the Sandcastle transformations use hard-coded .NET framework values rather than the ones specified in the configuration file and the filter will not have any effect. This has been reported and hopefully it will be fixed in a later release of Sandcastle.