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.
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.
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:
Source
subdirectory.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.
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.
To
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 formatThe -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
:
|
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.
Author: | The Delphi Inspiration - Ralf Junker <delphi@zeitungsjunge.de> |
Homepage: | http://www.zeitungsjunge.de/delphi/ |
Version: | 0.8.1 |
Date: | 10. June 2002 |
$J
) was not checked in the project's Options
/ Compiler tab. Fixed this by changing all variables to use the var
instead of const
keyword. Thanks to Gasper Kozak <gasper.kozak@email.si>
for sharing his confusion about this.Objects.pas
.Starting from Version 0.8.0, rjPasDoc changed its name to DIPasDoc.
nil
.-S<FileName>
switch)
may contain wildcards (*?
).Languages.pas
unit contains all language and translation definitions and only this file
needs to be modified to add new languages. Everything else is taken care of
automatically, including the command line help. Also, if some language item
is not included in the translation, the default (English) text will be used
and no warning will be issued. If you speak one of DIPasDoc's languages, I
would appreciate if you could check "your" language for typing errors
and missing translations, using the English translation as a reference. Also,
new translations are of course always welcome.-Lru1251
, -Lru866
, and -LruKOI8
for Russian output. -Ldk
for Danish output.-Lit
.-Lsk
for Slowak output.-Lse
.overload
, etc.) which caused a parsing error
if a semicolon did not not separate and terminate the directives. Thanks to
Alexander Lisnevsky <alisnevsky@yandex.ru>
showing me that the semicolons can be omitted.{$ELSE}
bug which was unfortunately not properly
fixed in Version 0.6.22 and occurred again in a different
scenario. The scanner did not properly skip nested {$DEFINE ...}
conditional defines in conjunction with {$ELSE}
. Now everything
should be fine. See comment in SkipUntilElseOrEndif
(Scanning.pas)
for details.@code( ... )
was limited to the length
of a ShortStiring (255 Chars at most). Replacing this by an AnsiString removed
this restriction.-HtmlHelp
, rjPasDoc
generates all files needed by MS HtmlHelp Compiler to create full fledged
HtmlHelp projects directly from your sources (idea and first implementation
thanks to Wim van der Vegt <wvd_vegt@knoware.nl>).
HtmlHelp output is adjusted to the needs of that format and slightly differs
from standard Html output. To create the HtmlHelp file, simply open the project
(*.hhp) in HtmlHelp Workshop and compile. rjPasDoc will try to find the MS
HtmlHelp compiler to compile the project. If this is not what you want, specify
the -XHHC
option. For plain Html output (default), use the
new -OHtml
option.-T<TITLE>
comand line option allows to set
the title for both plain Html and Htmlhelp output.-N<Name>
option for setting a help projects
name. rjPasDoc will name *.css
files and the HtmlHelp project
according to this switch. -C<FILE>
switch to allow customized HtmlHelp
contents files. See Usage for details.Tex.pas
unit. So there is no LaTeX output any more.
I did not need it, did not maintain it, and nobody else said they would. All
LaTeX related options are gone as well.-k
option (keep formatting). It did
not show an effect anyway.DispInterface
types are now properly parsed as CIO (Classes,
Interfaces, Objects).}
. Example: {$DEFINE
MyDefine }
(notice the space after MyDefine
) is now
treated like {$DEFINE MyDefine}
(without the space).property Color;
). Where a colon was wrongly
inserted into the docs before, it is now a semicolon.objects.pas
(suggested by Wim van der Vegt <wvd_vegt@knoware.nl>).published
visibility, also included in rjPasDoc.exe
and automatically copied to the output directory. Also added alt
attributes for all images.unit MyUnitName
in their unit's clause.
Since duplicate unit names are not allowed, the source file parsed last will
be discarded and will not appear in the documentation.class MyClass=class;
) and does no longer create empty documentation
for those classes. Comments in front of the forward declaration are ignored,
only those of the defining declaration are included into the documentation.Scanning.pas
: Fixed a bug which caused the scanner to loose
track of {$ELSE}
conditional defines.@Created()
and @LastMod()
.@@
(literal @) to report a warning.We have fixed some bugs of the original version, corrected some of its functionality and added a few new features:
objects.pas
from FreePascal
sources.@exclude
, without brackets).-htmlheader FILE
switch adds contents of file to all HTML output
before the beginning of the page, just after the <BODY> tag.-htmlfooter FILE
switch adds contents of file to all HTML output
after the end of the page, just before the </BODY> tag.@Name
inserts the name of the current item (no brackets required).@ClassName
inserts the name of the class of the current item,
if there is one (no brackets required).@code(Text)
inserts the Text formatted as code
.@True
and @False
insert True / False formatted
as code
.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.
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.