Re: [boost] Any, Function, and Signals documentation

From: Beman Dawes (bdawes_at_[hidden])
Date: 2003-02-17 16:49:09

At 02:00 PM 2/17/2003, Douglas Gregor wrote:

 >On Monday 17 February 2003 11:21 am, Beman Dawes wrote:
 >> Ouch! That means the current HTML docs for these libraries aren't
 >> available to Boosters who depend on CVS to keep up-to-date,
 >
 >They're always available here, regenerated nightly in HTML, DocBook, FO,
 >PDF, and man pages:
 >  http://www.cs.rpi.edu/~gregod/boost/doc/html/libraries.html

That really isn't very satisfactory. In the last hour for example, pages on 
that web site have only been available sporadically. One minute access is 
OK, the next minute the site or page can't be found. No problems with other 
popular web sites.

Having the docs locally on my own machine is just a lot more satisfactory. 
Cheaper, too (my Internet access is metered service.)

 >Extract http://www.cs.rpi.edu/~gregod/boost/doc/boost-doc-html.tar.gz 
into
 >$(BOOST_ROOT) and you'll have a full release.
 >
 >> I think you need to develop a procedure so that a documentation change 
is
 >> reflected in the CVS doc/html files right away.
 >
 >We don't want to stick all of the generated HTML into CVS (too big).

If it is too big for the regular CVS, isn't it too big for the distribution 
too? How big is big?

 >Documentation changes will show up the next morning at the aforementioned 

 >site. I'd like to add a link to this generated documentation on the main
 >page (so it is obvious that both the current release documentation and 
the
 >current CVS documentation are available on-line).

Seems like a step backward. We have a simple model now. Click on CVS 
"update" (or equivalent in your favorite client) and you get the latest 
version of all files. CVS is the only tool needed.

It really isn't practical for many Boost developers to download a whole 
tarball and unpack it every time they want to be sure their Boost tree is 
up to date. Unpacking doesn't do things like getting rid of obsolete files 
either. Need a way to just download the changed files - and that sounds 
like CVS to me.

So I think we need to figure out a way for generated docs to work in the 
context of CVS. Or am I just being too picky?

 >They will only break if the links try to link inside the documentation
 >files,
 >e.g., to a specific anchor. Links that go directly to the library's entry 

 >point (index.html) will find the meta-refresh index.html that redirects 
to
 >the generated documentation. I've checked with inspect: nothing broke.

Well, but that's because there are only three libraries being generated 
now.  Some lib's docs do a lot more linking to other boost docs.

--Beman