From: Beman Dawes (bdawes_at_[hidden])
Date: 2007-11-25 11:03:45
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/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/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
> * 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/...
> 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?
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk