Integrating with Visual Studio

NDoc3

Visual Studio Integration

Each Html Help 2 topic includes an XML data island, that is used by the help system for creating indices, linking topics, looking up keywords, filtering topics and a number of other features. A typical XML data island looks like:

<xml>

<MSHelp:TOCTitle Title="Object Class"/>

<MSHelp:RLTitle Title="Object Class"/>

<MSHelp:Keyword Index="K" Term="Object class, about Object class"/>

<MSHelp:Keyword Index="A" Term="frlrfSystemObjectClassTopic"/>

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

<MSHelp:Attr Name="DocSet" Value="NETFramework"/>

<MSHelp:Attr Name="TopicType" Value="kbSyntax"/>

<MSHelp:Attr Name="DevLang" Value="CSharp"/>

<MSHelp:Attr Name="DevLang" Value="VB"/>

<MSHelp:Attr Name="DevLang" Value="C++"/>

<MSHelp:Attr Name="DevLang" Value="JScript"/>

<MSHelp:Attr Name="DevLang" Value="VJ#"/>

<MSHelp:Attr Name="Technology" Value="WFC"/>

<MSHelp:Attr Name="Technology" Value="ManagedC"/>

<MSHelp:Attr Name="TechnologyVers" Value="kbWFC"/>

<MSHelp:Attr Name="TechnologyVers" Value="kbManagedC"/>

<MSHelp:Attr Name="Locale" Value="kbEnglish"/>

<MSHelp:Attr Name="DocSet" Value="NETCompactFramework"/>

<MSHelp:Attr Name="TechnologyVers" Value="kbProfile2NETCF"/>

<MSHelp:Attr Name="HelpPriority" Value="2"/>

</xml>

When NDoc generates an Html Help 2 topic, it creates an XML data island similar. This allows the help title to be integrated into Visual Studio.NET in such a way that your topics will show up in the help index, the help contents, the search pane, the dynamic help pane and even in context sensitive help from the code editor. This level of integration makes it very easy for consumers of your code to get the information they need right from the development environment and is one of the most valuable features of Html Help 2.

Requirements

Even though NDoc generates the necessary XML data island for each topic, the nature of the Html Help 2 system requires some additional information in order to integrate generated help with VS.NET.

The help title must be part of a collection.

Html Help 2 defines two levels of containment for help sets: collections and titles. A title is a single set of related Html Help topics, compiled into an HxS file. A collection is one or more related sets of help title. (Confusing the issue: help titles can also be treated as collections, but not vice-a-versa). Each help collection must be assigned a unique namespace.

Only help collections can be integrated into the VS.NET help system.
The collection must be registered on each machine.

The Html Help 2 system maintains a registry (not to be confused with the windows registry) of all of the help topics currently installed on the machine. This registry is used when traversing links, doing searches, displaying indices etc. It is an essential part of the implementation of Html Help 2. For this reason the help collection needs to be registered when it is deployed, otherwise it will not be accessible from VS.NET.
The registered help collection must be "plugged-in" to the VS.NET help namespace.

Any registered help collection can be referenced from any other registered help collection. This allows one collection to include the title in another collection, even though those titles are not directly part of the parent collection. It is via this "plug-in" mechanism that third party help collections can be added to the VS.NET help system.

The namespace for the VS.NET 2003 help collection is: MS.VSCC.2003

Confused yet?

Html Help 2 is fairly complex technology. Further information can be found in the VSHIK documentation. The website helpware.net also has a lot of useful information and tutorials on Html Help 2. HelpWare also has a shareware tool by the name of FAR that will prove invaluable for exploring the capabilities of the Html Help 2 system.

The VS.NET documenter has a number of settings meant to simplify this entire process.

