Guide to MSDN Collection Integration

If you are like me sometimes the lack of documentation can be quite frustrating. Its not enough that you have to spend hundreds of hours building your code and polishing your application - now you have to search endlessly trying to find the answer to a question that should already be documented...somewhere...but is not! That is what I ran into when trying to integrate HTML Help with the MSDN Collection. I finally figured this one out, but not after endless hours of research. Hopefully my frustration and research will benefit those of you who are looking for help with this topic.

Getting Started

MSDN stores information about the HTML help files that it will use in what is known as a "collection". A collection is an XML formatted file that contains information about each help file to be used with MSDN. There are two files that the collection uses, msdnxxx.col and hhcolreg.dat. The msdnxxx.col file is the actual collection. This contains a list of all of the html help titles that are to be used with the collection. The name of this file typically begins with "msdn" and ends in ".col". The October 2000 collection file name is MSDN030.COL. The hhcolreg.dat file is the collection's registry. This file stores specific details about each collection title such as the location of the HTML help and index files and version number. The first thing we will need to do is locate both of these files.

Locating the msdnxxx.col file

We will need to look in the system registry to find the location of the msdnxxx.col file, you can use regedit for this. . If you have the MSDN Library installed you will find the following key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\HTML Help Collections\Developer Collections

This is where Microsoft stores the location of its help collections. Under this key you will notice an entry for Language. The value for this key specifies which language the collection is using. A typical value would be 0x0409 for English, but may vary depending on your language settings. The next key you will find is Preferred. This value tells us which collection is currently the preferred collection for use by MSDN. A typical value for this would be 0x039a24110 but may also vary. Under this key we will find an entry for Filename. This value is the actual location on your hard drive where the msdnxxx.col file is located.

Locating the hhcolreg.dat file

The next file we need to be concerned with is hhcolreg.dat. Like the collection file, this also is a XML formatted file, and contains specific information about your integrated help files. In older releases of the MSDN Library, this file was located in the Windows\Help directory. In later releases this has been moved to .\Documents and Settings\All Users\Application Data\Microsoft\HTML Help\. Beginning with version 5.0 of the shell32.dll we can make a call GetSpecialFolderPath(...) using the CSIDL_COMMON_APPDATA flag. We can also use the collectionnum tag found in msdnxxx.col to determine which directory the hhcolreg.dat is found. Typically if this value is less than 10000 the the file is located in the Windows/Help directory.

Editing the collection file

Now that we have located both the msdnxxx.col and hhcolreg.dat files, we need to examine these files in order to integrate our data correctly. The first file we are going to look at is the msdnxxx.col file. Using a text editor, open this file. You will see two tags at the beginning of the file masterlangid and collectionnum. These are very important in our integration. The masterlangid tag tells us which language the collection is using and the collectionnum tag indicates which collection we are working with. A typical value for these tags would be:

<masterlangid value=1033/>
<collectionnum value=10001/>

Each entry in the collection will begin with a <Folder> tag and end a </Folder>. There are three values that you should be concerned with. Two of them will be TitleString tags and one LangId tag. The first TitleString tag value is what you would see when you select the "Contents" tab when running HTML help. The second TitleString tag value is our collection identifier. This value must be unique to the collection will be used in the hhcolreg.dat file as well. The third tag value is LangId. This value will be set to the masterlangid tag value that was found at the beginning of the file.

Here is what a typical collection entry might look like:

<Folder>
 <TitleString value="Codejock Software"/>
 <FolderOrder value=2/>
 <Folder>
  <TitleString value="=xtreme_toolkit"/>
  <FolderOrder value=1/>
  <LangId value=1033/>
 </Folder>
</Folder>

Editing the registry file

Next we are going to update the hhcolreg.dat file. Open the file with a text editor. You will notice that each entry begins with a <DocCompilation> tag and ends with a </DocCompilation>. There are six tags that we should be concerned with here. The DocCompId tag contains the same value as the second TitleString value mentioned in the collection. This value is unique to the collection and must match exactly! The DocCompLanguage tag contains the same value as the LangId value mentioned in the collection. This value must match the masterlangid tag. The ColNum tag is the collection number. This value must match collectionnum tag found in msdnxxx.col. The TitleLocation tag contains the full path to where your *.chm file is located. The IndexLocation tag contains the full path to where your *.chi file is located. The last tag is the Version tag. This is the current version of your help file.

