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

[Beman Dawes]

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


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost