TDIPasDocLicense | 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.
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.
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 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 IDEIf 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.
Type one of the following
DIPasDoc -? DIPasDoc -? | moreto 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.
To
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 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 Create_HtmlHelp.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 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.
| Author: | The Delphi Inspiration - Ralf Junker <delphi@zeitungsjunge.de> |
| Homepage: | http://www.zeitungsjunge.de/delphi/ |
| Version: | 0.8.7 |
| Date: | 14. January 2004 |
@link(MyEnumItem).TDIPasDoc.OutputCharSet which overwrites the
language default output character set. Matthew Barucha <mati@nowydwor.k.pl>
suggested this feature to create documentation for languages which use another
code page than the Pascal source file(s). Its command line parameter is -P<OUTPUT
CHARACTER SET>.deprecated" and "platform"
calling conventions introduced with Delphi 6 were not recognized for class
members. Thanks to Adrian Meyer <ameyer@a4healthsystems.com>
for the hint.dispid" directives followed
by integer constants. Bug reported by Chris Eyre <chris@chris-eyre.demon.co.uk>.type instead. Surprisingly, Delphi
compilers don't report an error on such constructs, so they appear in code
and we consider them legal as well.'windows-1250'
as the default character set (courtesy of Matthew Barucha <mati@nowydwor.k.pl>
and Czarek <smoog@poczta.gazeta.pl>).VisibleClassMembers controls the level of class
member visibility which should be included in the documentation. The command
line switch equivalent is -M<private|protected|public|published|automated><+|->.
Example: -Mprivate+ includes private members, -Mprotected-
excludes protected members from the documentation.
for automated visibility of class members.{$R+},
{$B-}, etc.{$M+} Switch Directive is defined;
otherwise such members are documented as public. Published visibility is not
yet applied to those classes which are derived from classes which are compiled
in the {$M+} state.TDIPasDoc component with GUI applications.TDIPasDoc component
GUI example.register" and "safecall"
calling conventions were not recognized for procedures and functions.external" and "name"
directives, especially when followed by string constants. Reported by Alexander
Muylaert <alexander.muylaert@etc.be>.on" from the list of Pascal reserved keywords
to avoid DIPasDoc throwing an error on class properties with the same name
as suggested by Chris Eyre <chris@chris-eyre.demon.co.uk>.(* ... *) comments was sometimes overlooked.{$IFDEF Undefined} !!! Compiler Test
Error !!! {$ENDIF}.OutputFolder was not explicitly specified, TDIPasDoc
complained by raising an exception. Changed this to using the current directory
instead.ExcludePrivate property and the -P
command line switch in favor of the more powerful new VisibleClassMembers
property (see above).TDIPasDoc now descends from TComponent. This completely
separates the documentation engine from the legacy console application and
makes the engine available to third applications, console as well as GUI applications.
Applications only needs to set the TDIPasDoc properties (which
can also be done in the Object Inspector) and call the TDIPasDoc.Execute
method.ShortStrings with AnsiStrings. Now,
with DIContainers applied throughout, DIPasDoc uses 10 (yes, ten!) times less
memory and executes 3 times faster compared to the previous release. The advantage
is most pronounced with huge projects consisting of many files.DIPasDoc_Languages.pas if
your language needs an update, too!{$IFNDEF} compiler directive could still confuse the build-in
Pascal parser to skip code which it should not.$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>).
image for published visibility, also included in rjPasDoc.exe
and automatically copied to the output directory. Also added alt
attributes for all images.
)
are now included in the rjPasDoc executable and will automatically be copied
to the destination directory. Existing files will not be overwritten, so you
may replace the default ones with your own 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.I 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.
).
Copy the images from the Img folder in the rjPasDoc archive to the folder
where your HTML output is located. (This was changed in version 0.6.22.)@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.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.
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.