PasDoc

DIPasDoc is the only free help generator that flawlessly follows compiler defines and include files. DIPasDoc is the ideal tool for source code documentation, both for your company's in-house library and your customers.

The DIPasDoc syntax tries to immitate commands from the Delphi command line compiler BCC32.exe if possible, even though it is heavily extended by special preprocessor functionality. Type:

• DIPasDoc -? for the full syntax, or
• DIPasDoc -? | more to display one screen at a time only.

To test DIPasDoc.exe creating HTML output, run Create_Help.bat. This will run DIPasDoc on its own sources, and place the documentation files in the .\Help directory. Open any of the HTML files in your browser to see the result. Since the DIPasDoc source comments are not specially beautified for HTML documentation, it looks a bit odd at times. However, you will still get an impression of the possibilities of DIPasDoc.

To create a MS HTML Help project, run Create_HtmlHelp.bat. This will again run DIPasDoc on its own sources but create optiomized HTML files as well the HTML Help project files in the .\Help directory. DIPasDoc will then try to located the MS HTML Help compiler on your system and run it. After successful compilation, a new Help.chm file will be placed in the .\Help directory, ready to be used.

If DIPasDoc does not find the MS HTML Help compiler, you must manually compile the HTML Help project. Run the HTML Help Workshop, go to the DIPasDoc Help directory and open Help.hpp. Then click compile. All the rest works as with automatic compilation.

The -C<FILE> switch allows you to specify a file from which DIPasDoc generates the HTML Help contents file. This can be used to restructure the default order of items, to include additional topics, or to link additional HTML files. If no custom file is used, DIPasDoc generates a default contents file.

The “grammar” of the custom contents file is simple. It is set up as a “tree of lines”, where each line is one item. All lines must contain a Text=Link pair separated by the equal sign, where Text shows up as text in the HTML Help context tree and Link points to a file relative to the path where the HTML Help project file will be located. Lines beginning with white-space start new hierarchies.

As an example, this is the custom contents file used by Create_HtmlHelp.bat:

Introduction=
 Read me first=..\ReadMe.htm
 License=..\License.txt
 =@Legend
AllUnits=@Units
=@ClassHierarchy
=@Classes
Other files generated=@Overview

The various combinations of Text=Link lines have the following meaning:

• Line 1 does not have a link (no text after “=”), “Introduction” will only be a book for other items.
• The next three lines 2, 3, 4 are indented by one white-space character, which makes them subitems of line 1.
• Notice that lines 6 & 7 do not have Text parts (no characters in front of “=”), so the HTML Help compiler will take the title of the linked page as the text.

There are some shortcuts which DIPasDoc automatically expands. Their names are self-explanatory, so run CreateHtmlHelp.bat to see their effects. Notice that you can also link custom HTML documents, like lines 2 and 3 do.

The core Pascal source code documentation engine is available as a its own TDIPasDodc class, which inherites from TComponent. This allows other applications to use DIPasDoc as their documentation engine. Examples are the official DIPasDoc_Console application, as well as GUI applications (also included) or automatic build systems.

Lots could be improved, but time is precious. Below is a list of suggestions. If anybody is interested, grab the source and start coding:

• More customizations (colors, fonts, etc.) should be among the more simple things on the list. Speaking in more general terms, templates would be nice to have.
• Frames – loved by some, hated by others – might improve HTML layout and make it look more like the Delphi Help with class properties and methods in a frame on the left and their descriptions to the right.
• Language-dependent stopword lists for HTML Help full text search to create smaller *.chm files.
• mproved parsing is needed to incorporate new Delphi language extensions.
• More output styles. If someone could add RTF-output this would be more than welcome, even if Vista no longer installs WinHelp by default. Also, LaTeX has been requested once.

DIPasDoc does a nice job, so have fun with it. If you are using it for something useful and would like to let others know, feel free to add yourself to the users page or share your thoughts and code at the DIPasDoc Wiki.