H2 Dynamic Help

Note: In this document underlined hyperlinks link to VS .NET & VSHIK documentation. To make these links work you will need to either add "http://kb.helpwaregroup.com" to your IE Trusted sites zone, or download this page to your local drive (I'm assuming you have these collections installed). Otherwise you can copy the shortcut into Internet Explorer's address bar and click Go.

19-May-2002 - Initial upload.

2-June-2002 - Added 7b.

20-June-2002 - Added DevLang section to 1.

18-Mar-2003 - Append new information to section 6 on .HxA files.

20-Jul-2005 - MS recommends that you now plug into MS.VSIPCC.* under VS 2005 v8.0 and greater.

And the MS.VSCC.* collection for VS 2002 v7.0 and VS 2003 v7.1.

Dynamic help has been played down in VS v8.0 IDE (general search has been improved).

Setting up an H2 help project to work with

Visual Studio .NET's Dynamic Help Window

by Michael Waltuch from ESRI

When you work with the Visual Studo .NET integrated development environment (IDE) one way you can provide help for a Windows application (ms-help://MS.VSCC/MS.MSDNVS/vbcon/html/vbtskprovidinghelpinapplication.htm) is through the use of the HelpProvider component. You can attach Help topics within a Help file (that is either of HTML or HTMLHelp 1.x or greater format) to specific controls on Windows Forms. At runtime you can display a help topic related to an element of your application's user interface by either clicking the element with the What's This cursor or setting focus to the element and then pressing F1. In addition you can use the HelpProvider component to provide Pop-up help (ms-help://MS.VSCC/MS.MSDNVS/vbcon/html/vbtskdisplayingpopuphelp.htm).

In addition to F1 help, Visual Studio .NET includes a new user assistance feature, the Dynamic Help Window. This window provides links to topics that are specific to the current area you are using or task you are trying to complete within the IDE. The IDE tracks the selections you make, the placement of the cursor, and the items with focus as you interact with what's on the screen. The Dynamic Help window then filters through the topics available in all collections that have been plugged into VS Help Collection (see Note#1) to display relevant information. So as you type or focus on different windows, the Dynamic Window updates the information available to you. Dynamic Help is particularly useful if your H2 help project documents an assembly with syntax, reference, samples, or how-to topics.

Make sure to read the current Visual Studio Help Integration Kit (VSHIK) whitepapers "Visual Studio .NET Help Integration" and "Integrating New Content with Dynamic Help". They discuss these features. The VSHIK documents are works in progress, but contain valuable information. If you don't have VSHIK, you can downloadit from MSDN. Here, we'll distill this information down to several essential steps. It should help you enable these features for your help system easily.

Attributes (see the VSHIK overview -- ms-help://MS.VSCC/ms.vshik/vshelpintegr/html/hxconAttributeOverview.htm) characterize the topics in your help project. Each attribute consists of a name-value pair used to describe various aspects of content within your Help file. Each attribute has a name and a set of possible values, and when used in conjunction with filters, makes it possible for users to selectively display the type of information they are interested in. In addition, each topic you want to point to in the Dynamic Help window must include some, if not all of the following attributes in the XML data island of the topic's HTML file. Two attributes must be inserted into a topic for it to be included in Dynamic Help: Locale andTopicType. Make sure each topic has one of:

• Locale
• The Locale attribute is required for Dynamic Help. As its values imply, it is based on the language of the help collection.
• Here is an example of a Locale attribute for an English language help collection:
  • <MSHelp:Attr Name="Locale" Value="kbEnglish"/>
  • TopicType
  • The TopicType attribute is required for Dynamic Help. It identifies the type of content the topic contains. Here is an example of a TopicType attribute for a topic that has syntax information. This could be a Property, Method, Event, Control, Object, Statement, Function, Keyword, Constant, Operator, Interface, Enumeration, Structure, or Macro topic:
  • <MSHelp:Attr Name="TopicType" Value="kbSyntax"/>
  • Users of your help system can choose which topic types to display in the Dynamic Help window property sheet. See Customizing Dynamic Help in the MSDN Visual Studio documentation for details.

In addition to these two required attributes, you can insert one of each of the following recommended MS-Help attributes per topic:

• DocSet
• The DocSet attribute identifies a documentation set. Here is an example of a DocSet attribute:
• <MSHelp:Attr Name="DocSet" Value="MyTitle1"/>
• DocSet is commonly seen in visible filters for collections in Edit Filters dialogs.
• DevLang
• The DevLang attribute identifies the language context for the topic. Be careful when using this attribute in situations in which your topic may be used in more than one language context; for example, if you want to make the topic available to both a Visual Basic solution and a C# solution, make certain to add the attributes forboth languages, for example:
• <MSHelp:Attr Name="DevLang" Value="CSharp"/> <MSHelp:Attr Name="DevLang" Value="VB"/>
• Your topic will be pushed only in the context for which it has a DevLang attribute. Note though, that if you don't add any DevLang attributes, a conflict will not be present and Dynamic Help will include the topic.
• TargetOS
• The TargetOS attribute identifies whether a topic deals with Windows, Windows CE, or both. MS recommends that all topics contain the TargetOS = Windows attribute, however this is not required. Topics that are applicable to the Windows CE platform should also contain TargetOS = WindowsCE.
• Here is an example of a TargetOS attribute:
• <MSHelp:Attr Name="TargetOS" Value="Windows"/>
• Additional Microsoft attributes
• You can add any number of additional Microsoft attributes. They are useful for the internal filtering of dynamic help so you don't wind up with an umanageable number of topics in the Dynamic Help window. The VSHIK help provides a complete list of attributes (ms-help://ms.vshik/vshelpintegr/html/hxgrfVisualStudioAttributes.htm) that can be used in conjunction with the Visual Studio .NET documentation. You can use the same set of attributes as The Visual Studio .NET Combined Help Collection. If you define custom attributes, use this reference topic to ensure that existing attribute names are not duplicated. When adding attributes from the table, always use the text from the Tag column rather than the text in the Display column.

• For the Values column, expand the Values section and use the text specified in its Tag column:

• So for example, use TopicType rather than Information Type and kbArticle instead of Article.

As you determine what attributes you'll add to your topics, add them and all potential values to an Attribute Definition (.HxA) file (ms-help://MS.VSCC/ms.vshik/mshlpwrk/html/hxgrfattributedefinitionfilehxa.htm)

For example you might characterize each topic in your collection by whether it's geared to Beginner, Intermediate, or Advanced readers by establishing a SkillLevel attribute. Note, adding these additional attributes does not have any impact on Dynamic Help. Here is an example of a custom attribute:

<MSHelp:Attr Name="SkillLevel" Value="Beginner"/>

You can add any number of keywords and keyword types to your topics or to the appropriate index file; however, only "F" keywords impact Dynamic Help. "F" keywords stored either in an .HxK file that has a Name property of "F" or that are inserted as an "F" Index Keyword in the XML data island of the topics themselves provide the link to the topic to be displayed.

The following is an example of the contents of an XML data island excerpted from a topic .htm file:

<xml> <MSHelp:Attr Name="DocSet" Value="MyTitle1"/> <MSHelp:Attr Name="Locale" Value="kbEnglish"/> <MSHelp:Attr Name="TargetOS" Value="Windows"/> <MSHelp:Attr Name="TopicType" Value="kbSyntax"/> <MSHelp:Attr Name="DevLang" Value="CSharp"/> <MSHelp:Attr Name="DevLang" Value="VB"/> <MSHelp:Attr Name="SkillLevel" Value="Beginner"/> <MSHelp:Keyword Index="A" Term="IAnimation properties"/> <MSHelp:Keyword Index="K" Term="Interval property"/> <MSHelp:Keyword Index="K" Term="IAnimation Interface, Interval property"/> <MSHelp:Keyword Index="F" Term="Interval"/> <MSHelp:Keyword Index="F" Term="IAnimation.Interval"/> <MSHelp:Keyword Index="F" Term="MyAssemblyNamespace.IAnimation.Interval"/> </xml>

The last three "F" Keywords in the sample XML data island above are examples of the kind of text that you've determined the help context provider (Visual Studio .NET's Code Editor window, for example) will emit if you select or position your cursor on some text. To determine what text the help context emits for your code or user interface elements, see the section below named "How to determine what the context emits". If the context emits any of the strings you specify as an "F" keyword, a link to any topic that contains that keyword will appear in the Dynamic Help window. By default, the topic's <TITLE> text will appear in the Dynamic Help window. If you prefer, you can specify an RLTitle attribute in the XML data island. This text will then display in the Dynamic Help window instead of the <TITLE> text:

<MSHelp:RLTitle Title="Link displayed in Dynamic Help window"/>

To view the context (attributes and keywords) that is pushed by the environment to the Dynamic Help window, set the following registry key:

HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\7.0\Dynamic Help HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\7.1\Dynamic Help -- for VS .NET 2003 HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\8.0\Dynamic Help -- for VS .NET 2005 etc

so that the ValueName Display Debug Output in Retail is set to YES.

After you restart Visual Studio .NET, the attributes and keywords output appear in the Dynamic Help window below the list of Help topics:

The text that appears after the [F1 Kwd] in Visual Basic projects or as in the illustration above, after the [F1 Kwd CS] in C# projects, is the text to add as the "F" keyword in your topics. So, for example the System.Diagnostics Namespace topic has the following keyword in its XML data island:

<MSHelp:Keyword Index="F" Term="System.Diagnostics"/>

Note that if an "F" Index Keyword is not found, Dynamic Help searches the "K" Index Keyword list for matches. As you can see in the illustration these keyword types are pushed as [Kwd].

To disable the debugging state, change the registry key back to NO.

This is a critical step. You must have an attribute definition file (.HxA) at the collection level (.HxC) and at the title level (.HxS) of your help project. The collection level HxA is a superset of all the title level .HxA files. If you want you can simply use a copy of the collection-level .HxA (inserting the appropriate DTD) at the title level; however, the .HxA at the title level can include attributes that are specific to the title. Here's a collection level .HxA, containing all schema for all titles:

<?xml version="1.0"?> <!DOCTYPE HelpAttributes> <HelpAttributes DTDVersion="1.0"> <AttName Id="1" Name="DocSet" Display="Yes" UIString="Acme Help Collection" AttType="Enum"> <AttVal Id="1_1" Name="MyTitle1" Display="Yes" UIString="First Title Help" /> <AttVal Id="1_2" Name="MyTitle2" Display="Yes" UIString="Second Title Help" /> <AttVal Id="1_3" Name="MyTitle3" Display="Yes" UIString="Third Title Help" /> </AttName> <AttName Id="2" Name="DevLang" Display="Yes" UIString="DevLang" AttType="Enum"> <AttVal Id="2_1" Name="CSharp" Display="Yes" UIString="CSharp" /> <AttVal Id="2_2" Name="VB" Display="Yes" UIString="Visual Basic" /> </AttName> <AttName Id="3" Name="Locale" Display="No" UIString="Locale" AttType="Enum"> <AttVal Id="3_1" Name="kbEnglish" Display="No" UIString="English" /> </AttName> <AttName Id="4" Name="TargetOS" Display="No" UIString="TargetOS" AttType="Enum"> <AttVal Id="4_1" Name="Windows" Display="No" UIString="Windows" /> </AttName> <AttName Id="5" Name="TopicType" Display="No" UIString="TopicType" AttType="Enum"> <AttVal Id="5_1" Name="kbArticle" Display="No" UIString="Article" /> <AttVal Id="5_2" Name="kbHowTo" Display="No" UIString="How To" /> <AttVal Id="5_3" Name="kbSyntax" Display="No" UIString="Syntax" /> </AttName> </HelpAttributes>

18-Mar-2003 .HxA Update

MS now recommend the following in regards to using .HxA attribute definition files.

• You do not need to compile a .HxA file at the title level into your project. Not including a title-level .HxA means that all topic attribute tags will be compiled into the final HxS help file. This is exactly what we want.
• If you do compile a .HxA into your project, you must make very sure that it contains all attributes used including the VS attributes used. Compiling in a .HxA is like creating an attribute filter for the compiler in that only attributes declared in the .HxA will be compiled into the final .HxS help file. MS advise against this method because it is too easy to make a mistake.
• The collection-level .HxA (the one you ship uncompiled that contains no DTD reference - as shown above), must define all the title attributes you want to expose at the collection level. No collection-level .HxA file would mean your attributes would not show at all.
• The collection-level .HxA does not need to declare the VS attributes you have used. Since these attributes are already declared in the VS collection you are going to plug into.

For further discussion on using attribute files please see H2 Attributes & Filters

Each of the illustrations of the Dynamic Help window above, showed the standard Link Groups into which MS.VSCC places topics: Help, Samples, Getting Started. You may want to highlight your topics or make them easier to find by creating one or more custom groups into which to place your topics. To create a custom link group for all or some of your topics, do the following:

1. Declare the LinkGroup in the Dynamic Help XML files.
2. Look in the VS .NET LinkGroup folder, for example:
3. %programfiles%\Microsoft Visual Studio .NET\Common7\IDE\HTML\XMLLinks\1033.
4. (%programfiles%\Microsoft Visual Studio .NET 2003\Common7\IDE\HTML\XMLLinks\1033 for VS .NET 2003)
5. There you’ll find a file called context.xml that contains the standard LinkGroup definitions. DO NOT edit this file. Instead, create your own file, for example "HelpWare.xml", that declares your own LinkGroup. At startup time, Dynamic Help will read all the .xml files in this folder and add them to the Dynamic Help window when the context warrants it. Here's an example of a custom LinkGroup definition file that includes one group:
6. <DynamicHelp xmlns="http://microsoft.com/vstudio/tbd/vsdh.xsd"> <LINKGROUP ID="HelpWareHelp" Title="HelpWare Help" Priority="300"> <GLYPH Expanded="vs:/ctxhelp_show.gif" Collapsed="vs:/ctxhelp_hide.gif"/> </LINKGROUP> </DynamicHelp>
7. You can add define as many LinkGroups as you want. Note that the ID must not contain spaces; however the Title may. It's the value of Title that will be visible in the Dynamic Help window.
9. If you want to position your custom LinkGroup higher up in the Dynamic Help window you must change the Priority setting in the .xml file that defines it. The setting is relative to the values of the other groups. The example above sets the Priority to "300". This positions the HelpWare Help group beneath most of the Visual Studio .NET LinkGroups. A higher value, for example, "1000", will position your group at or near the top of the list, depending on the context.
11. Add the LinkGroup attribute to the XML data island of any topics you want to display in it. Here is an example:
12. <MSHelp:Attr Name="LinkGroup" Value="HelpwareHelp"/>
    1. You may also want to add the title to display in the Dynamic Help window:
    2. <MSHelp:RLTitle Title="About This Button (HelpWare)"/>
13. Add the LinkGroup definition(s) to the attribute definition (.HxA) files
14. List the LinkGroups you've defined in the .HxA files at the title-level and collection-level, for example:
15. <AttName Id="8" Name="LinkGroup" Display="No" UIString="LinkGroup" AttType="Enum"> <AttVal Id="8_1" Name="HelpWareHelp" Display="No" UIString="HelpWareHelp" /> </AttName>
16. Note that the Name item in AttVal matches the ID in the LinkGroup definition file and the value of the attribute in the topic's XML data island.

Here's an example of a custom LinkGroup in the Dynamic Help window:

You can see a simple example of Dynamic Help if you download FAR's H2Reg utility. The H2 version of the H2Reg Help file includes two topics that can be displayed in the context of a Visual Studio .NET Windows Application project (either VB .NET or C#). To see the example, follow these steps:

1. Inspect the files that have been marked up for Dynamic Help:
   • The LinkGroup definition is in
   • %programfiles% \Microsoft Visual Studio .NET\Common7\IDE\HTML\XMLLinks\1033\helpware.xml
   • (%programfiles%\Microsoft Visual Studio .NET 2003\Common7\IDE\HTML\XMLLinks\1033\helpware.xml for VS .NET 2003)
   • Note: 1033 is for English language help. For non-English Windows you will see a different Language ID.
   • The attribute definitions are in Col_Master.HxA and h2reg.HxA.
   • Note: The h2reg.HxA file is no longer compiled into H2Reg.HxS help file (no longer used). See part 2 of section 6.
   • The topics that have "F" keywords are html\dynamichelp1.htm and html\dynamichelp2.htm.
   • Note: To view these files you will need to decompile the H2Reg.HxS help file.
2. To the form that Visual Studio .NET adds to your project automatically, add a Windows Forms Button control.
3. Display the Dynamic Help window.
4. Select either the form or the button — you'll see a custom LinkGroup and a link to a topic.
5. Similarly, in the Code Editor if you click or select either System.Windows.Forms.Form or System.Windows.Forms.Button a custom LinkGroup and a link to a relevant topic will appear in the Dynamic Help window.

In order for users of your help project to take advantage of Dynamic Help window assistance, you must, of course, plug your help collection into the Visual Studio .NET Help Collection (See Note#1 below). One way to do this is to use FAR's H2Reg utility. If you add a custom LinkGroup, your setup program must install the .xml file in which you specified the ID and Title into

%programfiles%\Microsoft Visual Studio .NET\Common7\IDE\HTML\XMLLinks\1033

See Note (8.a) above

Note#1: For MS VS 2005 (v8.0) and greater MS now recommend you plug into MS.VSIPCC instead of MS.VCSS. This keeps 3rd party collections grouped together and out of the way of core collection files (for stability).

• For VS 2002 (v7.0) - plug into namespace=MS.VSCC
• For VS 2003 (v7.1) - plug into namespace=MS.VSCC.2003
• For VS 2005 (v8.0) - plug into namespace=MS.VSIPCC.v80

Once you've plugged your help collection into the VS Help Collection, you can use Dynamic Help in concert with your assembly or application. As you move the cursor into a context, the Code Window, for example, you'll see how the Dynamic Help window changes. At this point you can either press F1 to get the first topic listed in the Help section, or you can click any one of the links in the window.