[Doxygen-users] Gift for those single-sourcing or API documentation projects
Brought to you by:
dimitri
From: Glenn M. <gle...@vo...> - 2002-01-23 22:22:36
|
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... |