Zugg Software :: View topic - Delphi Tip #2

Posted: Tue Mar 14, 2006 7:12 pm

Ever since I installed Delphi 7 a couple of years ago, I've had problems with the F1 context-sensitive help system within the Delphi IDE.

In past versions of Delphi, you could put the cursor over the name of a class and press F1 to load the help file for that class. In Delphi 7, this broke for 3rd party components whose help was added via the Delphi OpenHelp system.

Apparently the help system got even worse in later versions of Delphi (I hear that Delphi 2005 was a complete mess). But since Delphi 7 remains the best Win32 version of Delphi, I don't plan to upgrade. So this article concerns the help system in Dephi 7 only.

The other night I finally got fed up with the non-working F1 help and went on a crusade to get it working. After all, it works fine for internal Dephi classes such as TLabel or TEdit. So how could it work for internal Delphi classes but not work for 3rd party components?

There is a lot of misinformation on the Internet about this. If you spend time with Google (like I have), you will see a lot of posts that just give the simple answer of putting the 3rd party HLP files into the Index and Link sections of Delphi Open Help (via the Help/Customize menu in the IDE).

The problem is that this still doesn't work. It allows you to select a component in the component pallette and press F1 to get help, and it works for getting help from the properties in the Object Inspector. But it still doesn't work with F1 in the source code.

For Delphi 7, ignore all of the posts talking about the limits in the Windows help system. Those limits do not exist in Windows XP, so there is no problem putting as many HLP files as you want into the Link and Index sections. That isn't the problem.

What you'll eventually learn is that Delphi started using something called ALS files for their keywords. ALS files are a list of A-LINK records from HLP files. If the 3rd party component help doesn't use A-LINKs then you are out of luck. Fortunately, many do.

First, take a look at the D7.ALS file that is in the Delphi Help directory. This is the keyword file that is used by the F1 system to load help for the internal components. All thats in this file is a sorted list of keywords. Apparently Delphi just uses this file to determine if help is available for the word under the cursor when F1 is pressed. There is no file or link information in the ALS file...just a sorted list of keywords.

So, to get F1 help for 3rd party components, you just need to merge the list of keywords into this D7.ALS file.

Some people claim that just putting a vendor's ALS file into the Delphi Help directory will work. Well, this doesn't work for me. It seems that Delphi *only* looks in the main D7.ALS file when using F1 from the source code editor.

Fortunately I found a tool that can help with this called CHI (http://www.delphidabbler.com/software?id=chi
There is a related article explaining how Delphi help works at: http://www.delphidabbler.com/articles?article=15

The CHI utility handles the normal Index and Link files for OpenHelp. But most importantly, it can also merge a 3rd party ALS file into the D7.HLP file.

The only job left is generating the ALS file itself. As mentioned in the above article, the Microsoft Help Workshop can do this, and the Help Workshop is included in the Delphi Help/Tools directory (HCW.EXE). Simply use the File/Report menu command and select the A-Link option. This will save a list of A-Link records to a file.

The problem is that this file isn't yet in the correct format. There are two header lines at the beginning that need to be deleted. And if you look at the resulting report file and compare it with the D7.ALS file you'll see that Delphi wants a single keyword per line, whereas the output from the Help Workshop has more that one keyword on a line. From what I could tell, it looks like the first keyword is the correct one. So I just wrote a simple utility program that goes through the Report output file and removes everything on a line after the first tab. This seems to be the correct format for the D7.ALS file.

I'm not going to bother uploading my utility to strip the stuff after the tab in the Report output of HCW...any Delphi programmer could create their own in about 5 minutes.

So here are the steps I finally used to get F1 help working in Delphi 7:

1) Run HCW.EXE and use File/Report A-Link to generate an ALS file from the 3rd party HLP file. If the 3rd party help file supports A-Link records, then you'll get a proper list of keywords.

2) Strip the first two lines of the report output, and if a line contains a tab character, strip it along with the text after it on the line. Save the result to an ALS file with the same name as the HLP file.

3) Place both the HLP and ALS files into the Delphi Help directory.

4) Run the CHI program to merge the 3rd party ALS file into the D7.ALS file and to get all of the proper entries in the Index and Link portions of OpenHelp.

5) Delete any *.GID files in the Delphi Help directory, or in the Windows Help directory. These are cache files created the first time you use a help file that need to be removed to force Windows Help to create new indexes.

Now run Delphi and when you put the cursor over any keyword in the ALS files you can press F1 to load that help.

This works not only for 3rd party components, but also for the Win32 MSDN help files that come with Delphi. So you can also restore the F1 functionality when you place the cursor over Windows API routines.

It took a while to put all of this together and really get it working. Hopefully this will help other Delphi programmers who also miss getting their F1 help. It's truely a shame that Borland let the help system get so out of control. Sure, there were problems with Windows Help on older versions of Windows, but those problems mostly don't exist in Windows XP. And instead of moving towards a better standard such as HTML Help, Borland instead implemented a system that was no longer easily extensible for 3rd parties. Putting every keyword into the single D7.ALS file is a bit mistake and makes it very difficult for 3rd party component builders. Fortunately, if you are willing to do a few hours of work, you can fix this using the instructions in this article.

Good luck!

Posted: Wed Nov 01, 2006 3:33 am

Hi