Stirling Westrup wrote:
On Fri, Mar 18, 2011 at 11:43 AM, Steven Watanabe <watanabesj@gmail.com> wrote:
On 03/18/2011 08:10 AM, Stirling Westrup wrote:
If the documentation cannot be automatically installed in a standard documentation repository, then the current documentation system is too rigid and needs to be fixed.
There is no "documentation system." The actual rule is simple. A library must provide HTML documentation. What makes it difficult to relocate is that the documentation has links to headers and source files. By the time you copy everything referenced by the documentation, you might as well just copy the whole tree.
You may wish to revise your procedures on this then. Boost has a reputation of rigorously testing its libraries. One might reasonably assume this extended to the documentation. After all, without correct documentation, most of these libraries are not very useful.
So far, my most common problem with using Boost libraries has been documentation that is unclear, outdated, incomplete and/or simply wrong. Its hard to be a world class library when you fail in the documentation.
You are confusing two issues that are completely orthogonal to each other. 1) The way the Boost documentation is structured. It's simple: the C++ code is part of the documentation. Hence, installing the documentation == extracting the Boost distribution tree. There is nothing wrong with this approach; it reduces "documentation duplication" which, exactly like reducing code duplication, is a good thing. 2) The quality of the part of the documentation that is not C++ code. Of course there may be errors in the documentation. In that case you're free to file a bug, just like with the C++ code. To conclude, changing the approach in 1) would not solve the issues in 2). -Julian