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

From: Beman Dawes (bdawes_at_[hidden])
Date: 2003-02-17 21:01:50

At 06:24 PM 2/17/2003, Douglas Gregor wrote:

 >On Monday 17 February 2003 04:49 pm, Beman Dawes wrote:

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

Where is this documented? How long does it take? It there a way to only 
regenerate the files that change, or does the entire Boost docs have to be 
generated?

I'd like to give it a try, but need pointers to docs. I don't even have an 
XML editor at the moment, let alone any of the other tools.

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

Understood. So we need to come up with some other smooth way of updating 
the  documentation HTML files on developers machines to match the CVS 
state.

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

A system that is too cumbersome to use isn't really more advanced, it is 
just a mess. We need to make the new system as easy to use as the old one 
or only the masochists will use it.

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

I don't mind some added costs as long as the system is easy to use.

--Beman