Re: [Boost-build] Boost build documentation

Subject: Re: [Boost-build] Boost build documentation
From: Vladimir Prus (ghost_at_[hidden])
Date: 2013-05-14 02:32:42

On 14.05.2013 04:30, Edward Diener wrote:
> On 05/13/2013 02:13 AM, Vladimir Prus wrote:
>> On 08.05.2013 13:46, Paul A. Bristow wrote:
>>>
>>>
>>>> -----Original Message-----
>>>> From: Edward Diener [mailto:eldiener_at_[hidden]]
>>>> Sent: Monday, May 06, 2013 8:33 PM
>>>> To: boost-build_at_[hidden]
>>>> Subject: Re: [Boost-build] Boost build documentation
>>>>
>>>> On 5/6/2013 2:44 PM, Thomas Suckow wrote:
>>>>>> The Boost build documentation at
>>>>>> http://www.boost.org/boost-build2/doc/html/index.html says 2006-2009.
>>>>>> Has it really not been updated in 4 years ?
>>>>> That webpage is indeed 4 years old.
>>>>>> If it has not been updated in 4 years, could it not be updated if
>>>>>> changes have been made to Boost build ?
>>>>> Boost build has had numerous changes. I would use the nightly, not the
>>>>> latest "stable" version.
>>>>
>>>> If Boost build has had numerous changes in the last 4 years I do not
>>>> understand why the web pages
>>> have
>>>> not been updated to reflect those changes. Every link within Boost's
>>>> general documentation, on the
>>>> website and in the releases, which refers to Boost Build points to
>>>> that web URL.
>>>> What is the point of having documentation which does not reflect the
>>>> current status of Boost Build
>>> as
>>>> the official documentation for the product on the web ?
>>>>
>>>>>>
>>>>>> If it has been updated in the meantime could the dates be changed to
>>>>>> reflect when it was last updated ?
>>>>> I think the source contains newer documentation, but not much. The
>>>>> information that would be really useful would be the modules that ship
>>>>> with boost-build.
>>>>
>>>> There are lots of other things I have been told about Boost Build,
>>>> usually by the kindness of
>>> Steve
>>>> Watanabe answering my questions, which is not in the Boost Build
>>>> documentation at the URL above.
>>> It is
>>>> hardly just about the modules which ship with Boost build, although
>>>> knowing more about them would
>>>> also be helpful.
>>>
>>> We've accepted much kindness from Steven Watanabe and many others, but
>>> collectively, we Boosters
>>> have failed to get the accumulated knowledge about Boost Build into
>>> our documentation.
>>>
>>> And the number of queries that are repeats suggests that we have
>>> abused their kindness.
>>>
>>> Despite the noble efforts of Daniel and others, several bits of key
>>> documentation, initially
>>> state-of-the-art, are way out of date.
>>>
>>> IMO, this is because we have restricted the access to add to the
>>> documentation to too few people,
>>> partly through limiting write-access, but mainly from not having a
>>> 'standard' Boost-way of producing
>>> docs and updating them.
>>
>> Do we have any write-access limits? I am not aware of any.
>
> I agree that anyone with access to the SVN trunk can make documentation
> changes to Boost build.
>
> What I do not understand is why when some functionality changes in Boost
> build, as programmed by you or other programmers who work as developers
> in Boost build, the programmer who has made that change is not willing
> to update the documentation.

How did you arrive at this conclusion? The problem is not so much that a
lot of radical changes are checked in without documentation, the problem
is more that for changes made long ago, like 5+ years:

- Some of the obvious documentation things were not known. For example, the
value of index
- The presentation of some other things is found suboptimal

Neither of these can be fixed incrementally.

 > Your remark about write-access limits
> implies that you expect the end-user who discovers the difference in
> functionality to update the documentation.

My remark about write-access was meant to say that comment about 'restricted access'
is not 100% accurate. I don't think your implication is accurate.

- Volodya