Re:[boost] Serialization Menu

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
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