This is an interesting question. It seems I spend half my time bouncing back and forth between boost documentation pages. When this started to happen with my own boost serialization documentation I added a navigation frame with with a static index which would let be jump right to the part that I was interested in. Eventually as I added more pages to the documentation, the scrolling started to annoy me and I implemented the current scheme. I was inspired by the boost pre-processor documentation and I don't remember whether or not I was aware of the "kind of policy" against. I've been very, very pleased with the utility of the result. I made it and checked with both IE and netscape. I haven't checked with other browsers but have no received no reports that it doesn't work. I love this system. I think it should be adopted for all boost documentation. In this way I have a collapsible navigation pane which would let me navigate all of boost rather than just the serialization library. There are a couple of issues a) I had to make it "by hand" for the serialization library. OK for a prototype - but unsatisfactory in general. Ideally it should be generated automagically by Boost.Book. After all it's just an index which I would presume Boost.Book should be generating anyway. I haven't studied boost book so I don't really know anything about it. But if it doesn't include something like this I would consider it a glaring oversight. b) I believe that with a little effort the browser portability issues could be addressed. Basically there could be two index pages - a dynamic as well as a static one. All the "documentation pages" would be unchanged. I didn't really go into this because no one seemed to have a problem with the dynamic one. Of course the above doesn't raise the key issue that Dave raises. Should it be removed now? Should it be replaced with anything? - if so what? I would prefer to leave as it is. A final point regarding boost book. When I go to the main boost page and select nightly CVS I get a page which seems to have the look/feel that of the pages the boost.book is going to produce. I don't want to start a religious argument about aesthetics, but... I prefer the previous look and feel which was supported by the original documentation guidelines. Its just one man's opinion. Dave Abrahams wrote:
We have a kind of policy against using scripting in our library doc pages, mostly because in the past scripts have caused major portability or usability problems. I personally love the menu on the left of the serialization lib docs page, but if it uses scripts and we can't really be assured that they'll work everywhere, it probably ought to be removed.
There are alternatives that might actually be more usable: http://article.gmane.org/gmane.comp.lib.boost.documentation/389