Using the XMLDoc tool for API documentation and HelpInsight with Delphi 2005

By: Aleatha Parker

Abstract: How to use XMLDoc to quickly and easily document your software and generate HelpInsight for your components

    Introduction to XMLDoc

XMLDoc is a demonstration version of a highly configurable documentation system based on the same documentation system that Delphi uses. Like many other documentation systems, it uses compiler output and in-code comments to generate documentation. However, XMLDoc takes documentation generation a little further, by abstracting out the structure of documentation from the content. XMLDoc creates intermediary comment files for you, which are then merged with structural information about your code from the compiler. This allows you to either document your Delphi in code, or maintain all your help content separately from the code, without the overhead of updating documentation every time the structure changes.

The XMLDoc tool reads the xml file generated by the Delphi compiler's --doc switch. This file contains structural information about your code, and comments that use the devnote format. Source code comments and structural information are separated out into different files, and then merged together to create the final output. The default output for XMLDoc is Microsoft Help 2.0 format, the same format that Delphi 2005 uses. For full functionality, the files can be compiled into the Microsoft Help 2.0 compiled help format using the Borland HelpKit and the Visual Studio Help Integration Kit, and then integrated into Delphi 2005, or any other Help 2.0 system. These files can also be used in a standard HTML help browser, however, Help 2.0 links will not function. To create a standard HTML help system, you can customize the XMLDoc tool to output HTML compliant links.

    Setting up XMLDoc

    Requirements

The XMLDoc tool requires a number of supporting tools:

    Setup

To prepare to use the XMLDoc tool, add the directory containing the tool to your path. In the default installation, this path is C:Program Files/Borland/BDS/3.0/Demos/XMLDoc. Consult your operating system documentation for instructions on changing your path environment variable.

You should also add the directories containing Saxon and Python to your path if they are not already there.

    Using XMLDoc

There are three major tasks you need to perform to produce XML documentation from source code comments:

  1. Use the Delphi compiler to generate the XML file with source code comments
  2. Use the XMLDoc tool to produce HTML files in the format used by Microsoft Help 2.0
  3. Use the Visual Studio Help Integration Kit and the Borland HelpKit to compile and install the new help topics

Each of these steps is broken into subtasks below.

    Using the Delphi compiler to generate the XML file with source code comments

  1. Write comments describing your classes, types, and members in the declaration section of your code.

    For your comments to appear in the output, you must use one of the special XML documentation comment marker styles:

    /// This comment goes until the end of the line
    {! This is also a comment}
    {*! and this too *}
    

    The relevant documentation should appear directly above the declaration of the documented type or member. For example:

    /// The TFooBar class includes an extremely useful method.
    type TFooBar = class(System.Windows.Forms.Forms);
      public
    	/// The function FooBar is extremely useful.
    	function FooBar: Integer;
    end;
    

    Note:The compiler does not output XML comments for private members.

  2. Enable the --doc switch in the IDE, by clicking the checkbox for the Generate XML documentation option on the Projectmenu pathOptions...menu pathCompiler page.
  3. Compile and build your project.

    Using the XMLDoc tool to produce HTML files in the format used by Microsoft Help 2.0

  1. Using any text editor or an XML editor, customize the variables in vars.xml. This file is located in the xmldoc/xml subdirectory of the folder where the xmldoc.py file is located. vars.xml contains text strings that are inserted into the output HTML in various places. You will certainly want to change the text in the <copyrightMessage> node, and you may wish to customize other text strings as well.
  2. Open a command prompt.
  3. Type xmldoc.py <MyProjectDir>, where <MyProjectDir> is the project directory for the project you are documenting. By default this will be something like xmldoc.py "C:Documents and Settings/UserName/My Documents/Borland Studio Projects/Project1". Don't forget the quotes if your project directory name has spaces in it.
  4. Go to the newly created doc subdirectory of your project directory, and examine the output HTML files in doc/final.

    Using the Visual Studio Help Integration Kit and the Borland HelpKit to compile and install the new help topics

  1. Compile into H20 files (.HxS and .HxI files) using the Visual Studio Help Integration Kit (VSHIK). Though you can view your HTML files as-is, this step is required to have your HTML files function as Help 2.0 files. The VSHIK is available as a free download from Microsoft. The use of that tool is beyond the scope of this document; see the documentation from Microsoft and from third parties like The Helpware Group for instructions.
  2. Create an installer to integrate your help files into the Delphi 2005 IDE using the Borland HelpKit. This step is required if you wish to redistribute your help files and have them integrate with the Delphi 2005 IDE. The HelpKit is available as a free download on the Borland Developer Network website. Follow the instructions provided with the HelpKit.

    Advanced usage and customization

The XMLDoc tool is very flexible. You can use source files outside of your code if desired. Also, by customizing stylesheets, you can produce documentation with whatever appearance or structure you desire.

    Maintaining content outside of code

It can be desirable to divide the tasks of development and documentation. The XMLDoc tool automatically produces template files that can be altered by a technical writer, independently of the source code. These files are written to the doc/templates directory under your project. Content files, which include the comments from source code, are written to the doc/content directory. To develop content independent of source code comments:

  1. Copy the content files from the content directory and any desired template files from the templates directory into a different directory, which we represent as <MyContentDir>.
  2. Modify these content files as desired.
  3. Execute xmldoc.py <MyProjectDir> <MyContentDir> (replacing the directories with the names of your project and content file directories) to use these content files rather than the source code comments directly.

    Customizing look-and-feel

Modify the cascading stylesheet, bdshelp.css, to give the documentation a custom look-and-feel.

    Customizing structure

Modify the XSLT stylesheets to make more extensive changes to the output format. The XSLT stylesheets, .xsl files, can be customized to make significant structural changes. The most important stylesheet for customization is the h2build.xsl file, located in the APIMerge subdirectory of the XMLDoc demo project. For example, this file can be modified to produce ordinary HTML links instead of Microsoft Help links, if desired. Many other customizations are possible.

    Creating HelpInsight files for your Delphi packages

XMLDoc can also be used to create HelpInsight for your Delphi custom components, so that people using your components can have on the fly tool tip help.

    To install HelpInsight:

  1. Download the HelpInsight tool from Code Central.
  2. Unzip the zip file to xmldoc/xmldoc.

    To create HelpInsight files for your components:

  1. Run the XMLDoc tool to create help files as described above.
  2. On the command line, change directories to xmldoc/xmldoc.
  3. Type HelpInsightGenerator.py <MyProjectDir>, where <MyProjectDir> is the directory where your project and compiled delphi package are located.
    A directory called helpinsight is created in the same directory as HelpInsightGenerator.py. This directory contains XML files with the same name as the package file they were created from.
  4. For HelpInsight to work, the XML file must be deployed to the same directory as the package file.

Server Response from: ETNASC01