Tutorial: How to Integrate Help Documentation into Visual Studio

Article
11/16/2012

This tutorial teaches how to use Innovasys HelpStudio Lite to create a Help file and integrate it into Visual Studio. The tutorial is divided into the following sections:

Create a Help project
Add Help topics
Create index keywords, context keywords, and a table of contents
Integrate Help files into Visual Studio

To complete this tutorial, you must have Visual Studio 2008 Help and Innovasys HelpStudio Lite installed on the computer. For more information, see the HelpStudio Lite documentation. To learn about other tools available for Help authoring and integration, see Help Tools.

Pre-Requisites

You must have the FirstToolWin project from VSPackage Tutorial 2: How to Create a Tool Window to complete this tutorial.

Create a Help Project

To create a project by using HelpStudio Lite

In Windows Explorer, open the folder that contains the FirstToolWin project and then create a new folder named Help.
Start HelpStudio Lite. On the File menu, click New.
In the New Project dialog box, click 2005 Style, and then click Browse.
In the Save As dialog box, browse to \FirstToolWin\Help\, and then name the file HelpProject and click Save.
The NewProject dialog box should now show the path and file name as follows.

Click OK.

The HelpStudio Lite Project Explorer should now have a new project.

On the left side is the Project Explorer tool window, which includes the Topics folder. By default, the Topics folder contains several categories where you can put your Help topics. You can also create new categories. This tutorial just uses the existing categories.

Add Help Topics

To add Help topics to the project

Create a new topic by right-clicking the Reference category in the Project Explorer, and then clicking New Topic.

The Topic Properties dialog box opens.
In the Name box, type Load File Button. The Name property will also be used as the file name in the project files.

Press TAB. The Title box contains the same name. By default, the value of the Title property will appear in the topic when it is created.

You can specify a different title to appear in the table of contents. However, for this tutorial, just leave the Contents Title box blank.

The Category box already contains the category that you used to create the topic (in this case, Reference). If you want to create this topic in a different category, you can click Category and then choose a different category. However, for this tutorial, just leave Reference as the category.

Click OK.

The Help File Item opens in the upper-right corner of the window.

The title text, Load File Button, now appears at the top of the topic. Below that is where you can type the text for the Help topic.

Notice that there are four tabs at the bottom of the pane, as follows:
- Full Page Edit. The WYSIWYG editor.
- HTML. The HTML source code for the file.
- Preview. A static preview of the final document.
- Tasks. A list of items that must be completed.
Above the pane in the main part of the window is a toolbar that can help you edit the topic.

The list box on the left contains a list of standard HTML styles that you can apply to the text in the topic.
Type text for the topic. For example, type the following line.

The Load File button loads the Media Player together with the file name that is specified in the Enter Filename combo box.

On the File menu, click Save.
In the Project Explorer, create another new topic by right-clicking the Reference category, and then clicking New Topic.
In the Topic Properties dialog box, type Enter Filename Combo Box in the Name box. Click OK.
When the topic appears in the editor, type text below the title. For example, type the following line.

Use the Enter Filename box to type the file name that you want to load in the Media Player.
On the File menu, click Save.
At the bottom of the window is the See Also Links tool window.

This tool window shows the topics that will be listed in a "See Also" section at the bottom of the Help topic.

Make sure that you have the "Enter Filename Combo Box" topic open. In the Project Explorer, drag the other topic, "Load File Button," to the See Also Links tool window.

Notice that a See Also header now appears in the topic, together with a link to the "Load File Button" topic.

On the File menu, click Save.
Switch to the other topic by opening the Window menu and clicking Load File Button.

In the Project Explorer, drag the "Enter Filename Combo Box" topic to the See Also Links tool window.

On the File menu, click Save.
Now, add a link from the text in the "Load File Button" topic to the "Enter Filename Combo Box" topic.

Make sure that the "Load File Button" topic is open. In the topic text, select the words "Enter Filename Combo Box".

On the Insert menu, click Hyperlink. In the dialog box that opens, make sure that Link to a Topic, Image or Other File is selected.

The area in the middle of the dialog box contains a list of the items in the project. Expand the Reference folder, click Enter Filename Combo Box, and then click OK.

