Boost logo

Boost :

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


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk