(summary) c++ api help: extraction tools
From Doxygen we then use HTML Help Workshop to convert the html filesthrough the command prompt to a chm. We weren't able to find any way to
convert the files to a chm through the command prompt using RoboHelp.
I've set up loads of groups for each specific module which builds a good
table of contents.
Hope this helps. If you have any further questions, let me know.
Thanks,
Katherine
<katherinet -at- csl -dot- com>
---
Hi Carol,
I concur with Megan about using tools to document code.
I'm using Doxygen at my company, as well. I'm really impressed with what it
does, particularly in the light of the alternative -- doing it by hand.
I'd be happy to share insight about using Doxygen.
I have to admit that your deliverables can be improved if you have a
programmer on your staff who can devote a week or two to writing scripts for
tweaking the output.
For example, part of our code pool exposes source code, while part only
exposes the function calls. I have to run Doxygen multiple times, meaning
multiple mini-HTML systems. Moreover, the theory of operation and usage is
written in FrameMaker and exported using Mif2Go, yet another mini-HTML
system.
There are many ways to wrap these into what looks like a comprehensive help
system. Both Doxygen and Mif2Go allow you to enter information such as
headers and footers when topics are generated. It wouldn't be too difficult
to have these point to some manually generated main pages to pull everything
together.
I will say that the route I chose was to do some Perl script programming
myself. I have Doxygen and Mif2Go insert HTML comments (special tags) that
my Perl scripts recognize. Once the HTML files are generated, I run my
scripts on them to swap out the information between the tags with what I
want. This way, if my co-workers don't like the navigation I created, my
CSS, the copyright notice at the bottom of each topic, etc., I can swap
these out for the entire system without pain. I can also generate main pages
from what is actually in the system, in addition to fixing relative paths.
I also use Perl to implement some input filters. One of the simple filters
changes the Doxygen @bug tag (which expands into "Bugs and Limitations") to
a new @lim tag (which expands into "Limitations and Caveats"). It isn't a
good idea to deliver any help system that uses the word "Bugs" frequently. A
slightly more complex filter I have turns our scripting language into
something more C++ so that it can be run through Doxygen, too.
Enough technical details for now. More important than this is getting true
buy-off from development. We were lucky in that our coding convention
document was five years old and due for an update. Our engineering director
(who is also my manager) set up a working group to update the conventions. I
was able to participate and get Doxygen related changes implemented for
doing code comments. This was the hardest aspect of the whole coding
convention task and garnered the most resistence. (Surprise, surprise.) But
I got what I wanted (e.g., the use of @ingroup for better chunking of the
material). And slowly but surely, development is getting better commented
source code.
You didn't mention what short notice really means. You'll need some time to
experiment with Doxygen. The output from Doxygen is pretty damn good even if
there are not Doxygen formatted comments in the code. However, once you (get
permission to) start re-formatting or outright adding Doxygen comments to
the code, you'll need time for multiple passes to see what format looks
best, to convert exist comments, to flag non-existent comments for
developments help, and to proof what development wrote.
Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com
_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com
Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East, June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline April 27. http://www.pdfconference.com.
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
Previous by Author:
(summary) c++ api help: tips & resources
Next by Author:
True Technical Writer
Previous by Thread:
(summary) c++ api help: tips & resources
Next by Thread:
Re: Creating Inch & Metric Tutorials
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads