On Sat, 20 Jul 2013, at 07:26 PM, Paul A. Bristow wrote:
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.
Hopefully, git should make this easier, since you can work in a git branch within the normal boost setup.
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).
Right now the best way to do that is using 'boost:' links. You might be able to use docbook's 'olink' tag, I think that's more of a build problem than anything. http://www.sagehill.net/docbookxsl/Olinking.html
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.
You should be able to setup 'boost:' links to link to the site in pdf documentation. I think by setting 'boost.url.prefix'.
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.
The big problem there is dealing with different documentation formats. Even quickbook based documentation has a variety of reference formats (e.g. asio, geometry, spirit). Could maybe combine the output from autoindex, John would be the person to ask about that, and it's independent of modularization really.