New Features in Microsoft Help Viewer 2.0 Beta

UPDATE: This post describes features introduced in Microsoft Help Viewer 2.0 Beta.  Introducing Microsoft Help Viewer 2.0 provides an overview of the final, released product.

Visual Studio 11 Beta is out and, with it, the release of Microsoft Help Viewer 2.0 Beta. Get started by downloading the bits at:

The Help Viewer team’s been busy since I blogged about new features in the Developer Preview. In this post, I’ll cover new features we’ve added in the Beta release:

  • TOC Filter
  • Keyword Index: “Begins With” vs. “Contains”
  • Docking Windows
  • Color Themes
  • Search Filter UI
  • Improved Performance

Setup and Configuration

If you’re performing a clean install of Visual Studio Professional, Premium or Ultimate, you’ll be offered the chance to download local Help content at Visual Studio first run or when you first set your Help Preference to “Use Local Help.”

clip_image001

Installing content during first run is a convenience, not a necessity. You can download and install local Help content from within the Help Viewer at any time.

Online Help is the Visual Studio default as it was in Visual Studio 2010. If you’re doing a clean install of Visual Studio and you want to use the Help Viewer, you’ll need to set your Help Preference to “Use Local Help” From the Visual Studio Help menu.

clip_image002

Table of Contents (TOC) Filter

The TOC Filter displays all topics with titles that contain an input filter string. But instead of displaying the results in a flat list, topics are presented in a sparse tree with their relative relationships intact. This view of the TOC can help you discover topics that are distributed across the TOC and clusters of content that represent in-depth treatment. The filtered view of the TOC can also help developers better understand how our reference content is organized.

For example, if I filter on ‘system.xml’, I can see topics in the .NET framework documentation where I expect to see them. But there’s a cluster of documentation in the Visual Studio debugging content that discusses troubleshooting exceptions. It would have been time-consuming to build this mental model of related content through Search queries alone.

tocFilter

To keep the list compact and manageable, we collapse empty TOC levels with an ellipsis (…). Placing your cursor over an ellipsis reveals the path to a topic or topic group.

If it takes a long time to construct the filter view (as it does in the above example), we display a banner message: “This filter may take a long time. You can change the filter or use search instead.” You can cancel the filter, switch to the search pane or just wait for the filter action to complete.

Keyword Index: “Begins With” vs. “Contains”

The keyword index now functions in either of two modes: “Begins With” or “Contains.” In “Begins With” mode, the keyword index displays items that begin with a given input string. This is the traditional behavior of the index control. When the keyword index is in “Contains” mode, it depicts items that contain the input string. To toggle between modes, click on the filter icon or press Ctrl + K.

Let’s look at how the same ‘sql’ filter string offers a different result list in these two modes:

Begins With Contains
clip_image005 clip_image006

Docking Windows

Docking windows were present in the earlier Developer Preview but they were still a work-in-progress. By supporting this capability, Help Viewer provides greater consistency with the Visual Studio IDE and it addresses a set of scenarios that might otherwise have required additional Viewer Options. (If you’re unfamiliar with Visual Studio docking windows, you may want to learn How To: Arrange and Dock Windows.)

While the possible configurations are nearly endless, some scenarios in which this feature can be helpful:

Example 1: Navigation panel docked on the right side of the content pane. This common configuration was a Viewer Option in Help Viewer 1.1.

example1

Example 2: Navigation panel docked above the content pane. This configuration minimizes horizontal real estate which can be helpful when developing on a single display, for example, a laptop.

example2

Example 3: Search pane docked in content window. This configuration is nice if you want to have more area to display search results.

example3

You can also display topics side-by-side or drag topics outside of the main Help Viewer window. As you’d expect, your docking customizations persist across Help Viewer sessions.

Finally, if you want to restore the Help Viewer to “factory settings,” open the Viewer Options dialog (Ctrl + O) and “Reset Window Layout” by selecting the ‘Reset’ button.

Color Themes

Visual Studio 11 Beta introduces a new visual design and user interface. As a companion app to the IDE, Help Viewer 2.0 Beta provides the same visual design and color themes.

You select your Visual Studio color theme in the Options window of the IDE.

themeOptions

The next time you launch the Help Viewer, it will honor your Visual Studio color theme. Currently there are two theme options: Light and Dark.

Help Viewer Light Theme Help Viewer Dark Theme
hvlight hvdark

NOTE: We’re currently receiving a flood of strong feedback on the user interface changes and it’s likely we’ll make revisions in response to that feedback. Whatever changes are made in the IDE will be reflected in the Help Viewer. If you’d like to weigh in on the new user interface, the best place to be heard is on our Visual Studio UserVoice site or on Visual Studio Connect.

Search Filter UI

We now have UI support for the search filters I described in my post on the Developer Preview. When entering a string into the search box, you’ll see a list of your last three searches followed by filter options. The filter options enable you to discover the available filters and add them to your search query. For example, clicking on ‘title:’ automatically appends it to the search string.

