Re:[boost] Javascript Tree Control [was: Serialization Menu
Jonathan Turkanis
There was a discussion a couple weeks ago about the javascript menu in Robert Ramey's serialization docs. I suggested making a menu component available Boost-wide and testing it on a large number of browsers to address portability issues. I've written a preliminary version, documented here:
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. 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. 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. 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 Boost.book might have to add a little bit to support this. While I'm on the subject of Boost.book. I would hope that the formatting is in a .css so that I might replace it with my preferred look and feel. (I prefer the "classic" one). I believe this would resolve the essentially irresolvable about esthetics. Robert Ramey
"Robert Ramey" <ramey@rrsd.com> wrote in message news:20040728163157.8D31D31AFE@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
"Robert Ramey" <ramey@rrsd.com> writes:
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.
For cases like that it's crucial to have a link on each page that gets you back to the "navigator context", i.e. the one with the index frame visible. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
participants (3)
-
David Abrahams -
Jonathan Turkanis -
Robert Ramey