MSDN Library And WxWidgets Help File
Did you ever wonder how you could integrate the (chm) help files of wxWidgets into the MSDN Library, thereby increasing the comfort and the speed of accessing them? Have you ever been dreaming about just moving the cursor over a function or class name and hitting the F1 key to receive detailed information?
These questions came up in my mind a few days ago when I had decided to use wxWidgets as my personal framework to develop cross-platform applications. Fortunately I found a way to make this dream come true. At this stage I'd like to express my heartfelt gratitude to "Pete Lees" (from the wxwindows newsgroup) who gave me a very important link to a site that was of crucial help in accomplishing this task.
- 1 Prerequisites
- 2 Creating the CHI file
- 3 Using MSDN Integration Utility
- 4 Using Visual Studio .NET Help Integration Kit 2003
- 5 Trouble shooting
- 6 Conclusion
- Get the MSDN Integration Utility from the site Mr. Lees directed me to.
Note of a second author: The last time I tried to get MSDN Integration Utility, the links in this page were broken. Fortunately, there is still a way of integrating wxWidgets help files to the MSDN library using Visual Studio .NET Help Integration Kit 2003 which I explain in a chapter below.
- Download the HTML Help Workshop utility.
Creating the CHI file
Now I'll present you with a simple step to step guide demonstrating how to make your programming experience with wxWidgets a bit more pleasant.
- Start HTML Help Workshop
- Select "Decompile..." in the File menu. Specify a destination directory for decompilation (e.g. C:\decompiled\) and choose the compiled help file (e.g. wx.chm) you'd like to see in the MSDN Library. Hit OK!
- Go to File->New to create a new project (select 'project' in the dialog that pops up). Hit 'Next' on the first page of the wizard.
- Enter a name for the project (e.g. C:\decompiled\wx.hhp). On the next page check all three checkboxes.
- The wizard will ask you for the location of the files that resulted from the previous decompilation.
- When you're finished close the application. We need to make a manual change to the project file. Just open it with an editor and add the line "Create CHI file=Yes" to the [OPTIONS] section.
- Reopen your project file with HTML Help Workshop and go to the project options (the top-most button on the vertical toolbar).
- Specify a title on the 'General' tab (e.g. "wxWidgets 2.4.2").
- Switch to the 'Compiler' tab and check the "Create a binary TOC..." option. Hit OK!
Note: It's very important to leave the "Compile full-text search information" option unchecked!
- Hit the bottom-most button on the vertical toolbar to compile your project.
- Basically we are finished, and you may use the Integration Utility now. But if we want to have search capabilities in the MSDN Library, we have to make some additional steps.
Note: To avoid a crashing bug in HTML Help Workshop we always have to compile the project first with the "Compile full-text..." option being deactivated. Afterwards we may activate this option and compile the project safely. Whenever you newly open the project you have to proceed like this.
- So go back to the project options dialog and check the "Compile full-text search information" option and compile the project. Hopefully it won't crash the application.
Using MSDN Integration Utility
The MSDN Integration Utility will sometimes fail with Visual Studio 6 installations. If this occurs, it is still possible to integrate wxWidgets help into MSDN manually. Follow the instructions laid out in the MSDN Integration Utility page. However, note that the location of the "hhcolreg.dat" file may be different. In some systems it is located in C:\winnt\help.
I hope it works for you. If it doesn't, just try using a different *.chm decompiler utility. The overall point is that we need to generate a chi file, because it is needed by the MSDN Library.
Using Visual Studio .NET Help Integration Kit 2003
Converting the Help 1.x to a Help 2.0 project
CHM files are "Microsoft Help 1.x" but Visual Studio needs a "Microsoft Help 2.0" project which is basically a bunch of XML files. That's where the Integration Kit will help you.
Note that when you installed the Integration Kit, it creates not only a "VSHIK 2003" directory but also (and silently) a "Microsoft Help 2.0 SDK" directory. (Both of this directories are usualy in
C:\Program Files\.) In this last directory, you will find the following executables:
hxconvwhich will be used to convert your CHM files to a "Microsoft Help 2.0" project
hxcompwhich will be used to compile your newly created "Microsoft Help 2.0" project
hxregwhich will be used to register your help collection and help title to MSDN Library
So now, I assume that you have both wx.chm and wx.chi files in the same directory. Execute the command:
hxconv -o wx wx.chm
This will create a
wx directory next to your wx.chm file. And this directory now contains a "Microsoft Help 2.0" project for wxWidgets.
Compiling the Help Title
The previous step has created some
wx.Hx? files but we need more of them before registering the project. This is done with the
hxcomp -p wx\wx.HxC
wx.HxC is one the files generated in the previous step.
Creating a new Help Collection
Now we need to create a Help Collection from scratch. To do so, just create the three following files in the previously created directory:
<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE HelpCollection> <HelpCollection DTDVersion="1.0" FileVersion="18.104.22.168" LangId="1033" Title="wxWidgets documentation"> <TOCDef File="wx_collection.HxT" /> <KeywordIndexDef File="wx_collection.HxK" /> <ItemMoniker Name="!DefaultToc" ProgId="HxDs.HxHierarchy" InitData="" /> <ItemMoniker Name="!DefaultFullTextSearch" ProgId="HxDs.HxFullTextSearch" InitData="" /> <ItemMoniker Name="!DefaultKeywordIndex" ProgId="HxDs.HxIndex" InitData="K" /> <ItemMoniker Name="!DefaultAssociativeIndex" ProgId="HxDs.HxIndex" InitData="A" /> <ItemMoniker Name="!DefaultContextWindowIndex" ProgId="HxDs.HxIndex" InitData="F" /> </HelpCollection>
<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE HelpTOC> <HelpTOC DTDVersion="1.0" PluginStyle="Hierarchical" PluginTitle="wxWidgets documentation"> <HelpTOCNode NodeType="TOC" Url="wx_documentation"/> </HelpTOC>
<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE HelpIndex> <HelpIndex DTDVersion = "1.0" Name = "K" Title="K-Keyword Index" Visible="Yes" LangId="1033"> </HelpIndex>
Registering the Help Collection & Help Title
Now it is time to register the documentation using the
hxreg utility. This is done, in two steps:
- first, we need to register a "namespace". It has to be unique, therefore I suggest
hxreg -n org.wxwidgets.wx -d "The wxWidgets namespace" -c wx_collection.HxC
- second, we need to register wxWidgets documentation content into this namespace:
hxreg -n org.wxwidgets.wx -i wx_documentation -s wx\wx.HxS -x wx\wx.HxI
Note that the
-i switch has to be the same as the
Url property value of the
HelpTOCNode node int the
Congratulations, wxWidgets documentation is now integrated to your MSDN Library documentation. If it still does not appear this is maybe because it is not enabled yet. To enable it, just follow the next step.
Enabling your new documentation
Go to this (weird)
ms-help://MS.VSCC.2003/VSCCCommon/cm/CollectionManager.htm URL with Internet Explorer (and ask it to enable its content). It will display a page where a "wxWidgets documentation" should appear. Enable (check) it and "update CCVS".
Now go back to your Visual Studio environment and try
Help > Content or
Help > Index (this might take a while).
If you still have troubles with integrating wxWidgets help into MSDN Library, you may be interested in the
namespace.exe utility (located into the
Unsupported Tools subfolder of the Help SDK). It displays the registered collections in a graphical interface. The namespace
org.wxwidgets.wx should appear and its content should be similar to the other items in the tree.
If all seems to be fine in this utility and if wxWidgets documentation still does not appear, maybe you have to disable and enable again the documentation (see next step of previous section). I don't know why this works... I assume that's some Windows' "magic".
You may integrate whatever CHM file in MSDN library using this method. So if you want your own code to appear in your Visual Studio environment, just create a CHM file (with doxygen for instance) and follow the steps above! One of the innumerable advantages of using doxygen is that it allows you to generate the CHI file with its configuration option GENERATE_CHI and, therefore, to skip the first step of this guide. (And it is also the new documentation utility used for wxWidgets since version 2.9.0.)