Rationale |
|
The tree control component was written with careful attention to the ECMAScript/JavaScript Rationale in the Boost Library Requirements and Guidelines and to concerns raised on the boost developers list.[1]
The requirements are summarized as follows. The control must be:
The control should function adequately on a wide range of broswers, including old browsers, browsers which do not support scripting or images, and browsers for which scripting or image loading has been disabled. For details on portability, see Portability and Screenshots.
To accommodate those who view Boost documentation online over slow network connections, the tree control must have relatively small code size and must not depend on large supporting documents such as images or stylesheets. The script <doc/tree/tree.js> is currently about 12k, but can be mechanically compressed to about 7k — smaller than the Boost logo. The stylesheet <doc/tree/tree.css> is just 850 bytes.
The effect on download time should be mitigated by the fact that there will be just one copy of the script for all of Boost, and this will typically be cached by users' browsers.
It must be immediately obvious to most users how to operate the tree control. To achieve this goal the control's user interface has been modelled after the tree controls provided by most modern windowing systems and familiar to users through filesystem viewers such as Windows Explorer and Nautilus.
Documents which appear within the content frame must not need to know anything about the tree control component. This makes it easy to migrate existing documentation to use the tree control.[2] In addition, by concentrating all the JavaScript in a single location, it significantly reduces the likelihood of JavaScript errors and tends to make them obvious and easy to diagnose when they occur. This helps to address the fifth and sixth items in the ECMAScript/JavaScript Rationale ("Would require Boost to test web pages for ECMAScript/JavaScript compliance" and "Makes docs maintenance by other than the original developer more difficult").
It must be possible to link to an arbitrary position within documentation, so that subsections can be bookmarked or published. To understand this need, view the Boost Preprocessor Library documentation, select 'Reference' from the navigation frame, then click ADD. The documentation for the macro BOOST_PP_ADD should appear in the content frame; however, on most browsers the url for the library homepage will still appear in the browser's address bar. This makes it difficult to bookmark or post a link to the documentation for BOOST_PP_ADD.[3]
The tree control component addresses this problem by providing a hyperlink [link to this page] which synchronizes the tree control and the url displayed in the browser's address bar with the document curently displayed in the content frame.
It is possible to make documentation 'self-synchronizing', so that the hyperlink [link to this page] is not required. For instance, Reece Dunn suggested replacing each hyperlink within library documentation with javascript code to load the requested document and update the tree control and the top-level url. Rene Rivera suggested displaying the tree control in the same frame as the main content. Both these suggestions have drawbacks; most notably, they sacrifice non-intrusiveness. But if the tree control component is integrated into Boost.Book, either solution, or some combination of the two, may be viable.
The control must not make use of animations, 3D effects, sound clips, etc. It's appearance should be spare and utilitarian, in keeping with the look and feel of most Boost documentation. This helps to address the third and fourth items in the ECMAScript/JavaScript Rationale ("Often results in really bad user interface design" and "It's just annoying in general").
[1]See lists.boost.org/MailArchives/boost/msg67245.php and follow-up messages.
[2]Links to documents which should load in the top-level frame rather than in the content frame must be given a target attribute of _top. E.g.,
<p>
For more information, please see
<a href='http://www.canoe-world.com/' target='_top'>Canoe World</a>.
</p>This is a feature of HTML frames, however, and not of JavaScript.
[3]I apologize for singling out the preprocessor docs. It's the only Boost example I could find.
Revised 22 July, 2004
© Copyright Jonathan D. Turkanis, 2004
Use, modification, and distribution are subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)