On Sat, 20 Jul 2013, at 06:02 PM, Dave Abrahams wrote:
on Thu Jul 18 2013, "Paul A. Bristow"
wrote: My original enquiry was to know if you have yet sketched out how the docs for each library would be built and made available, and if they would be available in some sort of combined way for reviewed and accepted libraries, a bit like the Boostbook collection http://www.boost.org/doc/libs/1_54_0/doc/html/index.html, but for *all* libraries, preferably in some standardish format.
I also see a need to be able to provide links to other Boost libraries - Boost is highly, and increasingly, incestuous ;-)
But if you haven't started consideration of this yet, then getting the main files into GIT format is obviously has total priority.
Actually my plan is to ask other people (like you) to consider those questions and solve those problems.
As far as I'm concerned the plan is to adjust the header links to the new location (probably using a one-off perl script) to get things working quickly. And then try to do something better later. Linking in boostbook is problematic, because xslt has no real support for paths, so I expect the better solution might be to write some kind of post-processor (for html and fop markup) which will adjust custom urls depending on the situation. The urls would be similar to the current 'boost:' urls, but with a way to specify the module, and they'd work for images. Something like 'boost://math/doc/html/quaternions.html' (btw. it would be better if math had forwarding file at places like 'libs/math/quaternion/index.html'). We'd also perhaps distribute a version of the html documentation from before the mapping, so that distributions can adjust the links as they see best. Should probably use a better schema than 'boost', hopefully there's an official convention for custom url schemas. And then, in a future version of quickbook, we could rewrite relative urls to this custom url schema so that they'd behave sanely.