clip_image019

Improved Performance

Performance is a key focus of Visual Studio 11 and that extends to the Help Viewer. Help Viewer 2.0 is faster than Help Viewer 1.1 in all of our performance benchmark tests.

Our biggest gains come in moving from an HTTP API to a COM API (with a managed wrapper for .NET programmers).  We no longer pay the HTTP network cost before retrieving data. (And you no longer have the Help Library Agent sitting in your taskbar.) Because the Help API is a core component of Windows 8, we had encouragement from our friends in the Windows team to optimize both our performance and memory footprint.

Other improvements include:

  • F1 Help – We revised viewer code to reduce UI blocking tasks and to optimize for fast startup by delay- or background-loading of nonessential data with the goal of delivering as fast an F1 response as possible. If you haven’t tried F1 help in a while, I encourage you to give it a look.
  • Search Index – Index functions have been parallelized using the .NET Parallel Constructs which speed index functions on multi-core machines. We’ve made a number of non-specific tweaks to fine tune performance including denormalizing data to reduce the number of index lookups per query. Finally, several caches are created at index creation time to improve search times.
  • Rendering – The content rendering system has been rebuilt from the ground up to be more extensible, flexible, and secure. By moving the rendering and branding into C# code (reducing the need for JavaScript and complex XSLT transforms) we have significantly reduced rendering time.
  • Table of Contents (TOC) – We modified the TOC API code to reduce the number of calls necessary to determine if a TOC topic has children or not. We also cache the results of TOC filter operation to increase the speed of repeatedly used filters. Note that the filter cache is reset on any ‘Manage Content’ operation.
  • Content Download – We optimized our use of BITS to improved content download times. In addition, content merge time have been reduced by over 50%.

…and much, much more

We’ve made numerous fit and finish improvements throughout the Help Viewer, for example, in the area of keyboard support. I’ve already blogged about some of the other significant improvements so if you’re interested in the following features, please read my earlier post on new features in the Developer Preview:

  • Simpler setup and configuration
  • Integrated content management
  • Search filters
  • New help runtime (no more Help Library Agent!)

Finally, we’ve added improved support for content management in enterprise and behind-the-firewall scenarios. I’ll save the details of those features for a future blog post.

To provide feedback on these new features in Help Viewer 2.0 Beta:

  1. Leave a comment at the bottom of this blog post
  2. Send us an email at hlpfdbk@microsoft.com, or
  3. Share your thoughts on the Developer Documentation and Help System Forum
Posted in Microsoft Help Viewer, Visual Studio 2012 | Tagged , | Comments closed

An MSDN Library for the Windows Dev Center

This week at Microsoft’s BUILD conference, we unveiled the new Windows Dev Center with four focused sub-centers: Windows Store apps, Internet Explorer, Desktop apps and Hardware:

Windows Dev Center

Windows Store apps Windows Store apps Internet Explorer Internet Explorer Desktop apps Desktop apps Hardware Hardware

As you click through the options in the Center navigation menus, you’ll see familiar MSDN pages (Samples, Downloads, Community, etc.) but with a twist. They’ve been integrated into the Windows Centers so that their branding and navigation is consistent with that of the product.

Library content (under the ‘Learn’ tab instead of the ‘Library’ tab) is also tightly integrated with the Windows Dev Centers and represents a significant departure from the standard MSDN Library.

Why did we create a new, integrated library experience?

The Windows 8 Learn tab provides a specialized version of the MSDN Library devoted to Windows 8 development. It delivers a targeted subset of the content in MSDN and a library search feature that’s constrained to Windows 8 Development topics.

We created this experience to address feedback we’ve received from developers about the challenges they face when using the online MSDN Library.

“It’s great that the MSDN Library has everything, but it’s too hard to find exactly what I’m looking for. It’s like looking for a needle in a haystack.”

There are over 3 million topics in the English language MSDN Library. And, mathematically speaking, about 3 million of those topics are irrelevant to you at any given moment. The Windows 8 Library lets you quickly move a large number of irrelevant topics out of your way so you have a better view of the content that you really need. The Windows Dev Center, at the time of BUILD, reduces the number of topics to about 15,000! Search queries performed inside the Windows 8 libraries will be constrained to those 15,000 topics.

Let’s look at an example of how integrated libraries move unneeded content out of your way. If you’re on the Windows Store apps Learn tab and you search for a Win32 API like “CreateWindow” (used by Desktop apps but not by Windows Store apps), you’ll get a “No Results Found” notification:

image

It’s just not there cluttering your life. However, if you truly need to find out more about the CreateWindow API, it’s trivial to remove the Windows Store apps refinement and automatically re-issue your query against the entire MSDN Library.

image

“The table of contents looks too much like a Microsoft org chart. As a result, the information I need is often scattered across the MSDN Library.”

Integrated libraries let us pull relevant content that’s scattered around the MSDN Library into a single experience. For example, we can take patterns & practices phone development guidance and consolidate it with Windows Phone Development content.

