[boost] [website] Tools docs usability problem

From: Beman Dawes (bdawes_at_[hidden])
Date: 2007-11-24 09:07:25

Some of the documentation that used to live within the boost-root/tools 
directory sub-tree has been moved to the 
website-root\public_html\beta\development directory.

That creates a usability problem because 
boost-root/tools/tool-name/index.html is no longer present. When working 
with these tools, you are usually using either the command line or a GUI 
directory tree browser, not a web browser. Thus it is now a real pain in 
the anatomy to locate the docs since aren't right there where you are 
working. Worse yet, you may fail to realize there *are* any docs, and 
never look for them at all.

In the boost-root/libs directory tree, we solve this same problem by 
providing an index.html file for each library that automatically 
redirects to wherever the docs for the library actually live. Because 
that is generally a relative link, it finds either the web version or 
the version within the local disk tree, depending on whether you are 
browsing the web or a local working copy. This is expected behavior, and 
works very well in practice. If you are using a working copy, you get 
the docs as of that working copy. If you are looking at the web site, 
you get the docs matching the web site release.

Perhaps we can solve the problem for tools in the same way. Each tool 
could have an index.html file that redirects to the actual docs 
location. With the docs now in a sub-tree that is not within the 
boost-root tree, the redirection requires a bit of logic:

    If index.html is a local working copy, redirect to beta.boost.org/...
    otherwise redirect to www.boost.org/...

Is this the best solution? Is Javascript capable of doing that?

--Beman