DIPasDoc 0.8.7 - 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 successfully compiles with Delphi 4, Delphi 5, Delphi 6, Delphi 7.


License

DIPasDoc is released as Open Source under GPL. Click here to view the GPL-License.

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


Compilation

A precompiled binary is available for the Win32 operating system, which should work fine on Win95, Win98, WinME, Win2K and WinXP. It is located in the /Win32 directory.

If you want to recompile the program executable yourself, you need to download DIContainers from the Delphi Inspiration's web site first. After installing and adjusting the path of your Delphi IDE, proceed compiling DIPasDoc itself.

Open the file DIPasDoc_Console.dpr located in the \Source\Console subdirectory and compile the project by either pressing F9 or via the Project/Build menu. The executable file will be placed in the same folder.

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

Installation

Installation is fairly simple: Since DIPasDoc_Console is a single-file command line utility, simply copy the DIPasDoc_Console executable (i.e. DIPasDoc_Console.exe for 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_Console executable is located.

TDIPasDoc Component installation into the Delphi IDE

If you want to use the TDIPasDoc component to build your own DIPasDoc applications, you need to download DIContainers from the Delphi Inspiration's web site first. After installing and adjusting the search path of your Delphi IDE, proceed installing the TDIPasDoc component into the Delphi IDE.

Create a new package and add the file \Source\Component\DIPasDoc_Reg.pas. Next click the Install button, and the TDIPasDoc Icon should appear on the Delphi component palette.


Usage

Type one of the following

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 of the original PasDoc is available in Acrobat Reader format (PDF). I have tried not to break the program's functionality, so that document still serves as a good introduction. However, the command line syntax is now different (see above).

To test DIPasDoc_Console.exe creating Html output, run Create_Help.bat. This will run the program 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. The source comments are not beautified, so the DIPasDoc documentation looks a bit odd at times. However, you get an idea.

HtmlHelpTo create a HtmlHelp project, run Create_HtmlHelp.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 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 Create_HtmlHelp.bat:

Line File HhcContents.txt
1
2
3
4
5
6
7

8
Introduction=
 Read me first=..\ReadMe.htm
 License=..\License.txt
 =@Legend
AllUnits=@Units
=@ClassHierarchy
=@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 lines 6 and 7 do not have Text parts (no characters in front of "="), so the HtmlHelp compiler will take the title of the linked page as the text. There are some 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.7
Date: 14. January 2004

DIPasDoc 0.8.7 - released 14. January 2004

New Features

Bugs Fixed


DIPasDoc 0.8.6 - released 31. March 2003

New Features

Bugs Fixed

Dropped Features


DIPasDoc 0.8.5 - released 18. December 2002

New Features

Bugs Fixed

Dropped Features


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

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


Open Issues

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.

Language-dependend stopword lists for HTML Help full text search to create smaller *.chm files.

The DIPasDoc source code could be made (more) Delphi-like, objects changed into classes, compiler warnings removed, etc. Last but not least, it needs some more testing.

How about additional output styles? For someone familiar with RTF, it should not be too hard to code RTF-Output to produce WinHelp files. Also, LaTeX has been requested again, but only once.

If anyone knows how to call HTML Help from the Delphi IDE (similar to the Delphi Help), please get in touch.


Concluding

DIPasDoc does it job, so have fun with it. I hope you will be able to use it for something useful. If you are using DIPasDoc, let us know so I can add your URL to the users section of the Delphi Inspiration's 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.