Homepage: http://delphidoc.sourceforge.net/
Project-Page: http://sourceforge.net/projects/delphidoc/

Remarks on the Source Code of JADD - Just Another DelphiDoc

Table of Contents

• Compilers (Delphi Versions)
• Release - Libraries
• Preparations
• Compiler Symbols
• Kylix
• Final Remarks

Compilers (Delphi Versions)

DelphiDoc should be able to be compiled under Delphi 4 and newer versions and on Kylix 3 (and probably newer versions, if there ever will be any). I compile with Delphi 4 (with update 3) and sometimes check with Delphi 7 and Kylix 3 - Open Edition. Because it compiles with Kylix I assume it won't have a problem with Delphi 6, or at least not too many. But Delphi 5 might have some problems because I use conditional compiling to implement features not available in Delphi 4, so if a feature is also not available in Delphi 5 you might have to change some VER120 to VER130.

And it can probably be adjusted for Delphi 3, there are only two pairs of overloaded methods, but I don't know, how often default parameters are used, also the type Cardinal is used more often. But it will get increasingly harder with each release because Delphi .NET does not support many things of the normal Delphis, and most times to get around this, features of Delphi 4+ have to be used. Still, DelphiDoc can't be compiled for .NET, and this will probably stay this way for some time.

For not Delphi's (like FreePascal or GPC, the GNU Pascal Compiler, but the latter won't probably work) I can't make any statements on the language, but in the actual parsing of the source code and generating of the documentation (also the command line client), I used only very few classes, an implementation of the classes TStringList (and its abstract base class TStrings) and TList should suffice.

Warning: This is no API! Parameters are not checked every time, you have to give sensible values or the error may occur later some time or you simply get a wrong result. There are some assertions but they are not extensive nor complete.

I've heard that the Delphi 6 compiler has some bugs, maybe there are updates/patches, so if you get the following error, please look for them. The compiler may abort with the "Internal Error L1030" when a dynamic array is declared in a function and the base type is also locally declared, i.e.:

      procedure Something;
      type      TBaseType = ...;
      var       MyArray  :array of TBaseType;
      begin
      ...
    

Release - Libraries

The release consists of four parts.

1. A library to represent parsed pascal data, files and identifiers. Also supports its writing to and reading from files. It is located in the subdirectory Idents.
2. A library to parse pascal source to the internal representation of the first library. It's mainly located in the subdirectory Parser.
3. A library using the first one to generate documentation about the parsed data, mainly located in the subdirectory Generator.
4. The programs to use these three libraries, in the directories GUI, respectively Command. Of course the libraries could be used for other things than just these programs.

Preparations

Before compiling DelphiDoc you should check two things, although they are now automatically set on each release.