Here is what a typical registry entry might look like:

Editor's Note: The TitleLocation and IndexLocation lines below in bold were broken for display purposes. Each tag should exist on a single line.

<DocCompilation>
 <DocCompId value="xtreme_toolkit"/>
 <DocCompLanguage value=1033/>
 <LocationHistory>
  <ColNum value=10001/>
  <TitleLocation value="C:\Program Files\Microsoft "
   "Visual Studio\MSDN\2000OCT\1033\Xtreme.chm"/>
  <IndexLocation value="C:\Program Files\Microsoft "
   "Visual Studio\MSDN\2000OCT\1033\Xtreme.chi"/>
  <LocationRef value=""/>
  <Version value=2/>
 </LocationHistory>
</DocCompilation>

Getting it all to work

You will need to generate a .chi index and a binary table of contents when you compile your HTML help file. Both are requirements for use with MSDN collections. To do this, you will need to add "Create CHI file=Yes" and "Binary TOC=Yes" to your .hhp file under the [OPTIONS] section. It is also recommended that you place your .chm and .chi files in the MSDN collection directory, but this is not a requirement for your collection to work properly. After you have completed editing the collection files, open the MSDN Library collection. Select the index tab to generate the index for your help title. A dialog will appear informing you that your index is being generated.

Tools for creating HTML help

Before you begin the journey into MSDN integration, first you will need to create your HTML help files. In order to do this you must have HTML Help Workshop installed on your machine. This program is what will compile your HTML files into a .chm file. This program is free and can be downloaded from Microsoft by following this link.

I have also found an excellent utility that has saved me literally hundreds of hours when creating html help documentation. I would highly recommend you check out the FAR application created by the Helpware Group. This shareware application is very reasonably priced and can be downloaded by following this link.

The MSDN Integration Utility

Well if after all of that if you are completely confused, don't worry, we have an Ace up our sleeves...the MSDN Collection Integration Utility! This program will actually integrate your HTML help files for you! Browse to the location of your .chm and .chi files, supply the title string to be used in the collection, and define a unique identifier to be used for your help files. You can use any string you desire for the unique id, however the safest approach would be to use a GUID to ensure uniqueness. You can create one automatically by pressing the "Gen. GUID" button. You also have the option to set the version label for your help as well. Once you have defined the required fields, the utility will take care of the rest by pressing the "Integrate with MSDN collection" button!

You can download the executable and the complete project source code. All of the integration code has been encapsulated into a single class CMSDNIntegration. You can use this class with any MFC application to create your own integration utility. Included with the download is is a HTML help file that you can use to test the program with. The help file is a complete reference for the CMSDNIntegration and CLoadLibrary class. The CLoadLibrary class is a wrapper that is used for loading dll's and determining the version number.

...enjoy!



Downloads

