[boost] Re: Re:Javascript Tree Control [was: Serialization Menu

From: Jonathan Turkanis (technews_at_[hidden])
Date: 2004-07-28 12:59:02

"Robert Ramey" <ramey_at_[hidden]> wrote in message
news:20040728163157.8D31D31AFE_at_acme.west.net...
> Jonathan Turkanis

> >I've verified that it works -- with varying levels of
functionality -- 
> >on 26 browsersincluding some antiques such as IE3.02.
>
> I'm still looking at this but I have some preliminary questions
observations
>
> a) Visually as displayed in the demo it looks very nice.

Thanks.

>
> b) I think that testing on 26 browsers and asserting it works on 95%
of
> those in use is the wrong way to look at it.  I believe it should be
a
> requirement.  "Works on all browsers" - has "more" functionality on
browsers
> that support it.  In the case of my implementation - it displays
fully
> expanded unless its one of the three browsers known to work
properly.

Let me repeat myself a bit. In a reply to Martin Wille, I said:

> I should have put this in the documentation: The control should (I
> hope) work on any browser if one of the three following conditions
is
> satisfied:
>
> 1. It supports no javascript at all (and understands the 'noscript'
> element)
> 2. It is reasonably conformant with the W3C DOM (level of required
> conformance currently unspecified)
> 3. It is a old version of IE, Netscape or Opera.
>
> In cases (1) and (3), the control displays in a fully expanded
state.
>
> My idea was to presume that untested browsers satisfy (2), thereby
> allowing the control to function optimally on as many browsers as
> possible, and to add browsers to (3) as needed.

By default, browsers are assumed to satifsy (2). This can easily be
changed so that by default browsers display the tree in fully exapnded
state. (All I have to do is change one occurence of 'true' to
'false'). Then my implementation would satisfy your requirement
(except as noted below) -- if I understand you correctly.

> c) The boost "rule" no javascript. This should be re-formulated to
be "all
> documentation should be usable on any browser that supports frames".
This
> can be implemented using the approach b) above.

I almost agree. Some browsers are so poorly programmed that its not
reasonable to be required to support them. HotJava is an example. When
I attempt to view your serialization docs on HotJava, sometimes it
displays okay, but a good deal of the time it crashes -- particularly
if I press reload a couple of times. (This is *not* a criticism of
your documentation.)

> d) The control presented is a very nice job - but I was hoping this
might
> take a slightly different direction.  What I would like to see is:
>
> "Boost Documentation Navigator"
>
> 1) a two frame page.  Left frame containing a expandable/collapsible
index
> implemented by a control such as yours.  The right page would be the
current
> boost documentation pages.
>
> 2) This "Navigator" would be automatically generated from the
Boost.Book xml
> files using XSLT or some other appropriate tool.
>
> This would have the following advantages.
>
> 1) Usage of this "Navigator" would be optional.  Lots of times its
> interesting to send a page without the frame.  Searching through
pages
> without the "Navigator" would be the same as it now - tedious but
relieable.
>
> 2) it would be "free".  The contents/index would be automatically
generated
> without my having to go through another layer of documentation and
preparing
> an index by hand.  Those using boost book would get a complete index
while
> old documentation would have just an entry into the top level.
>
> 3) it would provide much incentive for boost authors to move their
> documentation over to boost.book

I agree with all of this. But I think that having a tree control
component is still useful:

1) The control could be used by boost.book in the generated
documentation. The HTML for no-script borwsers would be generated
automatcially, as well as the script that draws the tree control for
script-enabled browsers. The alternative would be to have both
scriptable and no-script browsers display the same HTML, together with
a minimalist script which expands and collaspes nodes. This is your
approach.

There are some advantages, however, to having the control represented
as a javascript object which lives in the menu frame. For instance,
the synchronization feature works by searching through the urls for
each node in the tree until it finds one which matches the content
frame.To implement this feature with your technique would be a bit
messy -- but do-able. (It could also be done by having an
automatically generated synchronization link in each content page.)

In the end, either approach would be okay with me, assuming that all
documentation is automatically generated.

2) The control is a usable during the transition to boost.book, which
its seems may be indefintely long.

Jonathan