Re: [boost] [Boost Library Incubator] Unable to submit library

Subject: Re: [boost] [Boost Library Incubator] Unable to submit library
From: Edward Diener (eldiener_at_[hidden])
Date: 2014-07-21 09:40:22

On 7/21/2014 9:21 AM, Paul A. Bristow wrote:
>
>
>> -----Original Message-----
>> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Edward Diener
>> Sent: 21 July 2014 14:13
>> To: boost_at_[hidden]
>> Subject: Re: [boost] [Boost Library Incubator] Unable to submit library
>>
>> On 7/21/2014 7:02 AM, Paul A. Bristow wrote:
>>>
>>>
>>>> -----Original Message-----
>>>> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of
>>>> Robert Ramey
>>>> Sent: 20 July 2014 17:59
>>>> To: boost_at_[hidden]
>>>> Subject: Re: [boost] [Boost Library Incubator] Unable to submit
>>>> library
>>>>
>>>> Edward Diener-3 wrote
>>>>> On 7/20/2014 2:03 AM, Robert Ramey wrote:
>>>>>> Edward Diener-3 wrote
>>>>>
>>>>> I think you can appreciate that having to duplicate tests which
>>>>> already exist through bjam/Boost Build when the user clones the
>>>>> project is not something I really want to do. I really don't see the
>>>>> big deal of someone interested in my library cloning it locally
>>>>> under modular-boost and then having all the documentation and tests
> locally.
>>>>> I explain very carefully in my top-level *.txt files how to do all this.
>>>>
>>>> There's no disagreement here.  That's exactly how I envision that
>>>> this site be
>>> used.
>>>>
>>>>> I do appreciate the work you put into it. But I think that anyone
>>>>> interested in a library in the Boost Library Incubator sight should
>>>>> be trying it out locally just like everyone does with Git projects.
>>>>
>>>> There's no disagreement here either.
>>>>
>>>> But there are a couple issues you've left unaddressed.
>>>>
>>>> a) One looking for a library can only find documentation for
>>>> libraries already
>>> in
>>>> boost.  For the sandbox one had to download the package and
>>>> (maybe) build the documentation in order to see the decimation.  For
>>>> me this
>>> was a
>>>> big problem which I addressed by requiring browsable html
>>>> documentation.  The github method - (has a minor/temporary problem - I
> know)
>> is perfect for this.
>>> It
>>>> means one can browse the documentation immediately.
>>>> So this issue is resolved for me.
>>>
>>> The issue of generated (mainly html) files in GIT is still a nuisance.
>>>
>>> If you are a sole developer, then it is quite easy - you simply
>>> include all the /doc folder with /html etc in GIT.
>>>
>>> But if you are developing *with* someone else, these generated files are a
> PITA.
>>>
>>> You have keep reverting the /html files every time you want to GIT pull.
>>>
>>> And you have push the updated docs every time too - and these may be quite
> big.
>>>
>>> I don't see a better way round this yet.  Ideas?
>>
>> I do not think that generated HTML documentation should be in Git. The only
> reason
>> I put it in for my VMD library is because it is on the Boost review queue, so
> I am
>> trying to make it easy for someone who might be interested in the library to
> look at
>> the documentation without having to create it themselves. But really, with the
>> proper jamfile in the docs directory, anybody should be able to recreate the
> docs.
>>
>> While I think it is an advantage of the Boost Library Incubator that someone
> should
>> be able to see the docs directly from the website, anyone interested enough in
> a
>> library should be willing to clone it locally and regenerate the docs.
>
> Historically, building the docs has been a step too far for most people.
>
> Unless the build process can be fully automated, it's just not going to happen -
> not just to peruse a library that may never make it.

You have made a good point, but the principle remains the same: 
generated information which can easily change when some "source" changes 
is a PITA for any source control system.

>
> I think that until we have fully digested modular-GIT, that's not going to
> happen either.

For Boost libraries does anybody put their generated documentation on 
Git ? I know that I don't for TTI.