MSDN Library And WxWidgets Help File

From WxWiki
Jump to navigation Jump to search

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.

Prerequisites

  • 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.

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:

  • hxconv which will be used to convert your CHM files to a "Microsoft Help 2.0" project
  • hxcomp which will be used to compile your newly created "Microsoft Help 2.0" project
  • hxreg which 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 utility: 

hxcomp -p wx\wx.HxC

The 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:

wx_collection.HxC: 

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE HelpCollection>
<HelpCollection DTDVersion="1.0" FileVersion="1.0.0.0" 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>

wx_collection.HxT: 

<?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>

wx_collection.HxK: 

<?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 org.wxwidgets.wx:
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 wx_collection.HxT file.

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).

Trouble shooting

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".

Conclusion

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.)

Retrieved from "https://wiki.wxwidgets.org/index.php?title=MSDN_Library_And_WxWidgets_Help_File&oldid=6640"