RE: [boost] Re: Reference documentation: one approach

From: Jeff Garland (jeff_at_[hidden])
Date: 2002-11-01 21:50:43

> There seems to be only two viable choices, if we indeed want a
> "tag-and-structure" extracting tool: Synopsis and Doxygen. This choice
> is probably independent on whether we want to use DocBook or TeX as the
> format for the entry point of developers. [even though the route to
> DocBook is easier for Synopsis and the route to TeX easier for Doxygen]

As I said before, we don't really need to choose one extraction tool
or another.  We can use one or both.  I think the point that is being
missed here is that Doug has a proposal on the table, but to my eye 
it looks like mostly an extension of DocBook.  What I see in Doug's
stuff looks like solid XML, but I don't understand how DocBook 
extends so I'm just a little worried that the standard DocBook 
tools will be less useful than we think...

> And, unless someone (Jeff et al.) can come up with some new, positive,
> information regarding Doxygen's handling of templates, this choice will
> not be too hard...

For my purposes, Doxygen will work fine so I'm not planning on 
giving it up now.  (And I have plenty of template code -- not 
meta code, just regular templates see:
http://www.crystalclearsoftware.com/libraries/gdtl/gdtl_ref_guide/classboost_1_1date__time_1_1date.html for example)

And please, if you find bugs with the template handling in a recent 
release of Doxygen be sure to report them.  The developer of Doxygen 
is very responsive and helpful in fixing issues. There are regular
weekly releases for bug fixes and enhancements.  And, I'm certainly 
willing to try Synopsis.  Let me know when I can download an RPM for 
Linux and an exe installer for windows.  

Jeff