Re: [boost] Missing Documentation on Building and Installing Documentation.

Subject: Re: [boost] Missing Documentation on Building and Installing Documentation.
From: Julian Gonggrijp (j.gonggrijp_at_[hidden])
Date: 2011-03-20 17:44:39

Stirling Westrup wrote:

> On Fri, Mar 18, 2011 at 11:43 AM, Steven Watanabe <watanabesj_at_[hidden]> 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