How to generate HTML Help with Doc-O-Matic Express

XMLDoc in-source documentation style is becoming popular among Delphi open-source projects. There is also very good Delphi Documentation Guidelines document which describes what XML tags should be used for in-source XMLDoc-style documenting comments and how to use these tags. Unfortunately currently there are no documentation generators for Delphi in-source comments that fully support these guidelines.
So we must limit ourselves to the set of XML tags supported by the already available documentation generators. In fact I have found the only documentation generator that supports XMLDoc-style for Delphi in-source comments – that is Doc-O-Matic. There is also free (for non-commercial use) edition – Doc-O-Matic Express that can be downloaded from the official site. Using Doc-O-Matic Express one can generate documentation in several help formats; in this article we will see how to generate compiled html help (*.chm file).
For the demonstration purposes I downloaded Collections package by Alex Ciobanu; the project recently started to use XMLDoc-style in-source documenting comments.

Here is step-by-step instruction how to generate compiled html help using Doc-O-Matic Express 7.0:
Create the following directory structure:
C:\Work\Collections
C:\Work\Collections\Source
C:\Work\Collections\DoM700

Copy the “Collections” package files to the ‘Source’ subdirectory.

Run the Doc-O-Matic Express Configuration utility. Create a new Doc-O-Matic project and add all *.pas files from Source subdirectory to the project:

On the “General Options” panel set the project’s title (and other information if you like):

On the “Comment Finding” panel check “Use triple comments only” checkbox:

Now switch to HTML Help Tab; on the “HTML Help” panel set the name of *.chm file to be generated. The path to help compiler should already be set if help compiler is installed in your system; most probable it is installed already; if not download and install “HTML Help Workshop” from Microsoft – it is free:


On the “Help Project Option” check “Create binary TOC” checkbox:


Save the DoM project in DoM700 subdirectory under the name “Collections” and exit Doc-O-Matic Express Configuration utility.

We have created DoM project with necessary settings. Now we should use command-line documentation generator to create compiled HTML help file. To perform the compilation in a single click create a batch file collections.bat with a single text line like this:

“c:\Program Files\Doc-O-Matic 7 Express\domexpress.exe” -all c:\Work\Collections\DoM700\Collections.dox-express

The -all switch means to compile all configurations; we actually need only HTML Help configuration, but I have not found how to compile it alone, so I compile them all.

After executing collections.bat we obtain a very attractive help file Collections.chm; here is a screenshot:

Advertisements

5 thoughts on “How to generate HTML Help with Doc-O-Matic Express

  1. Thanks for the guide!

    Actually, We are working on a professional XML Documentation Generator. : ) It will be a lightweight, fast solution to help you generate professional API Documentation References.

  2. Thank you! I was just thinking to pick up DoM Express to generate myself (Collections) some documentation and you just showed step-by step how 🙂

  3. This tool does not handle C++ forward class declarations…

    They are so long on the market and there are still so basic problems with this software.

    Have you tried doxygen (plus pas2doc)?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s