Part 1: VS 2005 presentation changes in Sandcastle September Release

We have made several improvements to the VS 2005 presentation transforms for our September release of Sandcastle. Internally we call it the “hybrid” document design for Orcas. This new documentation presentation layer targets Visual Studio Developers who need to find information quickly and easily in our documentation that grows significantly with every Visual Studio/.NET Framework release. As new .NET Framework features are released, we must update the documentation design to accommodate the associated new concepts. As a result, we need improvements to the way that we navigate, filter, and display the documentation. These new features allow developers to locate, filter, and sort information in ways that are necessary to perform their job.

The following new features will be introduced in our Orcas documentation and users can take advantage of this by using the September Sandcastle release.

1. Programming language filter drop down: Syntax blocks, code examples, and member tables should be filterable by language. Users can pick one or more procedural code languages that will determine what content is shown on the member page.

2. Content Controlled by the Language Filter: The TOC titles will always use neutral language syntax

3. Frameworks Filter: The framework filter dropdown will appear on member list topics to enable framework filtering of the rows and icons displayed in the member list tables. It will be a separate dropdown in addition to the member filter dropdown. There will be a framework drop-down filter consisting of checkboxes.

4. Member List Filter Drop Down: The members filter will be its own drop down box consisting of check boxes that allow the displaying/hiding of protected and inherited members in the member list tables. Table rows for public members and explicit interface implementation members are always visible; but rows for protected members are shown/hidden based on the state of the “Include Protected Members” checkbox. Similarly, declared members are always visible, but the visibility of inherited members depends on the “Include Inherited Members” checkbox. Unlike the framework filter, this filter will not persist between type pages as the user navigates the documentation.

5. Dynamic language-specific text based on language filter: The language filter drop down determines how language-specific text is displayed in link text, topic titles, and language keywords. When a single language is checked in the language filter, the language-specific text is displayed using the format appropriate for the selected language. For example, when only C# is checked, link text is displayed using the C# convention for arrays (“String[]”) and generic types (“Collection<T>”); and when only VB is checked, link text is displayed using the VB convention for arrays (“String()”) and generic types (“Collection(Of T)”).

6. Filtering Persistence: A user can interact with the documentation by checking boxes in the filter drop down menus. In some cases the checkbox states should be persistent, meaning that the filter maintains the user’s choices as they navigate the documentation

7. Intelligent Filter Display: Language filter defaults should be configurable on a per-document project basis. For example, a C++ specific document set should default to C++. When a topic is configured for a single language, the language filter drop down is NOT displayed, but the topic’s content is filtered as if a checkbox for the single language is checked.

8. XAML syntax blocks/code samples: XAML is not a procedural language proper, however there are syntax blocks and code samples associated with it. The build process that generates XAML syntax will do so only for topics where it is appropriate (e.g. for APIs in assemblies that support XAML).

9. ASP.NET syntax blocks: In a similar manner to XAML syntax, ASP.NET syntax is always visible.

10. Updates to the non-scrolling region: Changes to the links in the non-scrolling region for the following pages

a. Member List Pages

b. Namespace Pages

c. Type Overview Pages

d. Member PagesLinks to Namespace on Member and Type Overview Pages

11.Cut and Paste Functionality: When users cut text from a topic, code must accommodate that the clipboard is populated with the currently selected language syntax.

12.Printing the Documentation: When a user is viewing the documentation, they are able to pront the topic and it’s subtopics from the TOC nodes.

13. Double Index Entries: Inject double entries into the Index for types and member pages to ensure that index entries displayed both C# and VB syntax for example

14.TOC Display Format: Topic titles as shown by the TOC can only be shown in one language syntax and is not changeable at runtime by the user

15. Representations of Generic Types and Methods

a. Generic TypeGeneric Method on Generic Type

b. Generic word and italics

c. Additional Examples

16. New 5 Star ‘Send Feedback” link in documentation

I will blog details about these features in the next part of this blog. Cheers.

Anand..