|
|
Boost Interest : |
From: Doug Gregor (doug.gregor_at_[hidden])
Date: 2008-05-24 12:06:43
Hi all,
I've started working on the build logic for the BoostBook
documentation toolchain within CMake. So far, the basics are working
on Linux with the Function library, so with the appropriate
configuration one can build HTML documentation for Boost.Function (in
libs/function/doc).
I want to take this opportunity to point out a really, really cool
feature of this system: it can automatically download the right
DocBook DTD and DocBook XSL stylesheets for a pain-free BoostBook
installation. This is essentially what the setup_boostbook.sh script
does for bjam, but it's built into the system. Once you have xsltproc
installed (a necessary prerequisite), just turn on DOCBOOK_AUTOCONFIG
and it'll do its magic. The important CMake feature behind this is
file(DOWNLOAD ...).
There is still a LOT of work to do in this area. We still need
transformations from Doxygen to BoostBook and from QuickBook to
BoostBook (the latter requires building quickbook, which isn't enabled
now). Plus, there are issues of installing documentation (including
extra documentation files like images, both from the common doc/html
and any library-specified images, making "make clean" work, properly
managing documentation dependencies, and adding the DocBook->man pages
and DocBook->PDF transformation paths.
One interesting issue that cropped up is that BoostBook is meant to
build monolithic documents encompassing all of Boost, so that it can
cross-reference the various libraries. That's at odds with the more
modular approach we're trying to take with CMake. So, right now, all
inter-library links are automatically suppressed in the resulting
documentation. That's probably okay... but we'll need to find a way to
present documentation to our users, especially when it is installed by
a binary installer.
Comments, ideas, and CMake code all appreciated. I'll ping the list
again when I have a more complete version of the toolchain working. If
you're interested in working on part of this, please tell me so we
don't duplicate effort!
- Doug