The Insert Hyperlink dialog box closes and you return to the editor.

On the File menu, click Save.

Create Index Keywords, Context Keywords, and a Table of Contents

Every index entry in a Help file points to a topic. However, you can create several entries that point to the same topic. For each index entry that you want to point to a topic, add a keyword to the topic.

The Index Keywords tool window is at the bottom of the main window, and can be accessed by clicking a tab under the See Also Links tool window.

Now, add index keywords to each topic. Notice that one keyword, "Filename," is common to both topics.

To create index keywords

Open the "Load File Button" topic.
Click the Index Keywords tab to display the Index Keywords tool window.
Click near the cursor at the top of the Index Keywords tool window. Type Load, and then press ENTER.
Click the top area again, type Filename, and then press ENTER.
On the File menu, click Save.

Doing this creates two index topics for the "Load File Button" topic.
Now create a keyword for the "Enter Filename Combo Box" topic.

Open the "Enter Filename Combo Box" topic.
In the Index Keywords tool window, type Filename, and then press ENTER.

Context keywords are used to associate topics in a Help file with features in Visual Studio. You insert context keywords just like you insert index keywords, except that you must start each keyword by using an exclamation point.

To create context keywords

Open the "Load File Button" topic.
In the Index Keywords tool window, type !LoadButton, and then press ENTER.
Switch to the "Enter Filename Combo Box" topic.
In the Index Keywords tool window, type !EnterFilename, and then press ENTER.
On the File menu, click Save.

For users to access your Help file, it must include a table of contents, even if it only contains one entry. The Table of Contents tool window can be displayed by clicking its tab, which is under the Project Explorer window.

To create a table of contents

Open the Table of Contents tool window.
To add the first item, click Add Sibling Node.
In the Node Properties dialog box, type Reference next to Caption.
Under Node Type, click Just a Title (no link), and then click OK. Doing this creates a folder in the table of contents that is not associated with a topic. This topic will contain the topics that you created earlier.
In the Table of Contents tool window, select the Reference folder, and then click the Add Child Node icon.
In the Node Properties dialog box, under Node Type, click Link to a Topic.
In the Select a Topic dialog box, expand Reference, click Load File Button, and then click OK.
In the Node Properties dialog box, click OK.

Doing this adds the "Load File Button" topic to the table of contents.

We just added the first topic to the Table of Contents; now we'll add the other.

Now, add the "Enter Filename Combo Box" topic.

In the Table of Contents window, select t:[Load File Button], which you just added, and then click Add Sibling Node.

Doing this adds a node at the same level as the first topic.
In the Node Properties dialog box, under Node Type, click Link to a Topic.
In the Select a Topic dialog box, expand Reference, click Enter Filename Combo Box, and then click OK.
In the Node Properties dialog box, click OK.
On the File menu, click Save.

To build and test the Help file

Before you build the Help file, check the spelling.

On the Tools menu, click Project Spell Check.

In the Project Spell Check window, leave everything selected, and then click Start.

If the spelling checker finds a misspelled word, it will appear in the bottom part of the Project Spell Check window. Double-click it to open a dialog box that lets you ignore the misspelling, add it, select from spelling suggestions, or type a new word.
Now you can build the Help file.

On the Tools menu, click Build.
In the Build Options dialog box, select Save the project before building and Default (Microsoft Help 2.x), and then click Build.

If a message appears and asks whether to create the specified output directory, click Yes.
After the build is finished, you should see a message that includes a link in the editor area. Click the link to open the built Help file

The Help file opens in its own Microsoft Document Explorer window, as shown in the following picture.

On the left, notice the Table of Contents that you created. It contains a folder named Reference, which you can expand to see the two topics. The first topic is selected and displayed.

Click the Index tab. Notice the index entries, which correspond to the index keywords that you added earlier. Click the Filename entry, which is the one that is associated with two topics, and notice that the Index Results window appears and displays links to both topics.

Integrate Help Files into Visual Studio

HelpStudio Lite and the Visual Studio 2008 SDK both provide tools to integrate Help content into Visual Studio. The Visual Studio SDK includes a wizard for this purpose. For more information, see Help Integration Wizard Overview.

