On Fri, 2008-07-18 at 15:53 +0100, Daniel James wrote:
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.
Interesting. That seems feasible.
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.
Well, we could certainly consider turning some of the BoostBook and DocBook linking entities (e.g., <classname>) into URLs.
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.
That causes some trouble for us, given that we're entirely based on DocBook at the moment :) Perhaps there's some post-processing step we could perform on the HTML that would achieve the same goal. - Doug