Boost Docs :
From: Douglas Gregor (gregod_at_[hidden])
Date: 2003-07-04 10:46:54
> I have tried to generate a sample documentation for the string_algo lib
> and Doxygen. Process was a little bit painfull, but the result is quite
Glad to hear it! I'm obviously still working on the process, but your
feedback helps quite a bit.
> I have a few comments and wishes.
> 1) Generation process.
> - I had to modify boost/tools/build/tools/doxygen.jam file.
> It contains quotes in the echo command ( for generating the doxygen
> These quotes are not handled well under Windows platform. I had to remove
Ah, right. The "echo" on Window is surprisingly hard to use for a
programmer, but the bjam print module should help
> This file also contained hard-coded path in 'rule extract-xml' ( Being not
> I have changed it to point directly to my files ).
> - Generation process always overrides the doxygen file. It would be handy
to be able
> to modify this file, to tune some of doxygen's parameters. So it would
> if the file is not generated over and over again, just modified when
> Or there could be some possibility to merge user part of doxygen file with
> a generated one.
I _think_ the Boost.Jam way would be to define features for Doxygen's
parameters, so that instead of writing out a Doxygen configuration file by
hand you would just supply some features to the Doxygen module and it would
map them to Doxygen parameters. Perhaps its not worth it, and in any case a
good interem solution would be to allow a "configuration override" file that
is appended to the BoostBook-created file. The reason we regenerate the file
each time is that we need to override some of the settings, and it makes
_sure_ that we can find the resulting files.
> - From some unknown reason 'xslt-xsltproc-dir html/HTML.manifest' step
> very long time to complete. I assume that I have misconfigured
> I have followed the boost-book guide and downloaded xsl and dtd into my
> harddrive, but they are probably not used. ( My Jamfile is included at the
One way to check this would be to add "--nonet" to the xsltproc command
line. That will tell you if it tries to download something off the 'net for
> 2) Generated output
> - First of all it looks much better then anything I have tried so far :)
> - There are some parts missing in the generated docs. For example
> are not there ( although they are in the file and doxygen recognized
Thanks for reporting this. Both are easily fixed.
> - I wish there will be some more doxygen parameters recognized. For
> the file description ( \file tag ) or examples ( \example tag ).
I'll look into it. In general, once I know a feature is missing it's easy to
add as long as its in the Doxygen XML in a usable format.
> - In my example, template functions have rather long return value and the
> does not look very nice ( see
> I don't know if it is feasible, but return type should go on separate
line if it is
> longer then some reasonable limit and possibly ( secret wish :) )
splited into several lines.
It's feasible. Actually, I thought I'd already coded it, but obviously
that's not the case :).
> - Doxygen is able to create links to different components of the
documentation directly in
> defintions. I would like to create link for types and template
paramters. ( something
> like this: http://www.boost.org/libs/utility/transform_iterator.htm ).
Again, I'll look into it. I'm not quite sure how it will fit with Doxygen,
but the goal for template parameters is that they will be declared to model
certain concepts (concepts will also be represented in BoostBook, by way of
Caramel), and BoostBook will create links from template parameters to the
concepts they model.
> That's all for now. I will post more as I will progress with the
> import toolset : using ;
> using xsltproc ;
> using boostbook : /cygdrive/d/docbook/xsl/
> : /cygdrive/d/docbook/dtd/
> using doxygen ;
The chunk of code above should really go into the user-config.jam in , e.g.,
$BOOST_ROOT/tools/build, because these are user-specific preferences. The
Jamfile.v2 should contain the other rules that describe how to build the