Contents 
 Index 
 "TP Tools" 
 < Previous 
 Next > 

TechPubs Tools

v2-00-0

Welcome to the online documentation for “Technical Publications Tools,” or TPT.

TPT are Perl programs, UNIX shell scripts, and master template files (HTML) used for creating a comprehensive HTML system from various mini-HTML systems that were generated from Mif2Go or Doxygen.

History of the TechPubs Tools

The TechPubs Tools grew out of a need at Voyant Technologies, Inc. to document our Application Programming Interfaces (API). Off-the-shelf tools could only take us so far. The TechPubs Tools were developed to bridge the gab between where those tools left off and where we wanted to be.

The first version of our API manual was created using FrameMaker. Unfortunately, it was a manual process to keep the API documentation in sync with the code. Doxygen offered the promise of extracting the exact code syntax and specially flagged comments directly from the source code whenever needed. It creates a mini-HTML documentation system for the code in a project. (JavaDoc is a similar tool, but its inclusion is beyond the scope of this documentation.)

After getting buy-off from our Software Development organization, we migrated most of the API reference material from the FrameMaker documents into appropriately marked comments in the source code. Doxygen was able to get us 70% of the way towards reliable API reference documentation. Where Doxygen came up short:

Mif2Go (from Omsys) is an inexpensive off-the-shelf tool that reliably exports from FrameMaker into a variety of formats, including HTML. It, too, creates a mini-HTML documentation system. (WebWorks Publisher is a similar tool, but its inclusion is beyond the scope of this documentation.)

Table of Contents Java Applet is a really flexible and inexpensive off-the-shelf tool which allows you to create a TOC with expanding/collapsing icons. One of its more powerful features is that it can used nested TOC scripts. In this manner, a larger book can be created from smaller books, and the master TOC can be created from smaller TOCs. The net effect is that you can do partial-updates of the documentation suite. The perl tools support generation of the TOC script files and including them into a master TOC.

The challenge for Voyant's Technical Publication Department was to wrap all of these mini-HTML systems into one big HTML system.

The TechPubs Tools (TPT) wraps around any number of mini-HTML systems and creates a comprehensive HTML system complete with table of contents and an auto-generated index/concordance. TPT consists of Perl programs, UNIX shell scripts, and master template files (HTML).

Disclaimer

The documentation for the TechPubs Tools (Perl programs and UNIX shell scripts) was created using these same tools ("eating our own dog food") even though Doxygen is designed for C/C++. An input filter to Doxygen was created which changes those files to look like C code. Even with its imperfections, we demonstrate to a small degree what the TechPubs Tools can do.

In addition, it should be noted that:

You are expected to make any and all modifications to get these to work in your environment.

Open new window to www.voyanttech.com.



 "TP Tools" 
 < Previous 
 Next > 



Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003

TP Tools v2-00-0a

# tp-tools-01