Re: [boost] Re: Review: Boost Coding Guidelines

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
 >>extraction.
 >
 >I'm currious, whats wrong with a tool such as doxygen?
 >http://www.stack.nl/~dimitri/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.

--Beman