“It’s hard to tell one part of the MSDN Library from another and to know which section I’m in, especially when I drop in from a web search.”

Each of the Windows Centers has a unique and easily identifiable URL. Before you’ve even entered a library, you can use the URL listed in search engine results to help determine which result is most relevant. For example:

Library URL Examples

Once you’re in the library you’ll note that product-specific branding helps you quickly determine where you’ve landed.

Scoped Library Design Principles

Ready for a look under the hood? The integrated Windows 8 Library experience is based on a new capability of MTPS called scoped libraries. A scoped library is a subset of the online MSDN Library with four main components: a reduced set of topics, a search mechanism constrained to those topics, an easily recognized identity (e.g. Windows 8 Development) and a unique, readily identifiable URL path. We’re piloting the Windows scoped libraries and an Azure scoped library to validate that they meet developer needs before adopting them elsewhere in MSDN and TechNet.

I’ve already discussed the benefits of scoped libraries; now let’s review some of the assumptions and principles that governed their design.

1) Every topic in a scoped library is also in the main library

Every topic in a scoped library is also present in the MSDN library. If a developer needs to work with multiple platforms or technologies at the same time, all of that information is available in the master MSDN Library without having to hop around between scoped libraries. The MSDN Library is still your one-stop shop for developer content.

2) As a rule, topics should not appear in more than one scoped library

Since each scoped library topic also appears in the master library, it follows that each scoped library topic can be found at two different URLs: the scoped URL and the master URL. For example, these are the URLs for the “Make great Windows Store apps” topic:

Scoped URL: http://msdn.microsoft.com/en-us/library/windows/apps/hh464920.aspx
Master URL:  http://msdn.microsoft.com/en-us/library/hh464920.aspx

Which of these topics is the preferred version? In this case the scoped library topic will be the canonical or preferred version and its URL will receive priority in search engine results.

image

However, if the same topic is repeated in multiple scoped libraries, we start creating confusion for the user: Why are there so many versions? Are there any differences between versions? If so, which version is the definitive version? Consequently, if a topic must appear in more than one scoped library, the topic in the master MSDN Library will be the canonical URL.

Finally, we provide a way for Microsoft content authors to override the default canonical URL when necessary.

3) Fewer libraries is better

More isn’t necessarily better when it comes to scoped libraries. We don’t want to replace the “needle in the haystack” problem with the “infinite haystacks” problem. Current thinking is that we’ll limit them to our core development platforms (Win8, Azure, Phone, SharePoint, etc.) As we introduce more scoped libraries, we’ll also need to make it possible to discover and navigate between them.

4) Scoped libraries don’t live forever

We expect a typical scoped library to have a lifetime of about three to five years. When a scoped library disappears, the MTPS platform will automatically redirect topic requests to the equivalent topic in the master MSDN Library. Long after attention has moved on to newer platforms, you can still get to the content you need.

Posted in MSDN Library | Tagged , , | Comments closed

Announcing Microsoft Help Viewer 2.0 Developer Preview

UPDATE: This post describes features introduced in the Microsoft Help Viewer 2.0 Developer Preview. Additional features were delivered in Help Viewer 2.0 Beta and in Help Viewer 2.0 RTM.

The Microsoft Help Viewer 2.0 Developer Preview is now available as part of the Visual Studio 11 Developer Preview. Get the bits at:

Here’s a quick tour of some of the key changes we’ve made from release 1.1 to 2.0 of the Help Viewer.

Setup and Configuration

The first thing you’ll notice is that we’ve removed the “Install Documentation” button from the Visual Studio Setup Finish Page. Too many developers (and Microsoft executives) were missing the “big blue button” during Visual Studio setup. Instead, you’ll be offered the chance to download local help content at Visual Studio first run or when you first set your Help Preference to “Use Local Help.” (Online Help is still the Visual Studio default.)

In addition, you can now set your Help Preference directly from the Visual Studio Help menu.

newmenu

Content Management

The capabilities of the Help Library Manager have been incorporated into the newly added Help Viewer “Manage” tab. The standalone Help Library Manager is gone. One of the key new features is the ability to relocate your local content store.

arlc

If a download is interrupted (for any reason) and restarted by the user at a later time, the Help Viewer won’t re-download any content that has already been transferred. This can save you a lot of time and is especially useful on poor Internet connections. An estimated download size is now displayed before you kick off a transfer to help you better manage bandwidth costs.

Content is downloaded in the background using the Background Intelligent Transfer Service (BITS). You can continue to use the Help Viewer, close the Help Viewer application or even reboot your system once a download has been initiated. When the transfer is complete, the help system automatically updates all help system artifacts (table of contents, search index, keyword index, etc.) without requiring a restart of the Help Viewer.

One other change you’ll see in the viewer is that we’ve added support for dockable windows (something I’ll discuss more in a future post).

Search Filters

The search box now provides search filters. Two filters are supported in the CTP – Title and Code. If you enter “title:foo” in the search box, your search results will be limited to topics that contain the string “foo” in the topic title. If you enter “code:bar”, you’ll get search results limited to topics with the string “bar” in a code example. You can use multiple filters per query and they can be used in combination, for example: “topic:datetime code:datetime code:tryparseexact”.

filter-example

The Code filter also has a set of sub-filters that enable language-specific searches:

Long Name Short Name
csharp c#
cpp c++
fsharp f#
javascript <none>
visualbasic vb

If you want to look for topics that contain the string “foo” in a C# code example, you can search on “code:c#:foo” or “code:csharp:foo”. For example:

subfilter-example

New Help Runtime

I’ve saved the best for last. If you look closely, you’ll see that we no longer install the Help Library Agent! The new help runtime has a COM API and the same lifecycle as the Help Viewer. It won’t clutter up your taskbar and it provides improved performance and memory footprint.

But there’s more. Windows 8 incorporates the Visual Studio 11 help runtime API. The Windows 8 “Windows Help and Support” viewer uses the same local help API for content retrieval and the same file and content formats as Visual Studio 11. Because Visual Studio has a need to support down-level operating systems, the help API ships as two different binaries. In Windows 8 it ships as Windows.Help.Runtime.dll and in Visual Studio 11 it ships as Microsoft.VisualStudio.Help.Runtime.dll. The same source code is used to build both DLLs.

In Closing

We spent a lot of time during this release incorporating the runtime into Windows so we didn’t get all of our Help Viewer features done in time for the Developer Preview. In particular, the work we’ve done to incorporate additional filtering features into the Help Viewer won’t be ready until our Beta release.

Please let us know what you think about the Help Viewer 2.0 Developer Preview. As always, you can:

  1. Leave a comment at the bottom of this blog post
  2. Send us an email at hlpfdbk@microsoft.com
  3. Share your thoughts on the Developer Documentation and Help System Forum

(Continue reading about features in the Microsoft Help Viewer 2.0 Beta release.)

Posted in Microsoft Help Viewer, Visual Studio 2012 | Tagged , , | Comments closed

Export then print multiple Library topics (Beta)

We recently introduced a Beta version of the “Print/Export Multiple Topics” feature in the TechNet Lightweight Library. The Print/Export feature enables readers to:

  • Create and organize a custom collection of Library topics
  • Export the collection to a PDF or HTML document
  • Print the collection

How do I get started?

There are several prerequisites for using this feature:

  • You must be running a browser that implements HTML5 DOM Storage: Internet Explorer 8, Firefox 3.5, Safari 4 or Chrome 5 (or higher versions of these browsers)
  • You must be in the Lightweight view of the TechNet Library. Click on the ‘Lightweight’ link in the upper right-hand corner of the Library to change views.
  • You need a Microsoft account

To enable the feature, click the printer icon in the upper right-hand corner of the page and select ‘Print Multiple Topics’ from the drop-down. If you’re running IE8 or higher and you don’t see this option, verify that you’re in Browser Mode IE8 (or higher) and Document Mode IE8 (or higher). You can change these settings under Tools (Alt + X), F12 developer tools.

PMT

Read the “Print/Export Multiple Topics – Help” page that appears for instructions on how to use this feature. When you’re ready, click on the ‘Start’ button to begin building a collection. You’ve successfully enabled the feature when the Print Multiple Topics toolbar appears at the top of the page:

PMT Toolbar

How do I create and organize my collection?

The collection is a user-defined subset of Library topics. The collection persists between browser sessions so you can start a collection, shut down the browser, and return to the collection at a later time. The feature currently supports one and only one collection. To create a new collection, you must delete the current collection and start over. At this time the collection cannot be saved or shared.

You add either single topics or entire branches of topics to the collection in one of three ways:

  1. While viewing a topic, click on the ‘Add This Topic’ link in the toolbar.
  2. Right-click on any topic hyperlink and select ‘Add This Topic’ from the context menu.
  3. Right-click on a node in the Table of Contents and select ‘Add This Set of Topics’ from the context menu.
    addtopicset

At this time, we limit collections to a maximum of 100 topics. As I’ve noted in the past, the Library is large and we don’t want to be responsible for sending three million topics to your printer. The Beta evaluation will help us determine if a 100-topic maximum is sufficient.

When you’re done adding topics to the collection, click on the ‘Collection’ link in the toolbar to open the Manage Collection page.

manage

This page enables you to organize your collection and provides access to the export capability. Topics can be organized in two ways: 1) you can change the order of topics and branches using the drag-and-drop feature of the Manage Collection page, and 2) you can organize groups of topics into chapters.

You can also assign custom names to the collection and its chapters. In the picture above, the collection is named “My Collection” and it has two chapters (PowerShell and SQL Server) that organize the topics. Title and Chapter pages will be added to your collection during the export process.

Finally, your collection persists on the computer on which it was created and is accessible until deleted or until the browsing history is cleared (i.e. cookies, cache, etc.)

How do I export the collection?

Before you can print your collection, you must export it. To export the collection, generate a document in your chosen output format and then download the document to your local machine. Two output formats are supported: HTML and PDF.

  1. Click on the ‘Collection’ link in the toolbar to open the Manage Collection page.
  2. Review your selections to ensure you’re ready to export.
  3. Select an output format. Choose either ‘XHTML’ (HTML) or ‘PDF’ from the dropdown menu.
  4. Click on the ‘Generate’ button. If you haven’t already logged in, you will be prompted for your Live ID and then you’ll need to click on the ‘Generate’ button again.
    When you see the “Generating” page your file has been submitted to an Azure service for processing. This page provides status on your Export job. You can wait for your job to complete or continue browsing and return to this page at a later time.
  5. When your document is ready, the page name changes to “Finished.” Click on the ‘Download Your Document’ link to download and open the file or right-click on the download link to save the file directly to your hard drive.

generating

How do I print the collection?

Again, you must export the collection before you can print it. HTML files can be printed from your browser, once opened. PDF files can be printed from Adobe Reader.

What are the Advanced Options?

A set of Advanced Options is available on the “Manage Collection” page. These options enable you to add additional Library content to your exported file. Click on the expand icon to the left of the Advanced Options section to reveal these options:

options

Can I view this content on a Kindle?

Yes. Instructions for transferring PDF files to your Kindle are available on Amazon.com. (Click to view larger image.)

TechNet Kindle

When will this feature be available on MSDN?

We decided to start the Beta program for this feature on TechNet and we’ll expand it to MSDN at a later (to be determined) date. Why? The ability to export Library topics has been a highly requested TechNet feature since IT Pros don’t have the equivalent of the Visual Studio local Help Viewer.

How do I provide feedback on this feature?

We’ll be posting a survey on this feature in the near future but, in the meantime, you can provide feedback by clicking on the Feedback link at the bottom of a Library page or you can leave a comment on this blog.

Posted in TechNet Library | Tagged , , , | Comments closed

View XHTML source for local VS Help topics

So you’ve decided to create some local content and you want to use the Visual Studio branding package to simplify your life. It would be helpful to look at Visual Studio source content so you can learn by example. What’s the easiest way to examine Visual Studio local Help topics in raw XHTML?

Let me give you a hint: it’s not right-clicking on a topic in the Help Viewer and “viewing source.” Nor is it cracking open the MSHC files in your local Help Library store. (Although that’s the best approach if you lack access to the Internet.)

As you’d expect, Visual Studio local Help content is just a repackaged version of online MSDN content. Local content is created by running online content through an XSLT transform and then packaging it for distribution. Local help is delivered and updated via the MTPS Service API, a public REST API that exposes MSDN and TechNet Library content. You can use the Service API to find and view raw XHTML files.

Step 1: Determine the ID of the topic you wish to inspect

Locate an online MSDN topic with formatting or behavior you’d like to adopt. The ID of the topic is simply the last segment of the URL and takes one of two forms, a Short ID or an Alias.

Step 2: Use the MTPS Service API to view the topic XHTML

Now that you have an ID, you can use the Service API to view the topic in its original, raw XHTML.

  1. Append the ID to the Service API Content URL and open in a browser. The full URL takes the following form (where TopicID can be an Alias or a Short ID):

    http://services.mtps.microsoft.com/ServiceAPI/content/TopicID

  2. When you provide a valid ID to the content service, you’ll see a list of Locale/Version combinations. Click on the link for your preferred Locale and Version. (See the MSDN URL Cheat Sheet for more information.)

    To view the EN-US version of the XmlReader Class for .NET Framework Version 4: http://services.mtps.microsoft.com/ServiceAPI/content/b8a5e1s5/en-us;vs.100

  3. The page that appears provides a variety of information about your selected topic. Click on the Format:Mtps.Offline link under the Primary Documents heading:

    rawxhtmlsm

  4. Right-click and “View source” to inspect the raw XHTML used by the local help system!

Disclaimer

The information in this post is for educational purposes. Both the MTPS Service API and the Help Viewer branding package are intended for use by the Microsoft Help Viewer and are subject to change.

Learn More

MTPS Service API provides a set of web services for exposing the content in MTPS. The URL for Service API is: http://services.mtps.microsoft.com/ServiceAPI

The Service API is documented at: http://services.mtps.microsoft.com/ServiceAPI/docs/

Posted in Microsoft Help Viewer, Visual Studio 2010 | Tagged , , | Comments closed

Add links and code examples to Help topics you create

In my last post, I explained how to add a simple, text-only topic to your local Help Library. I also described how metadata connects content into the help system. Now let’s look at what we can do to make our topic a little more interesting. (Skip ahead to the hands-on tutorial if you’re not interested in the details.)

Links

There are three common link types in Help Library content: internal, external and image.

