Re: [boost] ATTENTION: Library requirements..

Subject: Re: [boost] ATTENTION: Library requirements..
From: Agustín K-ballo Bergé (kaballo86_at_[hidden])
Date: 2016-01-10 22:51:45

On 1/11/2016 12:34 AM, Rene Rivera wrote:
> On Sun, Jan 10, 2016 at 9:23 PM, Agustín K-ballo Bergé <
> kaballo86_at_[hidden]> wrote:
>
>> On 1/10/2016 11:56 PM, Rene Rivera wrote:
>>
>>> On Sun, Jan 10, 2016 at 5:05 PM, Agustín K-ballo Bergé <
>>> kaballo86_at_[hidden]> wrote:
>>>
>>> On 1/10/2016 7:51 PM, Louis Dionne wrote:
>>>>
>>>> Robert Ramey <ramey <at> rrsd.com> writes:
>>>>>
>>>>>
>>>>>> The extra space used seems a small price to pay for this benefit.
>>>>>>
>>>>>>
>>>>> It's not just about extra space. Source control is for _source_ files,
>>>>> not
>>>>> generated stuff. I don't want generated files to appear in the commit
>>>>> history
>>>>> of a code branch (but another branch like gh-pages is fine).
>>>>>
>>>>>
>>>> By way of example, this is the kind of noise committing generated
>>>> documentation can yield:
>>>>
>>>> https://github.com/boostorg/hana/commit/e471106dc850ad72f7abaf442b3570f7f34da7ed
>>>>
>>>
>>>
>>> And by comparison, here's the minimal non-noise that pre-generating for
>>> Predef has: <
>>>
>>> https://github.com/boostorg/predef/commit/009367d6a1b6a26199f5b849ea166c44cf5223ff
>>>
>>>> .
>>>>
>>>
>> I honestly don't get this... No source code appears to change, but the
>> documentation somehow needs to be regenerated?
>
> I changed predef.qbk, to document the new location of a tool.

Ok, and how is the regenerated documentation related to that change? It 
took me a while to understand that the doc changes were just unrelated 
noise in the commit, and not related to the changes themselves.

>> Or does moving a .jam file to a different directory cause macros to become
>> uppercase? Or is this commit a bunch of orthogonal changes bundled together?
>>
>
> Those macro changes where a result of a previous human error (the human
> being me.. really I'm human.. trust me). In that I forgot to regenerate the
> docs after merging a PR (it may have been laziness too).

A tool could do that automatically, check the link to Boost.Hana docs 
commit that I posted earlier.

> But the HTML
> changes are still minimal, and proportional to the doc/code changes.

I guess this was the actual point of your original email. Some tools are 
better behaved than others.

>> Unless your documentation source is the HTML itself, committing
>> documentation output will necessarily introduce noise as it modifies both
>> the source and the target. But then we would be talking static
>> documentation, not generated documentation.
>
> Lost me on that. Don't know what you mean.

AFAIU, Boost.Serialization uses plain and raw HTML for the 
documentation, for each documentation page the source and target are the 
same file. As such, they are readily available for anyone cloning the 
repository, they are never out-of-sync with the documentation source 
(since they are the same thing), and they don't add noise to a commit 
message (since only the sources change).

In short, for a library with static documentation like 
Boost.Serialization, none of the concerns raised in this thread on 
automatically generated documentation apply.

Regards,
-- 
Agustín K-ballo Bergé.-
http://talesofcpp.fusionfenix.com