Project-Page: http://sourceforge.net/projects/delphidoc/
Homepage: http://delphidoc.sourceforge.net/
Project-Page: http://sourceforge.net/projects/delphidoc/
This is a very short description what to do to generate some documentation. Please use the F1 key to access the corresponding help.
When the program starts the welcome register is shown, with the tree view on left another one of more then two dozen registers can be shown. As can be seen from the layout of the tree view the program consists roughly of two parts. With the first part under the main entry "Acquire Parsed Data" some source code files can be parsed, on which in the second part below "Generate Documentation" exactly this can be done.
To parse new source files the register "Select Files" should be shown
and the source files be added to its list. This is simplest done by
dragging the project file, the .dpr-file, from the explorer
in the form and checking the new entry. After that is done on the
register "Parse" the button with the same caption can be used to parse
the source code. If conditional compiling is used within the project the
version of Delphi to emulate while parsing the source code can be
selected in the register "Compiler Options" before the code is
parsed.
Now the format of the documentation to be generated can be selected on
the register "Select Generator". The generators and all other objects
that are used to create the documentation have several (lots of)
options to tweak the gathering of information
and the result. The button "By Category" will show a dialog to edit the
options of the generator.
Then the register "Generate" should be selected. Here the directory to
generate the documentation to can be entered, it should be
empty because all files in it will be
overwritten when they are part of the new documentation
and already exist. The directory will be created if it does not exist.
All options of all objects used to generate the documentation can be
edited again with the button "Edit all Options by Category". And finally
the generation of the documentation can be started by pressing the
button "Generate Documentation".
To generate documentation as a help on a GUI there are three steps to do: Generating a log file, writing the documentation and generating the final documentation in the target format.
In order to generate the log file the unit UFormHelp in
the directory GUI in the source tree has to be included in the
application. The unit will automatically show a window to generate a
log file of all visible components on a form of the application and
save a screen shot of it. The currently active window should
automatically be selected, if there is a page control on the page a
prefix of the currently active page should also automatically be set.
To use the window with modal dialogs there is also a button to re-show
the window after a few seconds after the modal window has been shown,
so it can still be accessed.
When the generation of the log file is started it is generated in the
specified directory. The name of the file is assembled from the name
of the form, the prefix and the extension .log. The
screen shot is saved in a file with the same name but with the
extension .bmp.
The documentation of the GUI is written in simple text files, just
like additional user documentation. It has to be in a file with the
same name as the log file but with the extension .txt.
The documentation itself is in ~GUI sections similar to
the additional user documentation's ~Page sections.
Other files may be included in ~GUIInclude sections,
similar to the ~[userDoc ] inline command. Aliases to let
several components use the same documentation can be defined in
~GUIAlias sections, additional regions in the screen shot
may be defined as links manually in ~GUIManual sections.
Links to the documentation topics can be generated within this
documentation or the additonal user documentation with the
~[linkGUI ] inline command similar to the
~[linkPage ] command of the user documentation.
Please see the documentation on these sections
and the inline command. Also notice the three special topics for the
~GUI sections.
In order to generate the documentation in the final format with DelphiDoc the appropriate generator has to be chosen and the log files of the GUIs to generate the documentation about be added in the register "GUI Help Log Files". Then the button "Generate Help on GUI" on the next register can be used.
As always you change some options of the generator before generating
the documentation, localize some used texts or define some files with
additional user documentation to include. There are four options
specific to this kind of documentation, first two for all generators
(in TJaddCommentData or TFormatCommentDoc),
the option UseAutoAliases to specify whether the
automatically generated aliases (from labels to the control they
describe (linked via their FocusControl property)) should
be used and the other GUIHelpUseTopicAsLinkText to
specify the alternative texts for the links inside the screen shot for
the HTML formats, if it is enabled the title of its comment will be
used instead of the name of the component.
The two other options are specific to the PDF generator, more
precisely to the screen shot in this format:
InterpolateGUIHelpImages and
MaxGUIHelpImageScale. Take a look at
the descriptions of all options.
The Windows Help file and the HTML Help file also use the
HelpContext property of the components and links the help
topics to them, so you can use the generated help file directly for
your application simply by specifying it in the project options.
Of course it would also be good to rename it to a fitting name for
your application (i.e. the same name as the executable with the
extension .hlp or .chm). The number of the
help context can also be defined manually in the comments with the
inline command ~[HelpContext <number>].
There is also a generated documentation for the GUI available. Choose the window you want to read the help about and click on the image at the top on the component you want. On the main window you may, as in the original window, also click on in the tree at the left to change the current page.
This documentation is now also included as a Windows HTML Help file directly with the executable file, so you may simple press F1 in the program as well.
Both, the GUI and the command line version support parameters specified when starting the program. For the command line version these are mandatory. Some of these options only work or only make sense for one of the versions, in that case they'll be ignored by the other version.
The command line parameters have been completely revised in version
1.7.6.395. In most cases old parameters can still be used without much
change needed. The main difference in the concept is that now each
parameter is parsed one after another, each one is treated as a command
that will be executed directly, so parsing of the parameters works
much like a batch file. Previously first a set of parameters
where parsed, and only when the set was completely specified the whole
set was executed. The most obvious change in that regard will probably
be in the GUI version when the -p switch is used to load a
project file. While in the old version the source files were only parsed
when the set was finished (either by loading another file or with the
-a switch), now the files will be parsed directly. This has
also an effect on the order the parameters should be specified, while in
the old version a new set was started with the -p switch
and the options for the set had to be specified after it, now all
options pertaining the parsing have to be specified before the project
file is loaded.
The command line is also now parsed according to
the
rules used by Microsoft, avoiding the buggy ParamStr
and ParamCount functions. Additionally the parameters are
now specified similar to
GNU's
implementation of the
getopt
function defined in POSIX. This means that there is a long option for
each short option, and even some options for which only a long version
exists. Generally, the new long-options are recommend. The short options
are also now all case-sensitive, but they can be merged into a single
parameter like for example:
-pdgFro dd.ddp .\_doc TICWinHelpDoc
AutoLaunchDocumentation=true
Long options can be abbreviated as long as their meaning is not
ambiguous, for instance "--so=FILE" can also be used
instead of "--sourceproject=FILE".
The list of parameters follows. On Windows "/" can also be used instead
of "-" for short options. When loading project files the name "-" can
also be specified in the command line version to load the file from
stdin/Input. "[-]" on a line on
its own (i.e. an initialization section with the name "-") is treated as
the end of the file, in case several files should be read from the
standard input stream of the program.
Additionally to the parameters listed here, the command line version
checks whether the first parameter is "-auto". If this is
not the case it will wait for the user to press the enter key when it
has finished parsing all parameters.
-p option. If not either the .dpr file
with the same name is added to the list of files to be parsed or, if
it does not exist, the directory containing the executable file. Then
the selected files are parsed.$SAVEALL $SAVE -e $EXENAME"
(and others) it's relatively easy to generate documentation for the
current project.-k switch is no longer supported. It is not
necessary anymore as options no longer have to be in sets.--genoption=FileName=FILE.-L is
used it will instead be interpreted as the option
--uselanguage.~[userdoc ].-u" or
"--userdoc".Filter ::= GroupName=([01][01]*|(+|-)number[,number]*|-)-f TFormatCommentDoc=+0,1,2,3,4,5,6,7;TJADDCommentEvaluator=--f option.
-v/--verbose, it has the same meaning,
only that the final list of topics to be verbose about will be
inverted.-a switch is no longer supported. It has been
superseded by the option -A/--generate.-i"
or "--guilogfile".At the moment there are five different formats to choose from: HTML, Windows Help file, HTML Help, LATEX and PDF.
The HTML-Format is the first and thus it is the oldest generator. It was
the simplest format to generate but under Windows perhaps not the most
comfortable to use. So there may be some things, that could be optimized
or better formatted.
The Windows Help Format is really comfortable to use, if it is
integrated in the help of Delphi, so you get help via pressing F1
directly in the IDE.
The HTML Help Format is the new help format in Windows. It is similar to
the old format but raises its limits greatly so it can also be used for
really big projects.
LATEX can be used to
generate documents in many different formats. Created PDFs for example
are linked (like HTML) and easy to use. The makros for these links can
be changed to produce texts usable in printed versions.
PDF files
(Portable
Document Format, copyrighted by
Adobe) look quite similar to the PDF
files generated by the
LATEX files but you
save the compiling with TEX and, well, you
don't have to have TEX installed.
Each generator creates also a few Xfig- (*.fig),
WMF (*.wmf) and SVG-files (*.svg). These show
the relations between files and classes/interfaces.
XFig-Files are vector graphics, their format is textual not binary in
contrast to WMF-files. The format originated from the Unix-world, but
there are programs to view and edit
these files for Windows. WMF-files should be insertable into most
office-programs. SVG - Scalable
Vector Graphics - is a open textual graphic format based on XML, it
is an official W3C standard, most internet browsers should be able to
show them without any problems.
There are also lots of programs
supporting the format, and for the Internet Explorer
plug-ins
are available to enabled also that browser to view SVG images.
The generators define serveral options. Please do use them, they allow the customization of the generated documentation and the parsing of your comments. New options may be added in future versions. Some of their options are available in all generators, some are specific to a generator.
The texts used in the documentation can be localized. In the GUI the
button Localization will open a window to edit them. The last
option can be used to load a file with saved texts, and the one above it
to select a predefined translation. At the moment only "English" (the
default) and "German"/"Deutsch" are available. The file can also be
loaded or the language be selected with the parameter "-L"
when starting the program.
If the documentation is generated in the format HTML (Hypertext
Mark-Up Language) a lot of HTML-files will be created in the given
directory. The index file is named index.html. This is
obviously the simplest format to use, HTML is directly generated, no
further processing is necessary, although with the introduction of the
PDF generator it got a rival.
Only a simple browser is needed. No frames are used, so the simplest
browser will do. Most used tags are really old HTML so every browser
will understand them. CSS is only used once to mark strings red, so the
user may simply alter the CSS file to change this. A lot of HTML files
will be created along with some images (*.gif or *.png) and one
Cascading Style-Sheets file (DelphiDoc.css).
The CSS file contains also a few lines as a comment describing how to
create other styles. The following classes are used within the generated
HTML-files (HTML-attribute class=...):
abstract, additional, author, called, calls, class, classcomment,
classtree, classtreefiles, classtreeunknown, example, examples,
exception, exceptions, file, filecomment, filelist, filelistfiles,
funclist, globals, headerlinks, ident, idents, identslist, identsscope,
implements, included, includedlist, independentunits, index, longfunc,
member, methodlist, overridden, overrides, param, params, project,
result, see, special, string, unit, used, usedfilessub, usingfiles,
usingfilessub, version
and some others.
The new Windows help format with the file extension
.chm is a compilation of HTML files, what exactly
chm means is hard do tell, Compiled HTML Help or
Compressed Help Module(s) or something inbetween or completely
different. Well, anyway, as the names suggests its mainly an archive of
lots of HTML and additional files like images.
I personally don't like the new format, it's somehow "laggy",
and even Delphi uses the old .hlp format. And please be
aware that the user who wants to view the generated help files needs to
have the HTML Help viewer and Internet Explorer installed. Of course he
will in most cases, but if you still target old Windows 95 machines they
might have a problem. Also Mircosoft starts to generate HTML Help
version 2 for Longhorn and their new programs, but there is no
stand-alone compiler or even viewer for that format, it is only included
in some of their newer programs (mostly .NET based). This is also the
format Delphi .NET uses for its help (probably because Microsoft
provides the .NET documentation in this format). At least this is what I
gathered. And anyway, CHM is already obsolete again, in Vista MAML seems
to be the new standard.
Like the generation of the old Windows Help files here only the source
files are generated and Microsoft's compiler is used to generate the
final help file. The HTML Help Workshop can be
downloaded as
a htmlhelp.exe free of charge from Microsoft. And may
also be distributed in several SDKs. If it is installed and was started
once the created file DelphiDoc.hhp will be associated and
can directly be opened.
The compiling can be started by the third button or through the menu
"File | Compile...". The file DelphiDoc.chm will
be created. This can be done automatically but has to be enabled in the
options of the generator. The path to the help compiler may be needed to
be given, if not it will be searched. For this purpose it is checked
whether the file of the help project is associated or if it can be found
in the search path.
If the documentation is generated in the format WinHelp a help project (ini file format) and a RTF-file is created that can be compiled to a Windows help file by the Microsoft help compiler (included in the Microsoft Help Workshop). Besides the RTF file, a file with the content (.cnt) and the project file, defining how to compile the RTF file to a help file, and some bitmap (.bmp) files containing some small icons to mark identifiers are created.
The Microsoft Help Workshop can be
downloaded
free of charge from Microsoft, but is also on the Delphi-CD (or other
SDKs) included, and may have been installed in the directory
C:\Program Files\Borland\Delphi\Help\Tools. If it is
installed and was started once the created file
DelphiDoc.hpj will be associated and can directly be
opened.
The compiling can be started by Save and Compile or just by
commands to compile. The file DelphiDoc.hlp will be
created. This can be done automatically but has to be enabled in the
options of the generator. The path to the help compiler may be needed to
be given, if not it will be searched. For this purpose it is checked if
it is installed with Delphi, if the file of the help project is
associated or if it can be found in the search path.
The compiled help file can be integrated in the help of Delphi. In the
Delphi IDE chose in the menu "Help" the item "Customize..." or start the
program OpenHelp
C:\Program Files\Borland\Delphi\Bin\oh.exe and then with
it open the project
C:\Program Files\Borland\Delphi\Help\delphi.ohp.
After the activation of the tab Index the compiled help file can
simply be added. After saving the project, help to the documented
identifiers should be accessible in Delphi simply by F1 exactly like for
all other identifiers of Delphi. Now the documentation of
DelphiDoc itself is too big to be integrated in the index, but
you can still integrate it in the tab Link and accessing the help
via F1 will still work (else the index tab will be completly empty, not
a good thing).
Attention: Before integrating the help file it should be renamed
or the automatical start of the generated help file in
DelphiDoc won't work correctly anymore. The integrated help
file will be shown instead of the freshly generated one, nevertheless it
can still be started manually. It seems the help files are cached by the
name of the file or they are searched with search paths, what leads to
problems with files with the same name.
If the documentation is generated in the format LATEX several .tex-files are created. TEX is a typesetting system, that can be used to build the documentation in a lot of different formats. These include PostScript to print it directly and PDF (Portable Document Format by Adobe) that can be viewed on many platforms portable for instance with Adobe's Acrobat Reader.
TEX (the Greek letters Tau, epsilon and Chi, i.e. correctly: "ΤεΧ") documents are interpreted, not just parsed, it is a language on its own, comparable with macro languages. It was developed by one of the gurus of computer science, Donald E. Knuth, especially also for mathematical and scientific articles. As a free and portable system (and software) it is used for printing books etc. but can also be used for instance to produce PDF files. While TEX provides an interpreter, several (macro) packages expanding the capabilites to a more comfortable level are available. The most spread package is LATEX by Leslie Lamport. This package is also used for the generated documentation.
To generate these formats the
LATEX-system is
needed. You can download it free of charge on the web, take a look at
the following pages: the
Latex-Project, the (a)
TeX Users Group and the
the Comprehensive TeX Archive
Network.
Just execute latex with the generated main file
DelphiDoc.tex. Several macros/commands are defined in it,
you may want or need to change them.
This generator has some shortcomings now. Images are not supported, so also documentation cannot be generated as a help on a GUI. This is due I don't know how to use portable graphic formats that can be used in LATEX in general (PDF likes JPEG or PNG, dvi wants eps (Encapsulated PostScript)). Also I don't know how to create links on images or parts of images. If anyone knows, I'd be glad to learn.
If the documentation is generated in the format
PDF one single (and big) PDF file is created.
PDF means Portable Document Format; it is an open format
copyrighted by Adobe. Read more
about this
format on their website. PDF files can be viewed on several
platforms with different viewers. The best known is of course Adobe's
Acrobat Reader. The
used version of PDF is 1.2 (current: 1.6), that is quite
old and it can be read with Acrobat Reader Version 3.x (current: 8)
(at least it should). The old version of the PDF standard was chosen to
allow maximum compatibility with other programs, and the important
features for simple, read-only PDF files were all already defined in
this old standard.
XMI
is a format based on XML that can
be used to exchange UML data between
UML design programs.
The created XMI files can be imported in at least
ArgoUML, a free Java based UML
tool. With XML as an open, standardized and easy to read format it is
also possible to convert it to other formats or extract the information
needed. But be aware that XMI/UML only knows classes, so any not
object-oriented information is lost.
To convert XML files another powerful format,
XSL/XSLT, has been created.
There are a lot of XML libraries out there that can be used to
convert the XMI file with an XSL file. Web browser can also use XSL
files to show XML files, a simple XSL file will be extracted by default,
at least Mozilla can use it to show the XMI file with links etc. (I've
never used XSL before, so the code of the XSL file is not that good nor
fast (DelphiDoc's XMI takes about 2 minutes to render in Mozilla), if
you want an example that looks good, load
ESS Model).