First, make sure that GenerateCollectionFiles is set to true. This will generate the necessary Html Help 2 collection meta data files that will allow you to plug into VS.NET.
Second, supply a value for CollectionNamespace. Don't use spaces or any URI special characters. It is also a good idea to make an effort to assure that this namespace will be globally unique. The same rules you use to generate unique managed namespaces also work well here.
Third, make sure you supply the correct value for PlugInNamespace. This makes sure that when you deploy your help files with h2reg.exe, they will be plugged into VS.NET. (The default value of ms.vscc allows h2reg to decide at install time whether VS.NET 2002 or 2003 should be used.)

Filters

Each help topic's XML data island can have one or more DocSet values. The DocSet is what VS.NET uses when it filters the help index and search panes. DocSets are defined at the collection level, and then individual topics can be included in a DocSet via its XML data island.

MSDN defines a number of set filters as follows:

Windows Client SDK,     	Query: "DocSet"="WCSDK"
NET Framework,            	Query: ("DocSet"="NETFramework" OR "DocSet" = "NETFrameworkExtender") OR (("DocSet"="C#" OR "DocSet"="Visual Basic" OR  "DocSet"="Visual C++" OR "DocSet"="VBA" OR "DocSet"="VJ#" OR "DocSet"="Visual Studio") AND "Technology"="ManagedCode")
Visual Studio Macros,    	Query: "DocSet" = "VSM" OR "DocSet" = "NETFramework"
Visual Basic,              	Query: "DocSet" = "Visual Basic" OR "DocSet" = "NETFramework" OR "DocSet" = "NETFrameworkExtender" OR "DocSet" = "DHTML" OR "DocSet" = "XML" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "kbVBp700")
Visual C++,                	Query: "DevLang" = "C" OR "DevLang" = "C++" OR "Product" = "VC" OR "DocSet" = "PSDK" OR "DocSet" = "NETFramework" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "kbVC700")
Platform SDK,              	Query: "DocSet" = "PSDK"
(no filter),               	Query: 
Enterprise Servers,        	Query: "DocSet" = "NETEnterpriseServers" OR "DocSet" = "SQL Server"
Internet Development,      	Query: "DocSet" = "DHTML" OR "DocSet" = "XML" OR "DevLang" = "DHTML" OR "DevLang" = "HTML" OR "DevLang" = "VBScript" OR "DevLang" = "JScript" OR "DevLang" = "ASP" OR "Technology" = "kbSOAP" OR "Technology" = "ASPNET" OR "Technology" = "HPS"
Visual Studio,             	Query: "DocSet" = "Visual Studio" OR "DocSet" = "Visual Studio SDK" OR "DocSet" = "CrystalReports" OR "DocSet" = "Visual Source Safe" OR "DocSet" =  "VSAnalyzer" OR "DocSet" = "PSDK" OR "DocSet" = "NETFramework" OR "DocSet" = "NETFrameworkExtender" OR "DocSet" = "NETEnterpriseServers" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "kbVS700")
Visual C#,                 	Query: "DocSet" = "C#" OR "DocSet" = "NETFramework" OR "DocSet" = "NETFrameworkExtender" OR "DocSet" = "DHTML" OR "DocSet" = "XML" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "C#")
Samples,                   	Query: "TopicType"="kbSampleProd"
Visual FoxPro,             	Query: "DocSet" = "Visual FoxPro" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "kbVFP700")
Knowledge Base,            	Query: "DocSet" = "kbKB"
Visual J#,                 	Query: "DocSet" = "VJ#" OR "DocSet" = "NETFramework" OR "DocSet" = "NETFrameworkExtender" OR "DocSet" = "DHTML" OR "DocSet" = "XML" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "VJ#")
.NET Compact Framework,    	Query: "DocSet"="Smart Devices" OR "DocSet"="NetCompactFramework"

Adding your collection to any of the above sets is as easy as supplying a comma separated list via the DocSetList property. An entry will be made in each topic's data island for each item in this list. When you deploy your help, your topics will show up when the user is filtering by sets which you have defined.

NDoc will however create and register a single DocSet filter corresponding to the value of HtmlHelpName, and each topic will be included in that set. Defining additional custom filters is possible, but is outside of the scope of NDoc. To do so you will need to delve more deeply into the deployment and registration process as described in VSHIK.