-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Daniel James Sent: Saturday, July 20, 2013 5:50 PM To: boost@lists.boost.org Subject: Re: [boost] Status of various Boost initiatives?
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.
All sounds plausible but the proof of the pudding ... It is moving from experimental to sandbox to trunk to Boostbook collections that has caused me (and John even) some grief. This is where a ' official convention' on where everything lives might help. I feel that it would be very useful to be able to produce links easily even to the level of section or paragraphs or anchors within other libraries, and of course to their header, test and example files too. I feel these links are a major benefit to readers now that Boost has become so large (and further expansion seems inevitable). It would be nice if the pdf version links work too, but that may be asking too much. Some people like the PDF format for its self-contained nature - and that you can use the Find function in the whole document, something that you can't easily do with html - only the html page that you are on. Some form of local and global index would also be useful. I still find trouble finding things that I know are there, despite googling from boost.org. Your expert input will be totally invaluable of course :-) Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com