[boost] Re: Re: Broken HTML doc link for boost::function

From: Edward Diener (eddielee_at_[hidden])
Date: 2003-11-12 18:33:54

Douglas Paul Gregor wrote:
> On Wed, 12 Nov 2003, Edward Diener wrote:
>> David Abrahams wrote:
>>> That works until we have to release it I guess (?)
>>
>> Is it a PITA change back to the correct local file link when a
>> release occurs ?
>
> Nope. Just run "bjam --v2" in $BOOST_ROOT/doc and it will overwrite
> the
> local file with the full documentation.
>
>> I also notice that most links are correct to a local file in the CVS
>> downloaded files, but that might reflect fairly stable releases
>> whose docs rarely change.
>
> The HTML filename is the same as the "id" attribute of the DocBook
> element that generates it, so names are as stable as the "id"
> attributes, and BoostBook tries its best to generate good id names
> when they aren't
> supplied. However, it just falls back to pseudorandom names for
> entities
> that are hard to uniquely name (free functions, class template
> (partial) specializations, etc.). The entrypoint for libraries (i.e.,
> doc/html/function.html) should _always_ be the same.

In that case, I think you should generate HTTP addresses when necessary,
even if it is on the Net, for CVS builds and return to local file addresses
for releases. Of course for rarely changing implementations they can be the
same. That way those who download the files from CVS can use the links to
look at the latest docs. If it was too much of a PITA, I would say leave it
alone, but if, as you say, it is easy to switch between them, users who want
to keep up with the latest releases, also want to look at the latest docs
from the downloaded links. I know one can say, "well I am using Mr. Gregor's
boost::signals implementation and therefore I can open my browser to a web
page in my favorites which has the latest doc", but I think it is much
easier just to click on the link and go there.