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 HTML Help 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.
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:
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.
-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
Read me first=..\ReadMe.htm
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.
products/pasdoc/index.txt · Last modified: 2007/12/21 16:14 (external edit)