Why F1 Can Fail in the Delphi 2007 Editor

A bug has been reported that is best described on Fernando Madruga's blog here.

It turns out it is a simple logic problem with a new feature of help this version that uses the Delphi compiler to get more information about your code to provide better help. Something I overlooked and wasn't found until after we shipped. It goes something like this (obviously a bit more complex in real life):

begin
  if CanKibitzCompile then
    DoKibitzHelp
  else
    DoTokenHelp;
end;

Where DoKibitzHelp uses the compiler to get the type information and DoTokenHelp is a simple hand tokenizer that just returns the token under the cursor (even in comments). The idea was to use the kibitz compiler when we can. So the code should read:

var
  Success: Boolean;
begin
  Success := False;

  if CanKibitzCompile then
    Success := DoKibitzHelp;

  if not Success then
    DoTokenHelp;
end;

So to get help on a symbol in code that doesn't compile you can put the symbol in code where the kibitz compiler will never venture, such as comments.

How To Get Your Delphi 2007 Help Back

Sometimes the help inexplicably goes away and F1 no longer works. I've had this happen a few times and I'm not sure why but here are steps you can take to get it back:

1. Open up Task Manager and close any instances of dexplorer.exe that are running.

2. Unregister the help with the command (replace the path with the appropriate path on your system): "C:\Program Files\CodeGear\RAD Studio\5.0\Help\Doc\H2Reg.exe" -u cmdfile="C:\Program Files\CodeGear\RAD Studio\5.0\Help\Doc\h2reg.ini"

3. Register the help with the command (replace the path with the appropriate path on your system): "C:\Program Files\CodeGear\RAD Studio\5.0\Help\Doc\H2Reg.exe" -r cmdfile="C:\Program Files\CodeGear\RAD Studio\5.0\Help\Doc\h2reg.ini"

Changes To COM In Delphi 2007

There are two major but small changes to the COM features in Delphi 2007:

1. The tlibimp default for ignore the CanCreate option has changed to on, -Yc+. The reason for the change is since introducing the option and not generating code for CoClasses that were marked to not be created we noticed that a lot of type libraries out there are not using that type library flag correctly.

2. COM Servers (this includes applications with a Remote Data Module) do not auto register themselves when run the first time. You must pass the /regserver paramter once in order to register it. The reason for the change is it should never have been auto registering in the first place, and because of UAC on Vista we had to change it.

Color Management On Vista

I noticed the other day that in the Vista control panel there is a Color Management icon. So I started reading around and found information on Wikipedia about Vista's color management:

"A more open-concept, platform-independent view of color management is the use of an ICC-compatible color management system. The International Color Consortium (ICC) is an industry consortium which has defined an open standard for a Color Matching Module (CMM) at the OS level, and color profiles (ICC profiles) for the devices and working space. Beginning with Windows Vista, color management in Windows will be handled at the OS level through an ICC V4-compatible color management standard and API known as Windows Color System. Apple's Mac OS X and the classic Mac OS have long been capable of such color management which is called ColorSync."

I'm at a conflict here. Color management under all previous versions of Windows was a crap shoot and not consistent between computers. My wife is also an Scientific Illustrator and Artist and printing to our shared Epson 4800 with Windows resulted in many color problems. Then there is the font problem with Windows where you need print fonts and screen fonts. So all of these problems caused us to switched doing all my photography and my wife's art to a Mac a few years ago. I'm glad Windows users finally get color management with Vista, but I'm afraid I still don't recommend photographers using it due to my post last night. It would be all too easy to mess up an important photo using Vista.

Problems With Digital Camers On Vista

I noticed back in March that Microsoft issued a knowledge base article about Windows Vista corrupting RAW files from digital cameras. Well Canon has also just issued a service notice about possible data loss when using Windows Vista. "...We have discovered that the original image data of TIFF (RAW) images shot with an EOS-1D or EOS-1Ds Digital SLR Camera, and rotated or edited using Windows Explorer or Windows Gallery on a computer running Windows Vista, will disappear from the computer's memory...". There are also problems with Nikon when using vista. I'm sure all RAW plug-ins to Vista will suffer similar data loss or corruption. I think all photographers should stay away from Vista.

Update: Added info on Nikon digital cameras.

Integrating 3rd Party Help Into Delphi 2007

Below are the manual steps needed to integrate third party help into the Delphi 2007 help system. If these steps are not followed exactly the help my be left in a corrupted state.

1. Unregister our help with command "h2reg -u"

2. Copy your compiled help into the directory "C:\Program Files\CodeGear\RAD Studio\5.0\Help\Doc". It may be easier to remove it later if you copy it to a subdirectory.

3. Add your HelpTOCNode to "Master.HxT". If your help is only one part add these lines to the file: (obviously put your title inplace of "YourTitle")

  <HelpTOCNode Title="YourTitle" Url="mshelp://borland.bds5/YourTitle/index.html">
    <HelpTOCNode NodeType="TOC" Url="YourTitle" />
  </HelpTOCNode>

If your table of contents is more complex follow the examples in the file.

4. In h2reg.ini, you need to add two lines for each .HxS file you have. The first is under the "[Reg_Title]" section. If you only have an .HxS file with no .HxI file add this line: (path is relative to the h2reg.exe, if your files are in the same directory you don't need the path)

  borland.bds5|bds5start||YourTitle.HxS|YourTitle.HxS|

If you have an .hxi file add this line:

  borland.bds5|YourTitle||YourFile.HxS|YourFile.HxI|

The second line you need to add is under the "[UnReg_Title]" section. The line is:

  borland.bds5|YourTitle|

5. Register the help by running "h2reg -r"

6. View the help with: (the first time will show a status bar)

  "%CommonProgramFiles%\Microsoft Shared\Help 8\dexplore.exe" /helpcol 
     ms-help://borland.bds5"

Documentation/Help In Delphi 2007 Part IV

For me the most interesting topic about the help system is the F1 key in the IDE. Another embarrassment is when we moved to the Galileo IDE, the first product we released was C#Builder, so the F1 code was changed quite a bit. Specifically it was changed for C# and not general purpose or personality aware. So I looked back at the Delphi7 code base, took some of that code and added a bunch more so help is a whole lot smarter. I made the Object Inspector, Editor, and Form Designer personality aware so you will be more likely to go straight to the content you are looking for instead of having to choose the personality you want documentation for every time you press the F1 key.

When you press F1 on a component in the Form Designer the code checks to see if the component is in the help, if it isn't, by using the RTTI, the process is repeated with the parent class until help is found on the component or if TComponent then no help is found.

When you press F1 in the Object Inspector the same process is performed as above only looking for the property or event on the given component. If that search fails then just the component name is searched for. If all that fails then no help is found.

When you press F1 on a dialog the ContextID is used to find help. We format the string with "BDS5:" so we can also search for context IDs as keywords from the .NET side of the IDE.

The most interesting things happen when you press F1 in the editor. For this work I had to add a few things to the compiler because I go through the kibitz compiler to get scoping and type information. I also added the ability for the editor to use the compiler associated with the file in question. The kibitz compiler doesn't support certain parts of a .pas file, so when the kibitz compile fails a token parser is used.

Part I
Part II
Part III
Part IV