Sandcastle Version Information - Part 1/3

Introduction
Version information is one of the most advanced features supported by the Microsoft Developer Network (MSDN) help system.
The feature was introduced in September 2007 release of the Sandcastle with blogs detailing both the feature and how is it supported by the Sandcastle tools. The articles introducing the version information are listed below for reference:

Sandcastle September 2007 Release: VersionBuilder

Part 2: Version Builder

The information provided in those articles and tools were not sufficient to implement the full version information features in the MSDN Help System. In the Sandcastle Assist project, we implemented most of the missing parts but one main feature was still missing, and that is the target of this blog.

What is Version Information?
The MSDN help system for managed codes provides you with the ability to view the various API released in each version of the .NET and Silverlight frameworks.
We will illustrate the various parts of the feature so that we could discuss the complete implementations or how to realize them.
For better understanding of this feature, I will introduce three terms associated with it:

Versions
Versions are easy to recognize because these are directly marked by the release version numbers.
For the .NET framework; we have version labels; 1.0, 1.1 to 4.5 (in beta).
In the implementations, versions are defined by two parameters

1. Version ID
   This uniquely identify each release version, and for the MSDN there are a number of predefined versions identifiers provided in the Sandcastle content files.
2. Version Label
   This is the text representation of the version, and in most cases are numbers such as the 1.0, 1.1 etc. However, for the version information, this can be any text.

Examples of predefined version ids and labels provided by the Sandcastle in the reference_content.xml file are:

ID	Label
netfw40	4.0
netfw35_1	3.5 SP1
silverlight_mobile_v1	Windows Phone OS 7.0

NOTE: In that file, you will find these labelled as framework version ids.

The version parts are marked in the image shown below:

                   Fig 1: Version Information

Platforms
The platforms are confusing when working the Version Information because in Sandcastle there is another term, platform note, which relates mainly to the Windows platforms like Win95, WinXP, WinVista, Win7 etc.
For version information, platform is essentially versions collections (or categories). Similar to the version, platforms are defined by two parameters:

1. Platform ID
   This uniquely identify the platform (or versions collection), and there are predefined identifiers for the MSDN.
2. Platform Label
   This is the descriptive name of the platform.

Examples of predefined platform ids and labels provided by the Sandcastle in the reference_content.xml file are:

ID	Label
netfw	.NET Framework
netcfw	.NET Compact Framework
silverlight	Silverlight

NOTE: In that XML file, you will find this labelled as framework ids.

The platform parts are marked in the image below (again, this is extended to include the platform note to avoid confusion):

                Fig 2: Platform Information

The platforms are more visually expressed by icons that are directly attached to the API in the documentations as shown below:

                 Fig 3: Platform Icons

There are few point to take note of in the above image

• The main platform (.NET Framework in this case) is not represented by an icon.
• Most other platforms (XNA Framework and Portable Class Library in this case) have icons specifying which APIs are supported.
• Like the main platform, not all need an icon. Platform icon is not a requirement as in the case of .NET Framework Client Profile shown earlier.
• It is possible to provide platform icons, even if the version information are not provided, as shown by the X-like  XNA Framework icon. The version information and platform information can be used independent of each other.

Finally, the platform is used for filtering, which allows you to display the API for the platform you wish to see. This is available on the older online version of the MSDN help and is shown below:

                 Fig 4: Platform Filters

Frameworks

This may also be a little confusing when dealing with version information. By the version information, there are only two frameworks: .NET Framework and Silverlight Framework.
Whereas the Sandcastle allows you to mix version information easily from each version framework, to comply with the MSDN, you will have to create your documentation to work with the defined frameworks.
The confusion may be due to the fact that Silverlight documentation was later added to the MSDN and Sandcastle.
The image in Fig 3 is for a MemoryStream class defined in the .NET Framework. The same image for the Silverlight Framework, also taken from the MSDN, is shown below:

                 Fig 5: MemoryStream under Silverlight Version Framework

As you might have observed by now, I prefer the term Version Framework to avoid confusion.
Note that the .NET Version Framework is labelled by what may be called the version framework identifiers in the MSDN (see the image below). However, this is defined by the main platform in your documentation.

                         Fig 6: Framework Filter

In short, the Help 1 and Help 2 provide the platform filters in a framework, the Web Helps and Help 3 provide main platform or framework filters.

Conclusion
The version information is an advanced Sandcastle feature and working with it can be confusing. This article documents my understanding of the feature, and how I approach it. There is no complete formal documentation of this feature and I claim the responsibility for any error in this article.
Next, we will consider the implementation; first an updated version information and then the platform information.