Rene Rivera wrote:
Beman Dawes wrote:
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.
Well, no. Only the regression testing instructions moved. And obviously having two versions of the same test instructions is not something we want as they will go out of sync, as they are now. All the other tools are as they where before. One that needs to change are the Boost.Build docs as Volodya needs to have those regenerated daily.
That creates a usability problem because boost-root/tools/tool-name/index.html is no longer present.
We never had such files in the first place, AFAIK.
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.
Hm... Quick survey:
tools/bcp/bcp.html tools/boostbook/doc/*.xml (end up in doc/html/boostbook.html) tools/build/index.html (redir to tools/build/v2/index.html) tools/buildbot (no docs yet) tools/common (no docs) tools/inspect/index.html tools/jam/index.html (redir to doc/html/jam.html) tools/litre (no docs) tools/quickbook/index.html (redir to tools/quickbook/doc/html/index.html) tools/regression/index.html (redir to tools/regression/doc/index.html) tools/release (no docs) tools/wave (no docs)
If we want to be consistent we would want to:
* Rename tools/bcp/bcp.html to index.html.
Or add an index.html that redirects to bcp.html. John, are you reading this-?
* Create a tools/boostbook/index.html that redirs to the doc location.
Yes. Please go ahead and do that.
* Ignore tools/buildbot for now since this may not be needed if Dave gets good results from Bitten.
Yes, and Dave does seem to be getting good results from Bitten. I'll leave it up to you, but it seems to me that tools/buildbot should be deleted since we aren't actively using it. We can always retrieve it from SVN if needed.
* Move tools/common to someplace more logical. It may not even be used by now. * Finish writing the tools/inspect/doc/inspect.qbk docs and change the index.html to a redir. * Have Dave and/or Daniel write docs for tools/litre. And also put in copyright statements and general cleanup.
Yes to all three. Create tickets?
* Document tools/release. Or perhaps these are obsolete?
I haven't looked at them, but next week when we start looking at release candidate creation I assume we will update or replace what is there.
...
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?
We don't need that solution. The simple redirect is fine for just about all tools docs. The one exception is the testing docs. I think we can get away with a short note mentioning that the docs for running tests are in the web site. With a link to beta.boost.org for now. When we switch to the live site we can change that link.
A short note is fine. Could you please add it? Thanks, --Beman