From: Robert Ramey (ramey_at_[hidden])
Date: 2004-07-14 14:12:19
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
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:
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk