Re: [boost] Attention Boosters - a subset of documentation files

From: David Abrahams (dave_at_[hidden])
Date: 2006-12-11 18:01:23

Janek Kozicki <janek_listy_at_[hidden]> 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