This tutorial demonstrates how to use the InnovaHxReg tool, which is included in HelpStudio Lite, to manage the integration.

In order to integrate your Help file together with Visual Studio, you must add a namespace and ID to your Help system.

To integrate Help files into Visual Studio

Close all instances of Microsoft Document Explorer.
In HelpStudio Lite, on the Tools menu, click Build.
In the Build Options dialog box, click Edit.

The Build Profile dialog box opens.
For both Build Profile Name and Project Title, type MediaPlayerHelpProject, and then click OK.
In the Build Options dialog box, click Build to rebuild your project.
At a command prompt, add the \Common\ folder of your HelpStudio Lite installation to the path, for example, as follows:

set PATH = %PATH%;"%ProgramFiles%\Innovasys\Common"
Navigate to the build directory of the project.

cd "Documents\Visual Studio 2008\Projects\FirstToolWin\FirstToolWin\Help\Build"
Register the Help collection with the global cache by using the InnovaHxReg tool.

InnovaHxReg /R /N /Namespace:MediaPlayerHelpProject /Description:"Media Player Tool Window Help" /Collection:COL_HelpProject.HxC
Register the Help file.

InnovaHxReg /R /T /namespace:MediaPlayerHelpProject /id:MediaPlayerHelpProject /langid:1033 /helpfile:HelpProject.hxs
Finally, integrate the Help into the Visual Studio 2008 documentation.

InnovaHxReg /R /P /productnamespace:MS.VSIPCC.v90 /producthxt:_DEFAULT /namespace:MediaPlayerHelpProject /hxt:_DEFAULT
Now, add code to the FirstToolWin extension so that Help is displayed when the user presses F1 in the extension.

Start Visual Studio and open the FirstToolWin project. For more information, seeVSPackage Tutorial 2: How to Create a Tool Window.

To enable context-sensitive Help, first obtain a context object.
Open MyToolWindow.cs
At the top of the class, just after the control declaration, declare a IVsUserContext object and an ITrackSelection object, as follows.
```
private IVsUserContext selectionContext;
private ITrackSelection trackSelection;
```

Next, add the following code to the MyToolWindow class. Put the code before the final two braces in the file so that it is an individual method. This code creates the selectionContext that is used to select the Help topic to display.

public override void OnToolWindowCreated()
{
    base.OnToolWindowCreated();

    var handler = new ToolWindowEvents((FirstToolWinPackage)this.Package);
    ((IVsWindowFrame)this.Frame).SetProperty
        ((int)__VSFPROPID.VSFPROPID_ViewHelper, handler);

    var package = (FirstToolWinPackage)this.Package;
    object userContextObject;
    ((IVsWindowFrame)this.Frame).
        GetProperty((int)__VSFPROPID.VSFPROPID_UserContext,
        out userContextObject);
    var userContext = (IVsUserContext)userContextObject;

    var monitorUserContext = (IVsMonitorUserContext)this.
        GetService(typeof(SVsMonitorUserContext));
    monitorUserContext.CreateEmptyContext(out selectionContext);

    uint cookie;
    userContext.AddSubcontext(selectionContext,
        (int)VSUSERCONTEXTPRIORITY.VSUC_Priority_ToolWndSel,
        out cookie);

    trackSelection = GetService(typeof(STrackSelection)) as ITrackSelection;
}

Add the following code to the end of the ComboListHandler function, before the closing brace.

int res;
selectionContext.RemoveAttribute(null, null);
res = selectionContext.AddAttribute(
    VSUSERCONTEXTATTRIBUTEUSAGE.VSUC_Usage_LookupF1,
    "keyword",
    "EnterFilename");
selectionContext.SetDirty(1);
if (null != trackSelection)
{
    trackSelection.OnSelectChange(null);
}

This code will open the Help topic when the user selects the combo box in the extension and the Dynamic Help window is open.

Save the file.

Trying It Out

To test the Help integration

Start the project without debugging.
In the experimental build, on the View menu, point to Other Windows, and then click Window Media Player.
On the Help menu, click Dynamic Help.
Click the combo box in the Media Player tool window.

You should see the Help item displayed in the Dynamic Help window.