See what's going on with flipcode!

This section of the archives stores flipcode's complete Developer Toolbox collection, featuring a variety of mini-articles and source code contributions from our readers.


  Integrating DirectX 8 Into MSDN
  Submitted by

It was really starting to annoy me that I couldn't just hit F1 from within my source (under Visual Studio 6) on a DirectX8 function call and get help through MSDN for DirectX 8. I never found any resources on the net about this, so I went hunting around through my system and figured out how. If there's a better reference on the net, somebody please post it in the comments.

Look in the directory:

C:\Program Files\Microsoft Visual Studio\MSDN98\98VS

From there, you'll see another directory which is specific to your language. On my system, it is '1033'. If you look in there, you'll find a lot of CHM and CHI files.

First, go find your DX8 help files. They are called directx8_c.* (for C++) and directx8_vb.* (for Visual Basic). There will be two files for each, a CHM and a CHI file. Copy these into your language specific directory. In my case, I'm a C++ programmer, so I just copied the directx8_c.chm and directx8.chi files into my '1033' directory. I'm going to describe how I got this working on my machine with just the help files for C++, but if you want to add support for VB help (or both) you should be able to figure it out relatively easily.

The CHM files are compiled HTML files (called "chums") and the CHI files are the index files for each associated CHM file. In your language-specific directory, you'll also see a msdnvs98.CHW file, a msdnvs98.CHQ file and a msdnvs98.COL file.

The CHW file is the combined index file (i.e. when you open up the index pane under MSDN.) This is a binary file.

The CHQ file is the index file used for word searches (i.e. when you open up the search pane under MSDN.) This is a binary file.

The COL file describes what you'll find in the table of contents. This is an XML file.

If you study the COL file, you'll see how the treeview (for the contents) is arranged. Here, you can add your directx8 help file. You can add it to the tree wherever you want, but I recommend replacing the DX5 documentation that's already there. This documentation is out of date anyway. So find the string "=dxfound" and replace it with "=directx8_c" (for C++) or "=directx8_vb" (for Visual Basic.)

Immediately following that, you'll find an entry for dxmedia. This is also out of date and contains duplicates from the new DX8 docs), so I removed it from mine. If you want to remove it, make sure you remove the whole thing (from <Folder> to </Folder>).

Save the COL file. You're done with it.

If you open up MSDN and go to the contents, then open up "Platform SDK" and then look in "Graphics and Multimedia Services" you'll notice that the directX stuff that used to be there, is no longer there. But the new stuff isn't there either. Why?

Because we never told MSDN that the file (directx8_*) is actually part of the document set. So go find your hhcolreg.dat file. In my case, it's in the C:\WINNT\HELP directory. Before you edit this file, make sure MSDN is not running.

The hhcolreg.dat file is also an XML file. Go to the bottom of the file. You'll see a bunch of <DocCompilation> </DocCompilation> groups. Take notice that these are all within a huge <DocCompilations> grouping. Take further notice that there is a difference between <DocCompilation> and <DocCompilations>. :)

Using copy/paste, duplicate the last block -- it should be about 16 lines. Looking at your duplicated block, find the tag and change the value to equal your directx8 base filename (again, in my case, it is "directx8_c").

Finally, remove the <QueryLocation> tag line alltogether. If you leave this in, then MSDN will try using the existing CHQ file when you perform searches. By removing this, you're telling MSDN that the CHM file's index is not integrated into the CHQ file, and MSDN will search it separately. I never found a way to rebuild the CHQ file, so this is necessary.

So, what we've done so far...

We've edited the COL file to add our stuff to the MSDN table of contents. We've modified the hhcolreg.dat file to tell MSDN to access our new help files. This will get MSDN to recognize our file in the table of contents. And since we removed the CHQ file reference in the hhcolreg.dat file, we've told MSDN not to use its combined search index for searches.

The only thing left, is to rebuild the CHW file, which is used for the index pane in MSDN. Fortunately, this is automatic. Just open up MSDN and click on the 'index' pane and it will automatically rebuild the CHW file.

That should do it. DX8 should be fully integrated now, without the old DirectX or DirectMedia stuff getting in the way and cluttering up our search results.

Paul Nettle

The zip file viewer built into the Developer Toolbox made use of the zlib library, as well as the zlibdll source additions.


Copyright 1999-2008 (C) FLIPCODE.COM and/or the original content author(s). All rights reserved.
Please read our Terms, Conditions, and Privacy information.