DIPasDoc 0.8.1 - Readme

License | Compile | Install | Usage | History | Open Issues | Concluding

DIPasDoc generates HTML documentation from comments in Pascal unit source code files. It outputs browsable help as standard Html files and can also create complete and customizable MS HtmlHelp projects. It 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.

DIPasDoc continues the development of PasDoc, originally written by Marco Schmidt and published under GNU General Public License (GPL). The original source did not compile with Delphi, so we worked on it a bit and now it does compile with Delphi and Kylix. We also fixed quite a lot of bugs and introduced some new features.

DIPasDoc successfully compiles with Delphi 4, Delphi 5, Delphi 6 and Kylix (which needs more testing). Other versions are yet untested, but are likely to work as well.

License

Since the original PasDoc is Open Source under GPL, DIPasDoc is also released as Open Source under GPL. Click here to view the GPL.

All changes to the original PasDoc sources are copyright The Delphi Inspiration - Ralf Junker 2001-2002.

Compile

To compile the program executable, simply open the file DIPasDoc.dpr located in the Source subdirectory and compile the project by either pressing F9 or via the Project/Build menu. The executable file should be placed in the Source subdirectory.

DIPasDoc should compile straight out of the box. If it does not, please check the following:

Install

Installation is fairly simple: Since DIPasDoc is a command line utility, simply copy the DIPasDoc executable (i.e. DIPasDoc.exe in Windows) into any directory which is included into your search path (i.e. your Windows folder if you are running a Windows OS). If you don't want to do this, open a console window and go to the path where the DIPasDoc executable is located.

Usage

Type DIPasDoc -? to see the new syntax. With Version 0.7 I have changed the syntax to be easier to parse and to be more compatible with the Delphi command line compiler BCC32.exe.

An introduction and more detailed documentation for the original PasDoc is available in Acrobat Reader format (PDF). I have tried not to break the program's functionality, so that document will serve as a good introduction. However, the command line syntax is now different (see above).

To test DIPasDoc.exe creating Html output, run CreateHelp.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. I have not beautified the source comments, so the DIPasDoc documentation looks a bit odd at times. However, you get an idea.

HtmlHelpTo create a HtmlHelp project, run CreateHtmlHelp.bat. Again, it will run DIPasDoc on its own sources and create both the Html files and the HtmlHelp project files in the Help directory. DIPasDoc will then try to find the MS HtmlHelp compiler on your system and run it. If everything went all right, the compiler will place the Help.chm file in the Help directory. Open it to see the results.

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

-C<FILE>: The HtmlHelp custom contents file format

The -C<FILE> switch allows you to specify a file from which DIPasDoc generates the HtmlHelp contents file. This way you can include additional entries and Html files into the contents tree and / or restructure the default order of items. If you do not specify this file, DIPasDoc will still generate 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 the Text part will show up as text in the HtmlHelp context tree and the Link part must point to a file relative to the path where the HtmlHelp project file will be located. You may also indent lines (by space or tab) which will reflect in the tree. Here is the file used by CreateHtmlHelp.bat:

Line File HhcContents.txt
1
2
3
4
5
6
7
Introduction=
 Read me first=..\ReadMe.htm
 License=..\License.txt
 =@Legend
AllUnits=@Units
=@Classes
Other files generated=@Overview

There are various combinations of Text=Link lines. Since 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 character and will be subitems of line 1. Notice that line 6 does not have a Text part (no characters in front of "="), so the HtmlHelp compiler will take the title of the linked page as the text. There are a four shortcuts which DIPasDoc will automatically expand. Their names are self-explanatory, so run CreateHtmlHelp.bat to see their effects. Notice that you can also link to files you provide yourself, like lines 2 and 3 do.

History

Author: The Delphi Inspiration - Ralf Junker <delphi@zeitungsjunge.de>
Homepage: http://www.zeitungsjunge.de/delphi/
Version: 0.8.1
Date: 10. June 2002

DIPasDoc 0.8.1 - released 10. June 2002

Bugs Fixed

DIPasDoc 0.8.0 - released 7. June 2002

Starting from Version 0.8.0, rjPasDoc changed its name to DIPasDoc.

New Features

Bugs Fixed

rjPasDoc 0.7.0 - released 12. July 2001

New Features

Gone Features

Bugs Fixed

rjPasDoc 0.6.22 -released 30. June 2001

New Features

Bugs Fixed

Version 0.6.21 - released 21. June 2001

We have fixed some bugs of the original version, corrected some of its functionality and added a few new features:

Open Issues

DIPasDoc rarely crashes with an EAccessViolation when running on many and large source files. We have not yet traced its cause, but expect it to be a very tedious search. On most sources, however, DIPasDoc works just fine.

Lots could be improved, but time is precious. Some 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 could 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.

Improved parsing for records and enumerated values is also needed. The DIPasDoc source code could be made (more) Delphi-like, objects changed into classes, long strings used instead of short strings, compiler warnings removed, etc. Last but not least, it needs some more testing.

Concluding

DIPasDoc does it job, so have fun with it. We hope you will be able to use it for something useful. If you are using DIPasDoc, let us know so we can add your URL to the users section of our homepage.

If you have an opinion on DIPasDoc or want to participate with its development, please e-mail. We always welcome feedback, suggestions, bug-fixes and new features.