2008/7/18 Douglas Gregor <dgregor@osl.iu.edu>:
Right now, the generated documentation is going to live outside of the modules. The problem isn't on the CMake side---we can easily generate whatever commands we need to drive the BoostBook toolchain---but that BoostBook/DocBook doesn't really work well as a modular system. The problem is that, when generating the documentation separately, we don't get the inter-library links that we'd like.
A while I ago I was looking at the mechanisms for linking to files. Steven Watanabe suggested a patch to create links relative to boost root: https://svn.boost.org/trac/boost/ticket/1166 It's clear that I was stumbling around the idea. I was going to try to get something into 1.36, but I discovered problems with the implementation and had other priorities, so I left it for 1.37. If boost is going to be more modular, I think it would be possible to do adapt the idea, using a custom URL along the lines of 'boost://module/path' which could either generate relative links or link to the website, depending on build parameters. Of course, that's for linking to files. I know there are multiple mechanisms in docbook for linking between separate docbook units, but when I looked at them, they seemed complicated and awkward to use. You probably know a lot more about them than I do.
Moreover, the HTML files that the DocBook XSL generates aren't currently in a form that easily permits side-by-side installation of documentation for each library separately and, even if we did, we need to deal with the problem of generating a table of contents and/or index.
We have to pull together documentation generated by several different methods, so I don't know if a docbook based solution would be appropriate.
So, while I'd like modular documentation generation, it's going to need some serious work on the BoostBook side that I'm not prepared to do. Of course, help would be appreciated :)
I've been doing a little work with BoostBook, but I don't think I'll have time for 'serious work'. Daniel