On Sat, 28 Dec 2013 03:16:17 -0800, Neil Groves wrote:

On Sat, Dec 28, 2013 at 10:22 AM, Mostafa wrote:

...

Can the maintainer(s) of range answer this question that came up in the documentation ML:

On Sat, 28 Dec 2013 02:09:06 -0800, Daniel James wrote:

On 28 December 2013 00:15, Mostafa

...

wrote:

...

If html files, or any other files for that matter, are auto-generated then why are they included in the repo? The reason I ask because this difference in boostbook version causes a lot of extraneous noise when I do a git status. Instead of the three html files I was expecting to be modified when I changed a qbk file there are 153 extra html files that show up as modified.

For many libraries they aren't. It's up to the library maintainer how they're managed. What you can do is rebuild the documentation from a clean checkout and commit that, then later edits shouldn't result in so many changes.

I have been generating the html and checking it in. However if there is a way to transition to a better system I am all for it. I'm catching up on the changes to the version control and the working process before making a renewed effort to clear some outstanding trac tickets. I'm sorry that I've been a little slow in catching up with the process changes. In the long-term I expect to converge on optimal working practice.

In the interim, if there is something I can do in the short-term that helps, please let me know. If you simply require permission to do what you believe is right, then please go ahead with your change. I'm happy to try a change and revert if it goes wrong.

From Daniel's reply and my very elementary understanding of Boost's build process, I think it's only necessary to revision the quickbook files, and that all files generated from the latter need not be revisioned. <MyTake> Generally, I don't think it's a good idea to revision auto-generated files, since minor differences in the generator version may result in harmless but extraneous deltas between the generated files that were revisioned in the repo by doc-generator-v1.0 and the ones generated by someone else like me who generated the same files using a newer (or slightly older) doc-generator-v1.1. This can get really cumbersome because a revision diff (i.e., git diff) will display all the harmless auto-generated diffs in addition to the real ones. </MyTake> Anyways, to make a long story short, I just wanted to tweak some docs and make a pull request when I ran into this other issue. I thought I should bring it up only because I think it represents an unnecessary obstacle to ad-hoc contributors. Mostafa

On 28 December 2013 11:16, Neil Groves wrote:

I have been generating the html and checking it in. However if there is a way to transition to a better system I am all for it.

I run an occasional documentation build (once or twice a week) which is added to the final release. The documentation from the master branch is also uploaded to sourceforge, but I'm thinking of changing it so that it's uploaded to the website. I can add range to the build.

On December 28, 2013 12:21:54 PM Mostafa wrote:

On Sat, 28 Dec 2013 07:08:44 -0800, Daniel James

wrote:

...

On 28 December 2013 11:16, Neil Groves wrote:

...

I have been generating the html and checking it in. However if there is a way to transition to a better system I am all for it.

I run an occasional documentation build (once or twice a week) which is added to the final release. The documentation from the master branch is also uploaded to sourceforge, but I'm thinking of changing it so that it's uploaded to the website. I can add range to the build.

Speaking of documentation and the final release, every time I have to build boost from scratch I have to scrounge third party distros for boost documentation (like Ubuntu or Fedora), because it seems that there is no way to centralize and install the docs. If you're already building and adding docs to the final release, can you also add an optional install hook so that they may all install in one location (like share/doc/).

That would be awesome for us package maintainers! -Steve (Member of Debian Boost packaging team)

On Sun, 29 Dec 2013 02:20:51 -0800, Daniel James wrote:

On 28 December 2013 20:21, Mostafa wrote:

...

Speaking of documentation and the final release, every time I have to build boost from scratch I have to scrounge third party distros for boost documentation (like Ubuntu or Fedora), because it seems that there is no way to centralize and install the docs. If you're already building and adding docs to the final release, can you also add an optional install hook so that they may all install in one location (like share/doc/).

Not really, as there's a lot of documentation that isn't built, and the documentation that is built often links to files in the boost tree, or uses images from the boost tree. So if we built the documentation at another destination, there would be a lot of files missing.

Then how are the files for the website documentation (i.e., http://www.boost.org/doc/libs/1_55_0/) build? Or are those also embedded in the boost tree? (At times I've been tempted just to wget everything under the latter url, since the distro docs I resort to usually are missing css and image files, sometimes the important ones.) Thanks, Mostafa