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

From: Jeff Garland (jeff_at_[hidden])
Date: 2002-11-01 17:49:52

> I used Doxygen to produce HTML (directly) and PDF (through pdftex)
> documentation of the 1.29 version of Boost.Python. It was not a very
> interesting document... Doxygen seems to not acknowledge templates as
> "compounds", so one basically get a list of the files involved in the
> project. Not very useful for Boost, in other words. 

I think generalizing about Boost libraries soley based on Boost.Python 
is quite dangerous.  You might get very different results from other
libraries...

> It is a pitty that the Doxygen group has not put much effort in handling
> templates, since Doxygen is a more supported tool than Synopsis. I think
> the Boost group has to more or less adopt Synopsis to make it viable as
> a documentation generator...

I don't think that is the issue at all.  Someone needs to help
Dimitri with a clear specification of what would be desired. The 
types of things that Dave is working on with Synopsis to hide
implementation classes or tagging meta-programming classes 
can't be produced without someone having a vision of what 
they need.  I don't think that vision is clear even now
so I'm not even sure we know what to ask for improvement 
in yet.

> My goal was to use a "tag- and structure-extractor" such as Doxygen or
> Synopsis to generate either LaTeX or DocBook, and then merge other

Are you looking at Doug's example, because it has many elements
that are not part of standard DocBook?

> documentation in that format, such as the specification, to in the end
> create HTML and PDF output. All this is possible in both Synopsis and
> Doxygen as it seems, although one would need to either use the
> experimental XML output of Doxygen with some DocBook-generating XSLTs,
> and use OpenJade, db2tex+pdftex or FOP to do the DocBook-->PDF and
> pdftex to do the LaTeX-->PDF.

The Doxygen XML output is quite different from the specification 
that Doug is proposing, so I expect the translation scripts to
be non-trivial, but certainly possible.  At some point, however,
it might be easier to write a Doxygen XML output that matches the
Boost specification.  It would certainly be more efficient in
the long run.  This might also encourage the development of 
additional Doxygen features to better support Boost.

Jeff