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

From: Douglas Gregor (dgregor_at_[hidden])
Date: 2008-07-18 11:22:37

On Fri, 2008-07-18 at 15:53 +0100, Daniel James wrote:
> 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.

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