rjPasDoc 0.7 ReadMe
rjPasDoc 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. rjPasDoc is the
ideal tool for source code documentation, both for your company's in-house library
and your customers.
rjPasDoc 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 I worked on it a bit so it now compiles
with Delphi. I also fixed quite a few bugs and introduced some new features.
rjPasDoc successfully compiles with Delphi 4 and Delphi 5. Other versions are
yet untested, but should work as well.
This Release — Version 0.7
New Features
- Automatic generation of MS HtmlHelp projects, including Contents
and Index files. With the new output switch
-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). 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.
- Introduction of Cascading Style Sheets. The default style sheet is
very basic. So you have all options to change it and extend it since rjPasDoc
will not overwrite it once it is in the output path.
- New
-T<TITLE> comand line option allows to set
the title for both plain Html and Htmlhelp output.
- New
-N<Name> option for setting a help projects
name. rjPasDoc will name *.css files and the HtmlHelp project
according to this switch.
- New
-C<FILE> switch to allow customized HtmlHelp
contents files. See Usage for details.
Gone Features
- Removed
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.
- Completely removed the
-k option (keep formatting). It did
not show an effect anyway.
Bugs Fixed
DispInterface types are now properly parsed as CIO (Classes,
Interfaces, Objects).- Compiler defines are now correctly recognized without trailing spaces in
case there are any after the terminating
}. Example: {$DEFINE
MyDefine } (notice the space after MyDefine) is now
treated like {$DEFINE MyDefine} (without the space).
- Improved parsing of property overrides / redeclarations where only the property
name is given (i.e.
property Color;). Where a colon was wrongly
inserted into the docs before, it is now a semicolon.
- Corrected parsing of e-mail addresses with underscore (_) characters.
- Eliminated compiler warnings by removing unused code from
objects.pas
(suggested by Wim van der Vegt).
- Corrected a small typo in the English language strings (thanks to Wim
van der Vegt for spotting this).
- Added
image for published visibility, also included in rjPasDoc.exe
and automatically copied to the output directory. Also added alt
attributes for all images.
License
Since the original PasDoc is Open Source under GPL, rjPasDoc is also released
as Open Source under GPL. Click here to view the GPL.
All changes to the original PasDoc sources are copyright Ralf Junker 2001.
Usage
Type rjPasDoc -? to see the new syntax. With Version 0.7
I have changed it to be easier to parse and to be more compatible to 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 compile the program, run Delphi, goto the rjPasDoc Source directory and
open the rjPasDoc.dpr project file. Then compile. The executable
file should be placed in the source directory.
To test rjPasDoc.exe creating Html output, run CreateHelp.bat.
This will run rjPasDoc 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 documentation looks
a bit odd at times. However, you get an idea.
To
create a HtmlHelp project, run CreateHtmlHelp.bat. Again,
it will run rjPasDoc on its own sources and create both the Html files and the
HtmlHelp project files in the Help directory. rjPasDoc 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 rjPasDoc does not find the MS HtmlHelp compiler, you must manally compile
the HtmlHelp project. Run the HtmlHelp Workshop, go to the rjPasDoc Help directory
and open Help.hpp. Then click 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 rjPasDoc
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, rjPasDoc 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:
| Line |
File HhcContents.txt |
1
2
3
4
5
6
7 |
Introduction=
Read me first=..\ReadMe.htm
License=..\License.txt
=@Legend
AllUnits=@Units
=@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 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 rjPasDoc 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
Version 0.6.22 — released 30. June 2001
New Features
- The default html-image files (
)
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.
- For better readability, the names of functions, procedures and methods now
appear in bold font.
- rjPasDoc now issues a warning in case two different unit files have the
same unit name, i.e.
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.
Bugs Fixed
- Improved parser: Now rjPasDoc correctly recognizes forward class declarations
(
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.- Corrected expansion of
@Created() and @LastMod().
- Fixed a bug which caused
@@ (literal @) to report a warning.
Version 0.6.21 — released 21. June 2001
I have corrected some bugs of the original version (and probably introduced
some new ones), fixed some of the functionality and added a few new features:
- Delphi compatibility: Included objects.pas from FreePascal sources.
- Improved link generation.
- Proper recognition of "reintroduce".
- All overloaded functions are now all listed, not just the first one.
- Duplicate class names no longer overwrite their corresponding HTML-files.
- Improved sorting of overviews.
- Class hierarchy.
- Removed conversion of Html markup characters '<', '>', '&' and
'"'. This allows to include HTML markup into the descriptions. To display
these characters, precede them by an @, i.e. @<, @>, @&, @".
- Reintegrated item exclusion (
@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.- Image support to indicate method visibility (
).
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.
Limitations
LaTeX output is untested. Due to modifications of the main generator engine,
I don't expect it will work. Since I do not use LaTeX at all, I will probably
remove it from the program some time.
Open Issues
rjPasDoc sometimes crashes with an EAccessViolation when running on many and
large source files. I have not yet traced its cause, but I expect it to be a
very tedious search. On small projects, however, it works 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 would improve HTML layout a lot, making it look more like the Delphi
Help with class properties and methods in a frame on the left and their descriptions
on the right hand frame.
Improved parsing for records is also needed. The 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.
Concluding
rjPasDoc does it job, so have fun with it. I hope you will be able to use it
for something useful. If you like, let me know that you are using rjPasDoc and
I will add your URL to the users section of my homepage.
If you have any opinion on rjPasDoc or want to participate in its development,
please e-mail me. I will be glad
to receive feedback, suggestions, bug-fixes and new features.