Internal links reference other topics within the local Help Library. They specify link targets by their topic ID alone—an approach we call “identity linking.” Since help topics are referenced without knowledge of their absolute or relative pathnames, topic linking does not depend on the structure of Library content. Why use this approach? The help system separates content, structure, presentation and behavior to enable extensibility and portability to future content formats.

It is the help runtime that maps topic IDs to their corresponding XHTML pages. The help runtime is called via the ms-xhelp API and we reference a specific help system topic by passing its ID into that API. The format of an ms-xhelp URL is:

ms-xhelp:///?Id=Microsoft.Help.ID

Here is an example of how the API is used inside a topic (the class=”mtps-internal-link” markup supports CSS formatting):

<a class="mtps-internal-link" href="ms-xhelp:///?Id=b3382805-aa6b-4e6f-a346-73d20f74d0cd">Links, Code Examples and Language-specific Text</a>

External links reference web pages outside of the Help Library and use standard HTTP URLs. Here’s an example of how external links are used inside a topic (the class=”mtps-external-link” markup supports link formatting):

<a class="mtps-external-link" href="http://msdn.microsoft.com/en-us/library/default.aspx">MSDN Library</a>

Image links are used to embed images in topics. Embedded images generally reside in the same package (MSHC file) that contains the topic. An example image link:

<img class="mtps-img-src" src="image.png" />

Branding Package Controls

The appearance and behavior of Help content is defined by a branding package, basically a collection of CSS files, JavaScript, images and other resource files. The help system allows each catalog to specify its own branding package. For this post, we’ll limit ourselves to controls that are provided by the default branding package that ships with the Help Viewer. Using this branding package enables us to easily create topics that look and behave like Visual Studio help content.

The default Help Viewer branding package supports three commonly used controls we’ll look at today: CollapsibleArea, CodeSnippet and LanguageSpecificText.

Collapsible Areas

In Visual Studio Help content, collapsible areas group sections within a topic. They serve two functions: 1) provide formatting for the title of the section, and 2) enable the user to collapse entire sections when reading a topic. This is useful for extremely long topics or for FAQ pages.

Collapsible areas were only partially implemented in Help Viewer 1.x. They provide proper title formatting but they don’t provide a collapse feature. However, marking up your content with the CollapsibleArea tag ensures it can take advantage of this capability in future releases.

The CollapsibleArea control contains the area to be collapsed and specifies the title of the section. For example:

<CollapsibleArea Expanded="1" Title="Content Linking" xmlns="http://msdn2.microsoft.com/mtps">

… section content …

</CollapsibleArea>

Note that, if Expanded="0", the area starts collapsed. Expanded="1" is the default.

Code Examples (CodeSnippets)

Many Visual Studio help topics contain code examples and syntax documentation. The help system CodeSnippet control displays formatted code examples in the user’s preferred development language. (Note that Help system “CodeSnippets” are not the same as Visual Studio “Code Snippets.”)

The help system automatically groups adjacent code snippets into a “snippet group” that enables readers to easily switch between examples in different development languages. A single CodeSnippet is expressed as follows:

<!-- Snippet for the C# language -->
<CodeSnippet EnableCopyCode="true" Language="CSharp" ContainsMarkup="false" DisplayLanguage="C#" xmlns="http://msdn2.microsoft.com/mtps">
using System;

// A "hello, world" program in C#
namespace HelloWorld {
  class Hello {
    static void Main() {
      System.Console.WriteLine("hello, world");
    }
  }
}
</CodeSnippet>

The CodeSnippet control uses two separate tags to support source code formatting. The Language tag specifies the development language used for code colorization. The DisplayLanguage tag specifies the text to be displayed on the snippet tab. Supported tag values include:

Language DisplayLanguage
CSharp C#
VisualBasic Visual Basic
ManagedCPlusPlus Visual C++
FSharp F#
JScript JScript
xaml XAML

Language-specific Text

It is common to use language-specific syntax in help documentation. Because syntax varies from language to language, the help system provides the ability to display text as a function of the reader’s chosen development language. This feature eliminates the need to author separate, redundant topics for each language.

The LanguageSpecificText control displays dynamic text based on the development language selected by the reader using the CodeSnippet control.

For example, the following language-specific text example is used frequently in Visual Studio content to modify namespace delimiters:

<LanguageSpecificText devLangcs="." devLangvb="." devLangcpp="::" devLangnu="." xmlns="http://msdn2.microsoft.com/mtps">.</LanguageSpecificText>

And here is the list of supported language tags:

Language Tag
C# devLangcs
VB devLangvb
C++ devLangcpp
Other devLangnu

Linking and Code Example Tutorial

Now it’s time to apply what you’ve learned. In this section, you’ll add links and use controls from the Help Viewer branding package to add code examples to your custom topic. This tutorial takes about 5 minutes and makes the following assumptions:

  • Visual Studio 2010 (RTM or SP1) is installed on your machine.
  • You have administrator privileges on your machine.
  • You have successfully used the local Help Viewer to read EN-US help content.

When you’ve completed the exercise, you can remove the tutorial content without side effects to your help system.

Step 1: Create a Topic

To begin, create a folder for your help content and then create a topic in that folder. For the purposes of this tutorial, you’ll create a folder named “HelpTutorial2” in your main Documents folder.

  1. Use Windows Explorer to create the folder or from a command prompt:
    mkdir %userprofile%\Documents\HelpTutorial2
  2. Launch Notepad.
  3. Copy the following XHTML and paste it into Notepad:
    (Tip: If you lose carriage returns when pasting into Notepad, consider copying this XHTML from within Chrome or Firefox. The code examples in this topic will not display correctly if lines don’t break in the correct locations.)

    <?xml version="1.0" encoding="UTF-8"?>
    <html xmlns="http://www.w3.org/1999/xhtml">
    <head>
      <title>Links, Code Examples and Language-specific Text</title>
      <!-- Specify the topic content key: ID, locale and version -->
      <meta name="Microsoft.Help.Id" content="ecab3be4-257f-4649-864b-761cfd9510c2" />
      <meta name="Microsoft.Help.Locale" content="en-us" />
      <meta name="Microsoft.Help.TopicLocale" content="en-us" />
      <meta name="Microsoft.Help.TopicVersion" content="100" />
      <!-- Use the default branding package to render the topic -->
      <meta name="Microsoft.Help.SelfBranded" content="false" />
      <!-- Place the topic in the TOC under the root node -->
      <meta name="Microsoft.Help.TocParent" content="-1" />
      <meta name="Microsoft.Help.TocOrder" content="0" />
      <!-- Enable topic access from the keyword index -->
      <meta name="Microsoft.Help.Keywords" content="help content links" />
      <meta name="Microsoft.Help.Keywords" content="Code Example (CodeSnippet)" />
      <meta name="Microsoft.Help.Keywords" content="LanguageSpecificText" />
      <!-- Enable topic access via F1 help -->
      <meta name="Microsoft.Help.F1" content="CodeSnippet" />
      <meta name="Microsoft.Help.F1" content="LanguageSpecificText" />
      <!-- Provide a description for use in the search results list -->
      <meta name="Description" content="This text provides an overview of this topic and is displayed in the search results list." />
    </head>
    <body>
      <h1 class="title">Links, Code Examples and Language-specific Text</h1>
      <div id="mainSection">
        <CollapsibleArea Expanded="1" Title="Content Linking" xmlns="http://msdn2.microsoft.com/mtps">
          <p>There are three common types of links: internal, external and image.</p>
          <table class="members" xmlns="http://www.w3.org/1999/xhtml">
            <tr>
              <th>Type</th>
              <th>Example</th>
              <th>Description</th>
            </tr>
            <tr>
              <td>Internal Link</td>
              <td><a class="mtps-internal-link" href="ms-xhelp:///?Id=1838dc17-b428-4db2-938e-10fa07f63e81">Help System Feature Overview</a></td>
              <td>Internal link to a topic in local Help system documentation</td>
            </tr>
            <tr>
              <td>External Link</td>
              <td><a class="mtps-external-link" href="http://msdn.microsoft.com/en-us/library/default.aspx">MSDN Library</a></td>
              <td>External link to the online MSDN Library</td>
            </tr>
            <tr>
              <td>Image Link</td>
              <td><img class="mtps-img-src" src="image.png" /></td>
              <td>Example of an embedded image</td>
            </tr>
          </table>
        </CollapsibleArea>
    
        <CollapsibleArea Expanded="1" Title="Language-specific Text" xmlns="http://msdn2.microsoft.com/mtps">
          <p>This text adjusts to match the coding language selected in the SnippetGroup (below).</p>
          <ul>
            <li>Current code language: <strong>
              <LanguageSpecificText devLangcs="C#" devLangvb="VB" devLangcpp="C++" devLangnu="other" xmlns="http://msdn2.microsoft.com/mtps">other</LanguageSpecificText></strong></li>
            <li>Namespace delimiter (example): <strong>XmlReader
              <LanguageSpecificText devLangcs="." devLangvb="." devLangcpp="::" devLangnu="." xmlns="http://msdn2.microsoft.com/mtps">.</LanguageSpecificText>Read Method</strong></li>
          </ul>
        </CollapsibleArea>
    
        <CollapsibleArea Expanded="1" Title="Examples" xmlns="http://msdn2.microsoft.com/mtps"><a id="exampleToggle" xmlns="http://www.w3.org/1999/xhtml"><!----></a>
          <p>Note that all of the tabs in the SnippetGroup are populated with a code example.</p>
          <!-- Declare the SnippetGroup container -->
          <div id="snippetGroup" xmlns="http://www.w3.org/1999/xhtml">
            <!-- Snippet for the VB language -->
            <!-- Language is the code colorization language -->
            <!-- DisplayLanguage is the tab title language -->
            <CodeSnippet EnableCopyCode="true" Language="VisualBasic" ContainsMarkup="false" DisplayLanguage="Visual Basic" xmlns="http://msdn2.microsoft.com/mtps">
    Imports System
    
    ' A "hello, world" program in Visual Basic
    Module Hello
      Sub Main()
          MsgBox("hello, world")
      End Sub
    End Module
            </CodeSnippet>
            <!-- Snippet for the C# language -->
            <CodeSnippet EnableCopyCode="true" Language="CSharp" ContainsMarkup="false" DisplayLanguage="C#" xmlns="http://msdn2.microsoft.com/mtps">
    using System;
    
    // A "hello, world" program in C#
    namespace HelloWorld {
      class Hello {
        static void Main() {
          System.Console.WriteLine("hello, world");
        }
      }
    }
            </CodeSnippet>
            <CodeSnippet EnableCopyCode="true" Language="ManagedCPlusPlus" ContainsMarkup="false" DisplayLanguage="Visual C++" xmlns="http://msdn2.microsoft.com/mtps">
    // A "hello, world" program in C++
    main( ) {
      printf("hello, world");
    }
            </CodeSnippet>
            <CodeSnippet EnableCopyCode="true" Language="FSharp" ContainsMarkup="false" DisplayLanguage="F#" xmlns="http://msdn2.microsoft.com/mtps">
    // A "hello, world" program in F#
    #light  
    open System  
    printfn "hello, world"
            </CodeSnippet>
            <CodeSnippet EnableCopyCode="true" Language="JScript" ContainsMarkup="false" DisplayLanguage="JScript" xmlns="http://msdn2.microsoft.com/mtps">
    // A "hello, world" program in JScript
    print("hello world");
            </CodeSnippet>
          </div>
    
          <p>Singleton with tab and language colorization:</p>
          <CodeSnippet EnableCopyCode="true" Language="html" ContainsMarkup="false" DisplayLanguage="XHTML" xmlns="http://msdn2.microsoft.com/mtps">
    &lt;html xmlns="http://www.w3.org/1999/xhtml"&gt;
      &lt;head /&gt;
      &lt;body&gt;
        &lt;p&gt;hello, world&lt;/p&gt;
      &lt;/body&gt;
    &lt;/html&gt;
          </CodeSnippet>
    
          <p>Singleton with no tab, no colorization:</p>
          <CodeSnippet EnableCopyCode="true" Language="other" DisplayLanguage="" ContainsMarkup="false" xmlns="http://msdn2.microsoft.com/mtps">
    HRESULT SetDeviceEnumPreference(
      [in]  DWORD dwEnumPref
    );
          </CodeSnippet>
        </CollapsibleArea>
      </div>
    </body>
    </html>
    
  4. Save the file as: %userprofile%\Documents\HelpTutorial2\topic2.html
  5. Close Notepad.
  6. Right click on the MSDN image below and “Save picture as…” image.png in the HelpTutorial2 folder.

