[boostbook] Duplicates and free functions
Hello, I'm currently having trouble with the conversion between the XML generated by Doxygen and the Boostbook code generated by doxygen2boostbook.xsl. Some of my files define free functions and types inside a namespace (or at the top level; the problem appears equally). However, when these files are converted to Boostbook and later turned into HTML, I cannot see any of these functions. I can only see those classes that appear in the same file, but nothing else. The problem is because the code is skipping such cases. Additionally, Doxygen seems to be generating duplicate entries for some members, and I don't know why it's happening (a bug?). For example, if you document some #defines in a file, the resulting Boostbook will contain two entries for each #define, which is incorrect because 1) there are duplicate IDs, 2) the rendered document contains two entries. (This also happens with the free functions mentioned above, once they are fixed.) At last, Doxygen is also generating sectiondef's elements with an empty kind, which are also unhandled by the current code. I'm using Doxygen 1.5.1 under Mac OS X and Boost from CVS HEAD. The problems can easily be seen when building the Boost.Process' documentation that is currently in the SVN repository and later inspecting the synopsis of each header file in the Reference chapter. For example, note how "operations.hpp" is completely empty, or how "config.hpp" contains duplicates for all macros. The attached patch resolves these issues for me, but I'm not sure it is correct. Specially, the new sectiondef template in toplevel mode is needed to avoid the duplicates in the #defines' synopsis... but maybe it'd be avoided in some other way. Feel free to modify it to correct any obvious mistake, but please resolve the conversion issue :-) Thanks, PS: Is this Doxygen->Boostbook conversion experimental? Support for several things seem to be missing... -- Julio M. Merino Vidal <jmmv84@gmail.com>
Julio M. Merino Vidal wrote:
Hello,
I'm currently having trouble with the conversion between the XML generated by Doxygen and the Boostbook code generated by doxygen2boostbook.xsl.
Additionally, Doxygen seems to be generating duplicate entries for some members, and I don't know why it's happening (a bug?). For example, if you document some #defines in a file, the resulting Boostbook will contain two entries for each #define, which is incorrect because 1) there are duplicate IDs, 2) the rendered document contains two entries. (This also happens with the free functions mentioned above, once they are fixed.)
FWIW, the free function duplication is apparently a doxygen issue (#367233) that was just fixed in 1.5.2. There may be others I missed. http://www.stack.nl/~dimitri/doxygen/changelog.html Jeff
On 04/04/2007, at 23:00, Jeff Garland wrote:
Julio M. Merino Vidal wrote:
Hello,
I'm currently having trouble with the conversion between the XML generated by Doxygen and the Boostbook code generated by doxygen2boostbook.xsl.
Additionally, Doxygen seems to be generating duplicate entries for some members, and I don't know why it's happening (a bug?). For example, if you document some #defines in a file, the resulting Boostbook will contain two entries for each #define, which is incorrect because 1) there are duplicate IDs, 2) the rendered document contains two entries. (This also happens with the free functions mentioned above, once they are fixed.)
FWIW, the free function duplication is apparently a doxygen issue (#367233)
Yep, it seemed like a bug since the beginning. Should boostbook workaround it or simply require a sane doxygen version?
that was just fixed in 1.5.2. There may be others I missed.
Cool. This can simplify the patch a lot. -- Julio M. Merino Vidal <jmmv84@gmail.com>
Julio M. Merino Vidal wrote:
On 04/04/2007, at 23:00, Jeff Garland wrote:
FWIW, the free function duplication is apparently a doxygen issue (#367233)
Yep, it seemed like a bug since the beginning. Should boostbook workaround it or simply require a sane doxygen version?
Some might argue that there's no such thing, but I don't want to start that debate ;-)
that was just fixed in 1.5.2. There may be others I missed.
Cool. This can simplify the patch a lot.
Seems like it would be reasonable for people to upgrade doxygen instead of adding more workarounds to boostbook. Jeff
On Apr 4, 2007, at 5:33 PM, Jeff Garland wrote:
Julio M. Merino Vidal wrote:
that was just fixed in 1.5.2. There may be others I missed.
Cool. This can simplify the patch a lot.
Seems like it would be reasonable for people to upgrade doxygen instead of adding more workarounds to boostbook.
I would very much prefer that people upgrade Doxygen. The BoostBook XSL is hairy enough without working around yet more Doxygen bugs :( - Doug
Jeff Garland wrote:
Julio M. Merino Vidal wrote:
that was just fixed in 1.5.2. There may be others I missed. Cool. This can simplify the patch a lot.
Seems like it would be reasonable for people to upgrade doxygen instead of adding more workarounds to boostbook.
Every time I upgrade doxygen, something breaks. Case in point, I just tried building proto's docs using doxygen-1.5.2, and I get: xslt-xsltproc ..\..\..\..\bin.v2\libs\xpressive\proto\doc\msvc-8.0\release\threading-multi\protodoc.doxygen file:///F%3A/boost/cvs/boost/libs/xpressive/proto/doc/xml/extends_8hpp.xml:229: parser error : Unescaped '<' not allowed in attributes values <ref refid="structboost_1_1proto_1_1extends" kindref="compound" tooltip="extends ^ Looks like doxygen-1.5.2 isn't careful about escaping angle brackets in its XML output. :-( -- Eric Niebler Boost Consulting www.boost-consulting.com
Moving to boost-docs ... Julio M. Merino Vidal wrote:
Hello,
I'm currently having trouble with the conversion between the XML generated by Doxygen and the Boostbook code generated by doxygen2boostbook.xsl.
<snip>
The attached patch resolves these issues for me, but I'm not sure it is correct. Specially, the new sectiondef template in toplevel mode is needed to avoid the duplicates in the #defines' synopsis... but maybe it'd be avoided in some other way.
Feel free to modify it to correct any obvious mistake, but please resolve the conversion issue :-)
Thanks!
PS: Is this Doxygen->Boostbook conversion experimental? Support for several things seem to be missing...
It sure seems experimental, doesn't it? The biggest thing missing is someone who is skilled at XSLT and has the motivation to fix the bugs and add the missing features. I'll gladly apply as many patches as you care to submit. And while you're at it, can you fix the bugs in Doxygen, too? ;-) -- Eric Niebler Boost Consulting www.boost-consulting.com
Eric Niebler wrote:
Moving to boost-docs ...
Julio M. Merino Vidal wrote:
PS: Is this Doxygen->Boostbook conversion experimental? Support for several things seem to be missing...
It sure seems experimental, doesn't it? The biggest thing missing is someone who is skilled at XSLT and has the motivation to fix the bugs and add the missing features.
FYI... The Dox->BoostBook translator I've been working on is finished, as far as duplicating all the functionality (and adding some) as the XSLT translator. The key feature is that it's written in Python, so more people should be able to modify it :-) The one last test I have to run is to make sure it works to replace the current full doc build. After which I'll check in the doxygen.jam file that gives one access to the new translator. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo
On Apr 4, 2007, at 6:40 PM, Rene Rivera wrote:
Eric Niebler wrote:
Moving to boost-docs ...
Julio M. Merino Vidal wrote:
PS: Is this Doxygen->Boostbook conversion experimental? Support for several things seem to be missing...
It sure seems experimental, doesn't it? The biggest thing missing is someone who is skilled at XSLT and has the motivation to fix the bugs and add the missing features.
FYI... The Dox->BoostBook translator I've been working on is finished, as far as duplicating all the functionality (and adding some) as the XSLT translator. The key feature is that it's written in Python, so more people should be able to modify it :-)
Wonderful. Anything that simplifies that toolchain is a good idea. Why oh why did I choose to do everything in XSLT? It seemed like a heck of a lot of fun at the time... Cheers, Doug
On 05/04/2007, at 0:26, Eric Niebler wrote:
Moving to boost-docs ...
Ah, didn't notice that mailing list. Will send future patches to BoostBook (QuickBook too?) to that list.
Julio M. Merino Vidal wrote:
Hello,
I'm currently having trouble with the conversion between the XML generated by Doxygen and the Boostbook code generated by doxygen2boostbook.xsl.
<snip>
The attached patch resolves these issues for me, but I'm not sure it is correct. Specially, the new sectiondef template in toplevel mode is needed to avoid the duplicates in the #defines' synopsis... but maybe it'd be avoided in some other way.
Feel free to modify it to correct any obvious mistake, but please resolve the conversion issue :-)
Thanks!
What about the patch attached now? It removes the handling of duplicate functions/macros/whatever overall, which surely was incomplete and was only working-around a bug in Doxygen. With 1.5.2, this is not needed any more and removes some magic from the stylesheet.
PS: Is this Doxygen->Boostbook conversion experimental? Support for several things seem to be missing...
It sure seems experimental, doesn't it? The biggest thing missing is someone who is skilled at XSLT and has the motivation to fix the bugs and add the missing features. I'll gladly apply as many patches as you care to submit.
I see. I don't know much yet about the XML generated by Doxygen, but at a first look the conversion XSLT seemed overly complicated. But well, maybe that conversion is really needed.
And while you're at it, can you fix the bugs in Doxygen, too? ;-)
In fact, I was going to take a look at the duplicates issue, but it looks like someone beat me to it ;-) Cheers, -- Julio M. Merino Vidal <jmmv84@gmail.com>
participants (5)
-
Doug Gregor -
Eric Niebler -
Jeff Garland -
Julio M. Merino Vidal -
Rene Rivera