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 -? | moreto 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.
-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
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:
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: