Boost logo

Ublas :

Subject: Re: [ublas] [bindings] Which Bindings should I direct my users to? Boost proper?
From: Thomas Klimpel (Thomas.Klimpel_at_[hidden])
Date: 2010-07-04 10:23:28

Rutger ter Borg wrote:
> Thomas Klimpel wrote:
> > Question: Which boost version (=quickbook version) should I use to
> > generate the html? I suggest going with the latest released boost version
> > (=1.43 currently), as that version won't at least not change daily.
> I used trunk for this. Do other tools influence the generated html, like the
> docbook version, installed Boost templates for this, etc.? IOW, perhaps the
> boost version isn't the cause of different-looking results.

For my different attempts, only the quickbook version changed, and caused all the avoidable differences. In addition to the avoidable differences, some GUID's always change, but these are not generated by quickbook. I guess the GUID's are generated by xstlproc, but I'm not sure about this.

> > Summary of questions from above:
> >
> > - Which boost version (=quickbook version) should I use to generate the
> > html?
> That's up to us :-). Could be current (1.43) or trunk. What Boost version do
> you use for unit testing?

I used trunk in the past, but have already been bitten by this. One problem is that patches that cause regression test failures on trunk simply don't get merged to release, but the regression test failures on trunk are considered more or less acceptable. I was bitten (=lost more than 4 hours) by multi_array, which wasn't merged to release since 2007 (=released version 1.34.1). I recalled then that Robert Ramey had continuously been preaching that regression testing should be done against the release branch. Another problem with trunk is that users will report bugs against released versions, and these correspond much more closely with the release branch than with trunk.

> I tend to keep a copy of Boost trunk for this
> stuff; I don't mind checking out a release branch for this. But perhaps this
> doesn't solve the problem of different-looking results.

I think, using the release branch is a good compromise (= I will use the release branch from now on to generate the html documentation). It's less time consuming than using the latest released version, and provides essentially the same benefits. As unbelievable as it sounds, quickbook had more than 20 changes on trunk since the 1.43 release. And even so it was merged to the release branch on 23. June 2010, the current quickbook version on trunk has collected enough changes since then to again produce different-looking results. And it's even OK that way, because Doug Gregor once wrote "We're calling the development branch the trunk".

> > - Do you approve the new name "VectorView" for "Vector" arguments that
> > support general strides?
> So, a VectorView is one that supports strides, and a Vector is one that
> doesn't? Hmm. Both may be views, e.g., a contiguous column or row. What
> about "Vector" (=generic) and "ContiguousVector" (=one with stride 1), isn't
> that more precise?

I know that both may be views. I first named them "StridedVector", but that broke multiple places in the code generator, and I didn't even liked that name. And "ContiguousVector" has exactly the same problems: It requires multiple changes to the code generator and I don't even like that name. The std valarray header uses the name "slice_array" for what I called "VectorView". Using "VectorSlice" instead of "VectorView" would be easy, using "SliceVector" would be a bit more difficult. I don't know for sure whether "SliceVector" is a better name than "VectorSlice" or "VectorView", but I fear it is indeed (any native speakers here?).

I wouldn't use the name "Vector" for something that supports strides, because that would be unexpected (nobody unaware of the convention would be able to guess this meaning) and arbitrary (a vector with distributed storage would be even more general).

> > Here is David Abrahams' answer:
> > [snip]
> Looks like a smart solution! I can not think of many problems that could
> occur -- perhaps except with the instantiation of an adaptor?
> > - Should we omit nearly all overloads, because they are no longer
> > important now?
> I don't see any problem with this.

So we will probably omit them (sooner or later, as I probably first want to do something productive before removing perfectly well working functionality).

> > - How often should the generated html be checked in? I would tend to
> > update it only very infrequently, as some GUID's always change and cause
> > the checkin to be really huge.
> I agree, another alternative could be if we could upload it into some web
> space somewhere. Svn repository access isn't the best tool for this job

I fear this statement is more correct than you may be aware of. With the release of lapack 3.2.2, the design of the "lapack/explore-html" page has been changed, so that all of our lapack source links are broken now. We could fix this by changing "lapack/explore-html/sXXXX.f.html" into "lapack/single/sXXXX.f", but a more robust fix would be to upload our own versions of these files to some web space. However, for the moment I prefer to just wait until the netlib page of lapack has settled into a longer lasting state, and then do the necessary adjustments to our links. And I have to admit that I have no experience at all with web space.

> [snip more good stuff]

Thanks. Sorry for taking so long to answer.

> > I have attached my current TODO list (fixme.txt), but I won't wait until
> > it's empty before starting to write documentation.
> I will see if there's something I can fix immediately in the fixme file.

In the meantime, I addressed the "- fix clapack routines (no workspace)" and the "- fix gbtrf/gbtrs, gbsv (banded solve)" issue.