manual.html

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

    <p>The generators define serveral <b>options</b>. 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
       <a href="options.html">their options</a> are available in all
       generators, some are specific to a generator.</p>

    <p>The texts used in the documentation can be localized. In the GUI the
       button <b>Localization</b> 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 "<code>-L</code>"
       when starting the program.</p>

       

    <h3><a name="FormatHTML">HTML</a></h3>

    <p>If the documentation is generated in the format <b>HTML</b> (Hypertext
       Mark-Up Language) a lot of HTML-files will be created in the given
       directory. The index file is named <code>index.html</code>. This is
       obviously the simplest format to use, HTML is directly generated, no
       further processing is necessary, although with the introduction of the
       <a href="#FormatPDF">PDF generator</a> 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 (<code>DelphiDoc.css</code>).</p>

    <p>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=...):<br>
       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<br>
       and some others.</p>



    <h3><a name="FormatHTMLHelp">Windows HTML Help</a></h3>

    <p>The <i>new</i> Windows help format with the file extension
       <code>.chm</code> is a compilation of HTML files, what exactly
       <code>chm</code> 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.<br>
       I personally don't like the new format, it's somehow &quot;laggy&quot;,
       and even Delphi uses the old <code>.hlp</code> 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.</p>

    <p>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
       <a href="http://go.microsoft.com/fwlink/?LinkId=14188">downloaded as
       a <code>htmlhelp.exe</code></a> free of charge from Microsoft. And may
       also be distributed in several SDKs. If it is installed and was started
       once the created file <code>DelphiDoc.hhp</code> will be associated and
       can directly be opened.<br>
       The compiling can be started by the third button or through the menu
       &quot;File | Compile...&quot;. The file <code>DelphiDoc.chm</code> 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.</p>







    <h3><a name="FormatWinHelp">Windows Help Files</a></h3>

    <p>If the documentation is generated in the format <b>WinHelp</b> 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.</p>

    <p>The Microsoft Help Workshop can be
       <a href="ftp://ftp.microsoft.com/softlib/mslfiles/hcwsetup.exe">downloaded</a>
       free of charge from Microsoft, but is also on the Delphi-CD (or other
       SDKs) included, and may have been installed in the directory
       <code>C:\Program Files\Borland\Delphi\Help\Tools</code>. If it is
       installed and was started once the created file
       <code>DelphiDoc.hpj</code> will be associated and can directly be
       opened.<br>
       The compiling can be started by <code>Save and Compile</code> or just by
       commands to compile. The file <code>DelphiDoc.hlp</code> 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.<p>

    <p>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 <i>OpenHelp</i>
       <code>C:\Program Files\Borland\Delphi\Bin\oh.exe</code> and then with
       it open the project
       <code>C:\Program Files\Borland\Delphi\Help\delphi.ohp</code>.<br>
       After the activation of the tab <i>Index</i> 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
       <em>DelphiDoc</em> itself is too big to be integrated in the index, but
       you can still integrate it in the tab <i>Link</i> and accessing the help
       via F1 will still work (else the index tab will be completly empty, not
       a good thing).<br>
       <i>Attention</i>: Before integrating the help file it should be renamed
       or the automatical start of the generated help file in
       <em>DelphiDoc</em> 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.</p>




    <h3><a name="FormatLaTeX">L<small><sup>A</sup></small>T<small><sub>E</sub></small>X</a></h3>


    <p>If the documentation is generated in the format
       <b>L<small><sup>A</sup></small>T<small><sub>E</sub></small>X</b> several
       .tex-files are created. T<small><sub>E</sub></small>X 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
       (<a href="http://www.adobe.com/products/acrobat/adobepdf.html">Portable
       Document Format</a> by <a href="http://www.adobe.com/">Adobe</a>) that
       can be viewed on many platforms portable for instance with Adobe's
       <a href="http://www.adobe.com/products/acrobat/readermain.html">Acrobat
       Reader</a>.</p>

    <p>T<small><sub>E</sub></small>X (the Greek letters Tau, epsilon and Chi,
       i.e. correctly: "&Tau;&epsilon;&Chi;")
       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,
       <a href="http://www-cs-faculty.stanford.edu/~knuth/">Donald E.
       Knuth</a>, 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
       T<small><sub>E</sub></small>X provides an interpreter, several (macro)
       packages expanding the capabilites to a more comfortable level are
       available. The most spread package is
       <b>L<small><sup>A</sup></small>T<small><sub>E</sub></small>X</b> by
       Leslie Lamport. This package is also used for the generated
       documentation.</p>

    <p>To generate these formats the
       L<small><sup>A</sup></small>T<small><sub>E</sub></small>X-system is
       needed. You can download it free of charge on the web, take a look at
       the following pages: the
       <a href="http://www.latex-project.org/">Latex-Project</a>, the (a)
       <a href="http://www.tug.org/">TeX Users Group</a> and the
       <a href="http://www.ctan.org/">the Comprehensive TeX Archive
       Network</a>.<br>
       Just execute latex with the generated main file
       <code>DelphiDoc.tex</code>. Several macros/commands are defined in it,
       you may want or need to change them.</p>

    <p>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
       L<small><sup>A</sup></small>T<small><sub>E</sub></small>X 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.</p>





    <h3><a name="FormatPDF">PDF - Portable Document Format</a></h3>

    <p>If the documentation is generated in the format
       <b>PDF</b> one single (and big) PDF file is created.<br>
       PDF means <i>Portable Document Format</i>; it is an open format
       copyrighted by <a href="http://www.adobe.com/">Adobe</a>. Read more
       <a href="http://www.adobe.com/products/acrobat/adobepdf.html">about this
       format</a> on their website. PDF files can be viewed on several
       platforms with different viewers. The best known is of course Adobe's
       <a href="http://www.adobe.com/products/reader/">Acrobat Reader</a>. 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.</p>
<!--
    <p>I did use
       <b><a href="http://www.est.hi-ho.ne.jp/takeshi_kanno/powerpdf/index.html">PowerPDF</a></b>
       by Takeshi Kanno to create the PDF file. This library is published under
       the <a href="http://www.gnu.org/copyleft/lesser.html">LGPL</a>. The
       current version does actually not use this library! But as I said I used
       it to become acquainted with PDF, so I made some small changes
       (I don't know if they are good, but they work for me) and added a class
       for name trees. You can download the part of the library I used in
       <a href="PowerPdf.rar">another Rar file</a>.</p>

    <p>&nbsp;</p>
-->



    <h3><a name="FormatUMLXMIExport">XMI - XML Metadata Interchange - UML
         export</a></h3>

    <p><a href="http://www.omg.org/technology/documents/formal/xmi.htm">XMI</a>
       is a format based on <a href="http://www.w3.org/XML/">XML</a> that can
       be used to exchange <a href="http://www.uml.org/">UML</a> data between
       UML design programs.<br>
       The created XMI files can be imported in at least
       <a href="http://argouml.tigris.org/">ArgoUML</a>, 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.<br>
       To convert XML files another powerful format,
       <a href="http://www.w3.org/Style/XSL/">XSL/XSLT</a>, 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
       <a href="http://sourceforge.net/projects/essmodel/">ESS Model</a>).


  </body>
</html>