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

From: Douglas Gregor (gregod_at_[hidden])
Date: 2003-02-17 18:24:42

On Monday 17 February 2003 04:49 pm, Beman Dawes wrote:
> At 02:00 PM 2/17/2003, Douglas Gregor wrote:
>  >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.

You probably caught me messing with the scripts (and therefore regenerating 
the documentation in-place). 

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

Well, you'll have the doc source on your machine, and can generate whatever 
format you want.

>  >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?

The documentation isn't big (~650k, much smaller compressed). However, 
generated documentation tends to change a lot even with minor changes to the 
input, so unless someone has a good way to tell CVS "don't track any history 
for this file" then the CVS repository will get huge with the histories of 
these generated files. 

>  >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.

Sure, but we also have documentation that's inconsistent across libraries, not 
indexable, and unavailable in any format other than HTML. Our current simple 
model is simple for simple uses, but doesn't extend to any more advanced 
cases. 

> 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.

It's my hope that developers will adopt BoostBook for their own documentation. 
Then any time they want to be sure their local copy of the documentation is 
up-to-date they just regenerate the format they want locally. It's really not 
much different from rebuilding, e.g., libboost_regex with Boost Jam.

> 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?

If I can stabilize the filenames a bit, it _might_ be plausible to use CVS 
along with the "cvs admin -o" command, which can erase completely certain 
revisions of a file. It would be possible for a little grim reaper script to 
come by and erase all but the most recent version of each file on a nightly 
basis, after checking in the new version. Sounds tenuous to me...

>  >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

It's easy to link out of the generated documentation to static documentation 
(of course), and it's much easier to link amongst entities in BoostBook than 
in HTML. For instance, <libraryname>Tuple</libraryname> will link to the 
Tuple library, regardless of where the HTML is (even if it isn't generated); 
<functionname>boost::ref</functionname> will link to the function boost::ref, 
regardless of where it is. Broken link detection is built into the BoostBook 
XSL, because it emits a warning whenever name lookup fails (and won't 
generate a link). What we do now is much more involved: find the HTML file 
and anchor documenting the entity we want to link, put in an explicit link <a 
href="...">, and checking the links will have to be run manually prior to a 
release. 

Using generated documentation has some up-front costs: you'll need to get an 
XSLT processor, and maybe some stylesheets (if you don't want them downloaded 
on demand), and probably run a simple configuration command (now a shell 
script; will be in Jam eventually). 

The time savings from the generated documentation will come in little pieces: 
you won't need to keep the synopsis in sync with the detailed description, 
you won't need to keep a table of contents in sync, keep example code in a 
separate test file in sync with the HTML version in the documentation, or 
look up a link in someone else's library. BoostBook is meant to eliminate 
redundancy (except for XML closing tags; ha ha), and all the time we waste 
keeping redundant pieces in sync.

There's an unfortunate Catch-22 with all this: to smooth the BoostBook 
learning curve would require further integration with the Boost CVS 
repository (not the sandbox), but we shouldn't integrate with Boost CVS until 
BoostBook has been "accepted" (whatever that means for a tool). But 
"acceptance" requires, at the very least, more developers to hop over the 
initial hump and to start seeing the benefits of BoostBook.

        Doug