TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:C++ documentation tools: Autoduck versus George From:Lee Bumgarner <lee -dot- bumgarner -at- VIRTUS -dot- COM> Date:Thu, 10 Oct 1996 14:56:31 -0400
Techwhirlers:
When I last decloaked on this list, I was requesting information about
single-sourcing documents. This request is in a similar vein.
We will be documenting our C++ libraries for internal use and for external
customers very soon and are looking for tools that can take a (or multiple)
C++ header file(s), extract code and comments, and create html pages. We
have looked at Autoduck, which Microsoft owns and freely distributes, and
K2, which owns and distributes (at a cost, I think) George.
After much effort and trial and error, I have been able to get Autoduck to
extract C++ code and comments, somewhat successfully. To extract code and
comments using Autoduck, you insert tags and flags throughout individual
elements that you want extracted from the header file. To get an html page
coded to match one's html style, you have to add to an existing
html-tagging file or create your own and that file adds html tags during
the build process. The product is unsupported and has some documentation,
but from my experience, the specifics of documentation sometimes don't
match the behavior exhibited by the already- tagged sample files I used as
examples for tagging our C++ files.
After having a go at Autoduck, I am now getting ready to test George. From
what I understand about George (talking to their reps. and reading the
documentation on their web site and in their installation package), you
don' t need to insert tags in the documentation. Rather, you create an
extraction/html-coding file that takes care of both automagically during
the build process (or you can pay K2 to create this file for you).
Has anyone used these tools before? What were your experiences? Which tool
worked best for you? What are the relative merits of either? Which do you
recommend? Are there other methods that you have tried? Did you experience
success or failure? Please email me off the list and I will compile the
answers.