Comments

  • As to the reasons all people are dead wrong on shoes and also the reason why you should certainly check this out guide.

    Posted by BobHotgloff on 05/25/2013 01:39pm

    The essentials behind sneakers for you to take pleasure in commencing today. [url=http://www.shoesjp.biz/new-balance【ニューバランス】-c-670.html]ニューバランス[/url] The reasons why pretty much everything you read about sneakers is simply drastically wrong and what you want to realize. [url=http://www.shoesjp.biz/nike【ナイキ】-c-634.html]ナイキスニーカー[/url] Quick report helps you with some of the workings of shoes and the things one should do right now. [url=http://www.kutujp.biz/]アシックス[/url] Great new sneakers Publication Shows The Way To Rule The shoes Scene [url=http://www.kutujp.biz/アディダス-adidas-c-4.html]アディダス[/url] Why all the things you have discovered about shoes is simply completely wrong and what you ought to understand. [url=http://www.kutujp.biz/アシックス-asics-c-3.html]アシックス[/url] The greatest plan for the shoes that one could learn today. [url=http://www.kutujp.biz/ナイキ-nike-c-13.html]ナイキ[/url] The latest guideline unveils the concept over shoes and then why you have got to take action straight away. [url=http://www.kutujapan.org/]アシックス[/url] Great new sneakers Ebook Unveils Ideas On How To Rule The sneakers Arena [url=http://www.kutujapan.org/adidas-アディダス-c-74.html]アディダス[/url] Creative shoes Book Unveils Simple Methods To Dominate The shoes World [url=http://www.kutujapan.org/new-balance-ニューバランス-c-13.html]ニューバランス[/url] Whatever the industry experts might not be alleging on the subject off sneakers and ways this has impact on you. [url=http://www.kutujapan.org/nike-ナイキ-c-78.html]ナイキ スニーカー[/url] The reason why all are extremely wrong in regards to shoes and as a result reasons why you need to read this expose.

    Reply
  • Gossips, Untruths Along With mulberry bags

    Posted by hekvvddtest on 05/19/2013 11:17pm

    The dresses are availa .. [url=http://www.bymulberrybags.co.uk/]mulberry handbags[/url] [url=http://www.sportnikeairmax2012go.com/]2012 air max[/url] It's about the small stuff and details as the weeks begin.

    Reply
  • My Favorite Idiot's Manual For mulberry bags Simplified

    Posted by hekvvddtest on 05/19/2013 08:31pm

    Indeed modern branded shoes are worth buying.. [url=http://www.bycheapniketrainers.co.uk/]nike trainers[/url] [url=http://www.sportnikeairmax2012go.com/]2012 nike air max[/url] The designs of the modern shoes are modelled by expert designers.

    Reply
  • Everything that everyone else engages in when contemplating nike and furthermore exactly what youshould do different.

    Posted by icoppyapedcap on 04/22/2013 11:51am

    JhhPbmGotLmr[url=http://www.guccisayihujp.biz/]グッチ 財布[/url]FruOjxGlwXyc [url=http://www.guccisayihujp.biz/【グッチ】レディース財布-c-5.html]グッチ キーケース[/url]FzvWqhWmwYrm [url=http://www.guccisayihujp.biz/【グッチ】レディース長財布-c-6.html]gucci 長財布[/url]KmiZtbRrwDht [url=http://www.guccisayihujp.biz/【グッチ】ショルダーバッグ-c-2.html]gucci バッグ[/url]RomJkhNagYxw WmjZlnXhdYho [url=http://www.adidasgekiyasu.biz/]adidas スニーカー[/url]WvlMrvVliQfd [url=http://www.nikegekiyasu.biz/]ナイキスニーカー[/url]LqiSffYtiEbq DtqDybByaEmb [url=http://www.chanelsayihujp.biz/]シャネル バッグ[/url] JswPosOnpPrk [url=http://www.chanelsayihujp.biz/シャネル財布-c-9.html]シャネル 財布 新作[/url]OaiAvqYsoNzc [url=http://www.chanelsayihujp.biz/シャネル-ショルダーバッグ-c-1.html]シャネル マトラッセ[/url]ZohYsxCksYmc WrxBxgDtsQbc [url=http://www.chloesayihujp.biz/]クロエ バッグ[/url] MobVykWegHio [url=http://www.chloesayihujp.biz/クロエ-長財布-c-3.html]クロエ 長財布[/url] JfpRvuNkuOov [url=http://www.chloesayihujp.biz/クロエ-ハンドバッグ-c-2.html]クロエ バッグ[/url] XmxHqtEqwGwg

    Reply
Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • IBM Worklight is a mobile application development platform that lets you extend your business to mobile devices. It is designed to provide an open, comprehensive platform to build, run and manage HTML5, hybrid and native mobile apps.

  • Live Event Date: November 13, 2014 @ 2:00 p.m. ET / 11:00 a.m. PT APIs can be a great source of competitive advantage. The practice of exposing backend services as APIs has become pervasive, however their use varies widely across companies and industries. Some companies leverage APIs to create internal, operational and development efficiencies, while others use them to drive ancillary revenue channels. Many companies successfully support both public and private programs from the same API by varying levels …

Most Popular Programming Stories

More for Developers

Latest Developer Headlines

RSS Feeds