[Doxygen-users] Gift for those single-sourcing or API documentation projects

[Glenn M. <gle...@vo...>]

Howdy,

I just uploaded a file (tp_tools.zip 1.8 MB) to the HATT files area that
may be of interest to those creating large single-sourcing projects or
API documentation.

(If you're not part of HATT and are interested, let me know and I'll
send it to you directly. Or you can tell me/assist me in posting this
file to a location where others can access it.)

I do have my company's permission to open-source these tools.

Comments and suggestions are appreciated. However, I must be honest that
I have enough on my plate and am trying to get these out so that I can
move on to other more pressing projects at work. There's no guarantees
that I'll do anything further on the tools themselves.=20

Unzip and click on _start_here.html to see what is included. A short
summary is below.

Have fun.

Glenn Maxey
Technical Writer
Voyant Technologies, Inc.
1765 West 121st Avenue
Westminster, CO 80234-2301
Tel. +1 303.223.5164
Fax. +1 303.223.5275
gle...@vo...



=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

The TechPubs Tools (TPT) pick up where other tools (Mif2Go/WWP,
Doxygen/JavaDoc) leave off. They are intended for both large
single-sourcing applications and/or API documentation.=20

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).

Although designed for UNIX, the shell scripts can be easily altered to
batch files. Perl is supported on NT.

The tp_tools.zip file (1.8 MB) contains everything you need plus
complete documentation (using these tools on themselves).


=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

The TechPubs Tools grew out of a need at Voyant Technologies, Inc. to
document our Application Programming Interface (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.=20

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.=20

Doxygen is an off-the-shelf, open-source program that extracts the exact
code syntax and specially flagged comments directly from the source
code. It creates a mini-HTML documentation system for the code in a
project. (JavaDoc is a similar tool.)

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 our API reference
documentation.=20

Where Doxygen came up short:=20

- Our API consists of multiple projects, which means multiple mini-HTML
systems.=20

- Portions of the API documentation, such as overview and how-to
sections, still needed to be maintained and published from FrameMaker.

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.)

The challenge for Voyant's Technical Publication Department was to wrap
all of these mini-HTML systems into one big HTML system. Hence the
home-grown tools that Voyant has given their permission for me to
open-source.


Glenn Maxey
Technical Writer
Voyant Technologies, Inc.
1765 West 121st Avenue
Westminster, CO 80234-2301
Tel. +1 303.223.5164
Fax. +1 303.223.5275
gle...@vo...