First, if you want to compile the GUI version (that's probable), please refer to the section below to define some compiler symbols.

Second, the generated .dcu-files are redirected to a special directory to prevent problems when switching between the GUI- and the console-version. You should check that the used directory exists or you will get an error. Please create the directory directly in the directory with the .dpr-files. For the GUI-version it's name is "z_dcus" and for the console-version "z_dcusCL".

Compiler Symbols

Before compiling you can define some compiler symbols.
You can disable the symbol DEBUG and the assertion to improve the performance.
You will probably need to define the compiler symbol USENORMALSPINEDIT. It will use the normal TSpinEdit components as shipped with Delphi, in both dialogs to edit the options of the generator of documentation, instead of some more advanced versions. These components are not ready for release, and probably will never be because they are quiet old (1998) and still not ready. The main problem is they are heavily base on the TSpinEdits, and those are of course copyrighted by Borland, so I can't really release them.

You can define the compiler symbol USESOURCECODEGRID to use a different component to show the parsed source code with some syntax highlighting (although not a perfect one). Without it a component close to Delphi's editor will be used (of course in read-only mode). If the compiler symbol is defined, instead a modified version of a TDrawGrid will paint each line, this is always the case with Kylix, because the editor-like component is Windows-specific, and this in turn is the only reason the grid-component exists. The grid has two main flaws: no Copy'n'Paste, and only whole lines (i.e. whole cells) can be selected, so the column of an error etc. can not be highlighted.

You can also define NOPNGSUPPORT to disable using the PNG library. There is no real reason to do that unless you are using Kylix. Analogically the symbol NOJPEGSUPPORT can be defined.

Kylix

I now stopped supporting Kylix, you can't even register it with Borland/CodeGear anymore. I still try to program compatibly but for some GUI features it would be too much work to recreate components in Kylix. So far only the component to show the messages of the generators is Windows-specific. For the source code view several versions back I had still took the time to write a simple replacement, but as said, I don't want to invest that time again. The console version should still be able to be compiled under Kylix - as I don't check everytime maybe a few small things have to be fixed.

If you want to compile DelphiDoc with Kylix, most changes on the running binary are how you expect them. No generated documentation will be launched automatically after generation, because there is no associated binary to launch them. Also Window help files are not automatically compiled (what a surprise), although it is possible to compile them with the help of Wine. And no WMF (Windows Meta File) files are created (WMF records GDI calls, of course there is no Windows GDI in *nix).
The wrong end-of-line character sequence may be used sometimes, i.e. #13#10 instead of just #10, but that should never invalidate any file.
The tree views to select the objects for the generation is sorted after the original class names, not the shown titles, it seems Qt always sorts after the original specified text and doesn't care if it has been changed meanwhile.

Finally, if you want to compile DelphiDoc from the sources you have to make some changes. I added a script "ConvertForKylix.tcl" to do this, but I will list the things anyway below, in case you want to do it manually. If you got a *nix system without TCL you don't have a proper *nix system :-P, but anyway you can read more about TCL and install it.

As of version 1.7.1 this TCL-script is actually a set of TCL files distributed in as a separate "ConvertForKylix.tcl.zip". The additional scripts contain code to handle Delphi's .dfm files and convert them for Kylix. They are called from the main file, "ConvertForKylix.tcl", so if you don't want to, you don't have to care about that, but there are also some files that can be called directly from the shell (ending in .sh.tcl). By virtue of these new files you don't have to open all forms and pages/frames in the Delphi IDE to convert them (after all that's 41 files on last count). They can actually do some more with DFM files and form data but there is no documentation and only marginal comments, so you have to do a little source-diving.

Just download the additional file "ConvertForKylix.tcl.zip", unzip it (to any directory), change to DelphiDoc's base directory (containing the .dpr's) and start the file "ConvertForKylix.tcl" (prepend the path to it if necessary), after the first confirmation the general adjustments are done, then, after another confirmation, you need to wait shortly while the dfm's are being converted.

Now you have to delete the declaration of the component UpDownFontSize: TUpDown; from the UDiagramForm.pas (around line 160), seems Kylix doesn't know that component.
Finally you have to reload all image lists, it seems the transparent color is not correctly imported, so some of the images look really weird or empty. A list of the lists and images follows below, the images are in the sub-directory "Resources/SmallImages/" and are named with a prefix and their number within the image lists (for easier reloading), remember to select the images from last to first, so the first is selected and will really be the first one. For some of the images you have to select the transparent color manually, it is mostly clFuchsia or clWhite.

What the Script does

You must define a unit alias "Windows=Types" and lots of aliases mapping the VCL-Units to the CLX-Units (i.e. to prepend a "Q", use trial-and-error until all have been mapped), this quick and dirty solution was simply the easiest way to include the right units anywhere they are needed.
You will also have to edit the options and the project file to change several paths from using "\" (backslash) to "/" (slash) and some separators from ";" to ":". I would have really expected Kylix to do this on its own.
The library for regular expressions will have two errors, just use the not-optimized version as used for Free Pascal in the same lines to fix it.
DelphiDoc is now using templates. To keep it parsable by itself the path to the included files are specified instead of only the name, so again all backslashes have to be replaced with slashes.
I don't compile regulary on Kylix now, but code with it in mind, so you may need to tweak the code a bit to get it running. When I do, I use the Borland Kylix Open Edition Version 3.0 (Build 4.186) without any unofficial patches just the official patch number 2.

You will also have to open all units with forms (and pages/frames) in Kylix to convert the old .dfm files and to ignore a lot of warnings during that. Just ignore everything, and when compiling another one, that one field has no matching component.
Before opening in Kylix it may be wise to set all Properties "Scaled" of the forms to false, or better delete the property "PixelsPerInch" (if that is possible).
There are currently about forty forms (or pages/frames), so there are lots of files to open and lots of messages to ignore, and it seems Kylix chokes sometimes on these masses and sometimes it doesn't convert the .dfm files, or at least does not remove the invalid properties. The program compiles fine, but when the form or page is shown an exception is raised talking about invalid properties. The form/page has then to be opened again and converted again.

Furthermore the shortcuts are stored as a system dependent value, so they are mixed up when loading them under Kylix, this concerns all special keys like the function keys, e.g. F6, and the delete key and have to be set again manually.

Final Remarks

For anything else try generating a Windows Help file with DelphiDoc about the sources and integrate it into Delphi to get fast and simple help about all identifiers. That's a fast and powerful solution to get acquainted with any Delphi program.

If you have further questions or want to contribute to the further developing of DelphiDoc you may contact me on the email addresse given on the main page of this documentation, or visit its project page.