With Jeff Garland's Doxygen XML test data, I've started to build a Doxygen
XML->BoostBook translator. The XSL stylesheets are in the sandbox, in the
directory libs/documentation/boostbook-xsl/doxygen. There are two
stylesheets:
collect.xsl: takes index.xml from Doxygen's XML and outputs one big XML
document containing all of Doxygen's output. This is necessary because
Doxygen scatters the data across many XML files and we need cross-reference
capability. To use collect.xsl, copy it to a Doxygen XML output directory and
run something like:
xsltproc collect.xsl index.xml > doxygen-all.xml
doxygen2boostbook.xsl: takes the Doxygen XML output as one big file and
outputs another big XML file with the Doxygen output converted to BoostBook.
Usage is something like:
xsltproc doxygen2boostbook.xsl doxygen-all.xml > reference.xml
Don't think everything will work yet, of course. Doxygen's XML output omits a
great deal of structural information that is essential in BoostBook (and in
C++). For instance, a class might be given the compound name
"boost::date_time::date". However, Doxygen won't tell us whether this is:
namespace boost { namespace date_time { class date; } }
or
namespace boost { class date_time { class date; }; }
or
class boost { class date_time { class date; }; };
In all cases, the three entities in this will be <compoundref> elements and
will be peers. We need to traverse "innerclass" and "innernamespace"
references to rebuild the structure so that we get the properly nested
elements:
<namespace name="boost">
<namespace name="date_time">
<class name="date">
<!-- ... -->
</class>
</namespace>
</namespace>
(Interestingly, this was one of the complains about Doxygen's output: that it
puts nested classes at the same level as their logical enclosing classes)
The situation is worse for files: they only tell you what namespaces are used
in the file, not what other entities are in the file. For classes, structs,
and unions, we have a way out with the <includes> element, which tells us
what header file to include to get that entity (we can compare the header
name against the header file for which we're generating BoostBook).
Unfortunately, namespace-level typedefs, functions, and enumerations don't
have the <includes> element, so I'll need to find a better way.
I'd rather not post the resulting HTML until I get a little further. If you'd
like to try it out, you'll want Doxygen 1.2.18: 1.2.17 generates bad XML as
does 1.3-rc2 and the current CVS.
Doug
-------------------------------------------------------
This SF.NET email is sponsored by:
SourceForge Enterprise Edition + IBM + LinuxWorld = Something 2 See!
http://www.vasoftware.com
_______________________________________________
Boost-docs mailing list
[EMAIL PROTECTED]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
