Janek Kozicki <janek_listy@wp.pl> writes:
Thing that is bothering me:
" doc/ ...............A subset of all Boost library docs" ^^^^^^
why it's a subset? I want all documentation for my freshly downloaded boost.
You get it; that directory just happens to be a subset. The point is to keep people from looking there, as they often do, for complete documentation.
1. Are some libraries undocumented? 2. Is their documentation placed elsewhere? Where?
Oh I see the point "4. Don't be distracted by the doc/ subdirectory... Start with libs/index.html". This explains a bit, but better not to have to explain anything.
Yes it would be much better. Too bad; we have a misleading directory structure.
I opt for ,,merging'' doc/ and libs/index.html. So that a causal downloader will have an access to *whole* documentation from doc/index. It could be done as simply as copying libs/index.html to doc/index.html
You think that if I look in doc/ and see documentation files for about 10 libraries, the presence of an index file whose contents I might never even look at is going to leave me less confused?
I guess that doc/ is a documentation written in a new format, and the documentation in libs/ uses old format. So this doc/index.html will stay there until the rest of documentation is converted to new format (if ever).
It's just for convenience.
I would use a redirect if I didn't want it to be massively inconvenient for developers/maintainers.
Also I noticed that the redirections are wrong in *many* documentation files. For example - a person without a network connection, but with downloaded and installed boost opens a file doc/html/any.html and what happens?
It goes to the Boost website, IIRC. I'm sorry, but if there *is* a problem here, it is not an area I'm trying to address right now. I just need to get the Getting Started document in shape. For anything outside that scope, if you would step up and address it yourself I and the whole community would be grateful.
A failed redirection to http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/any.html
This file should contain a redirection to locally instaled file.
I think what you get in a Boost distro is slightly different from what's in the CVS. Try downloading the 1.33.1 distro... but anyway, really, I can't focus on this issue right now.
Maybe this is out of the scope of your post, but this difficulty in browsing documentation always annoyed me, when the network was slow or down.
Understood. Please volunteer to help fix problems in this area; I really would appreciate it. -- Dave Abrahams Boost Consulting www.boost-consulting.com