Re: [boost] ATTENTION: Library requirements..

Subject: Re: [boost] ATTENTION: Library requirements..
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2016-01-07 17:52:23

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Glen Fernandes
> Sent: 07 January 2016 18:30
> To: boost_at_[hidden]
> Subject: Re: [boost] ATTENTION: Library requirements..
> 
> Rene wrote:
> > I'm making my Predef library be that "golden" example. By commenting
> > the source to illustrate the requirements. But since my lib doesn't
> > have source it may not be the best.
> 
> It's interesting that Boost.Predef has both QBK sources and generated HTML output in the
repository.
> I was considering doing this for Boost.Align but did not want repository history affected by
commits
> around generation of documentation.

 
> Now that we're on git, and each library's repository already has two branches (master,d develop),
> maybe it would be a good idea to institute (as
> policy) or support (in our infrastructure) a third branch for documentation.

Sounds a good idea to me, but let's see what John Maddock thinks too.

 > 1. It serves the users who want to easily view documentation for a given library's repository.
(They can
> clone that documentation branch).

If there are (and there should be) links to the include and examples folders, then these updated
version are needed too.

> 2. It doesn't require us to put generated documentation output in our main development branches.

For cooperative working on Boost.Math, I found this very tiresome indeed.  it made it impossible to
see the wood for the trees.

> 3. It might even allow you support things like: "If <library> has 'docs'
> branch, don't require it to have a root level index.html."

It would allow anyone who wants 'developing' documentation updates to get them without having to
build the toolchain to get an updated version -  something that I've been kludging round by putting
the built docs (and the other updated folders) on my personal Dropbox.  I'd prefer to stop doing
that.

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]