Re: [boost] [1.36.0] Libraries with unmerged changes?

From: Daniel James (daniel_james_at_[hidden])
Date: 2008-07-18 10:53:13

2008/7/18 Douglas Gregor <dgregor_at_[hidden]>:
>
> 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