Step 2: Create a Package

Next, place your topic in a package.

  1. In Windows Explorer, right click on the topic2.html file you created in Step 1 and send it to a Compressed (zipped) folder named mycontent2.zip.
  2. Drag image.png into the mycontent2.zip folder.
  3. Rename the mycontent2.zip folder to mycontent2.mshc. (Click ‘Yes’ on the Rename dialog that pops up.)

Step 3: Create a Book

The last step in preparing your content is placing your package in a “book”. As you’ll recall from my previous post, a book is a collection of packages and is defined in an asset manifest file named HelpContentSetup.msha.

  1. Launch Notepad.
  2. Copy the following XHTML content and paste it into Notepad:
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head />
      <body class="vendor-book">
        <div class="details">
          <span class="vendor">My Company</span>
          <span class="locale">en-us</span>
          <span class="product">My Custom Content</span>
          <span class="name">More Custom Topics</span>
        </div>    
        <div class="package-list">
          <div class="package">
            <span class="name">mycontent2</span>
            <span class="deployed">true</span>
            <a class="current-link" href="mycontent2.mshc">mycontent2.mshc</a>
          </div>
        </div>
      </body>
    </html>
    
  3. Save the file as:
    %userprofile%\Documents\HelpTutorial2\HelpContentSetup.msha
    (Tip: Set the “Save as type” dropdown list in Notepad to “All Files (*.*)” )
  4. Close Notepad.

Step 4: Install the Book

Launch the Help Library Manager in administrative mode and install the book from disk. If you’re unsure how to do this, follow the install instructions from my previous post.

Step 5: Explore Your Content

Select “View Help” from the Visual Studio Help menu. Note that your topic appears in the Table of Contents as a child of the root node:

topic2toc

If you select this topic you’ll see the following page:

Help Topic with Code Examples

To Learn More

This tutorial covers the basics of the Visual Studio Help Viewer branding package. To learn more about designing content for the Microsoft Help Viewer, check out these resources:

Posted in Microsoft Help Viewer, Visual Studio 2010 | Tagged , | Comments closed
%d bloggers like this: