From: Beman Dawes (bdawes_at_[hidden])
Date: 2001-07-23 10:17:57
At 12:52 PM 7/20/2001, Iain.Hanson_at_[hidden] wrote:
>Author: bdawes (bdawes_at_[hidden]) at unix,mime
>Date: 20/07/01 15:40
>>If we want to put effort into documentation tools, I think DocBook/XML
>>should be the starting point rather than worrying about automatic
>I'm currious, whats wrong with a tool such as doxygen?
DocBook and Doxygen are really two different animals.
DocBook is a heavy-duty solution, with a whole tools industry behind it
(because it is XML based). It can solve difficult documentation problems
like generating output based on multiple user-specified styles and design
formats, all from the same source, and directed to a wide range of physical
output formats. Able to handle large volumes (I think some uses run into
tens of thousands of pages.) One downside is there is a considerable up
front learning curve.
Doxygen is a light-duty solution, with almost no tool support other than
the generator itself. It is, however, easy to get going with. OTOH, most
of the results I've seen give only a brief illusion of documentation rather
than the real thing.
There are also some Literate Programming tools available that fall
somewhere between DocBook and Doxygen. I'm not really familiar with their
pros and cons.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk