On Aug 13, 2004, at 8:07 PM, Eric Niebler wrote:
I'll repeat my other gripes here ...
My project is in the boost-sandbox, and all the relative HTML links generated by doxygen/boostbook are broken. For instance, the links in the header (Home, Libraries, People, FAQ, More) are broken, as are all the links to the source files. Is there some way to specify a relative path prefix so these links are correct?
We first need to replace all of the places where I stupidly put "../../" with $boost.root (or <xsl:value-of select="$boost.root"/>, depending on context). Then we can pass the correct path to the stylesheet via <xsl:param> in bjam.
<<extra info: the filenames in the Jamfile look like this:
../../../boost/xpressive/detail/algo.hpp
However, the URLs to the source files look like this:
<a href="../../boost/xpressive/detail/backref.hpp"
Considering where bjam is outputting the html, this should be:
<a href="../../../../boost/xpressive/detail/backref.hpp">>
Does anyone know how to easily get this sort of info from bjam, e.g., how many levels deep are we in the project?
I don't want the private members documented. I have added these directives to the doxygen rule in my Jamfile.v2, but they don't seem to have any visible effect:
<doxygen:param>EXTRACT_ALL=NO
<doxygen:param>HIDE_UNDOC_MEMBERS=YES
<doxygen:param>EXTRACT_PRIVATE=NO
<doxygen:param>ENABLE_PREPROCESSING=YES
<doxygen:param>MACRO_EXPANSION=YES
<doxygen:param>EXPAND_ONLY_PREDEF=YES
<doxygen:param>SEARCH_INCLUDES=YES
What am I doing wrong?
<<extra info: With Doug's recent changes, private members are thrown out, so this one is moot. Sort of. I'm still interested in turning on preprocessing, but the above isn't doing it. I have added <doxygen:param>PREDEFINED=BOOST_DEDUCED_TYPENAME=typename, in the hopes that it would replace all occurances of "BOOST_DEDUCED_TYPENAME" with "typename" in the code, but it didn't work. Why?>>
Possibly nothing. This is likely a Doxygen bug, where it doesn't follow its own parameters sometimes in the XML it outputs. To double-check this, see if BOOST_DEDUCED_TYPENAME shows up in the generated ".doxygen" XML output anywhere.
For each entity, I have a brief description and a detailed description. The brief description ends up at the top of the generated HTML file (good), but the detailed description ends up orphaned at the bottom (bad). There is a "Description" section in the HTML following the "Synopsis" section, but it is always empty. Bug?
<<extra info: I find this only happens for the documentation corresponding to free functions, not classes. If there is a Parameters section (/param), it appears after the "Description" header but before the description text.>>
I've moved the "Parameters" list after the description, but left it before the effects/throws/etc clauses. Or they could go last; doesn't really matter to me.
The text for the following doxygen fields end up orphaned at the bottom of the generated HTML, with no section header:
\pre
\return
There are probably others that I haven't discovered yet.
<<extra info: also without headers are \post and \attention.>>
These changes require some minor tweaking to tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl, to recognize the section kinds for these clauses and turn them into BoostBook. I'm actually a little surprised that 'pre' is working but 'post' isn't, because I can see code for the latter but not the former...
For enumerations, I have doc comments for each of the members, but they are not getting emitted in the HTML. Known problem? (I am aware that I need a \file directive for global entities to get emitted.)
Known problem: BoostBook doesn't support these yet. It would take a little extension and some hacking in tools/boostbook/xsl/type.xsl to get this to work.
<<extra info: I can't get *any* documentation about enumeration to get emitted -- not the brief description, or the full description, or the descriptions of any of the individual members of the enum. Nothing.>>
I *thought* this would work... I'll check it otu.
Other things I've noticed:
If I mention a type in a doc comment, it should get cross-linked in the resulting HTML, but it doesn't.
Probably a simple matter of determining how Doxygen XML represents links and transforming them into BoostBook links.
And if I want to change the filename that a class appears in, the Doxygen guide says I can do it with the /class directive, but it doesn't seem to have any effect.
I'll have to see how Doxygen XML deals with this before I can guess what's involved.
I would be happy to make some of these changes myself, if I only knew where to start. Can somebody point me in the right direction? What files are involved in the various transformations?
The BoostBook->DocBook bits (where most everything happens) are in tools/boostbook/xsl. The Doxygen->BoostBook bits (where all of the bugs come from) are in tools/boostbook/xsl/doxygen.
Doug
------------------------------------------------------- SF.Net email is sponsored by Shop4tech.com-Lowest price on Blank Media 100pk Sonic DVD-R 4x for only $29 -100pk Sonic DVD+R for only $33 Save 50% off Retail on Ink & Toner - Free Shipping and Free Gift. http://www.shop4tech.com/z/Inkjet_Cartridges/9_108_r285 _______________________________________________ Boost-docs mailing list [EMAIL PROTECTED] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
