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

From: Douglas Paul Gregor (gregod_at_[hidden])
Date: 2003-02-18 11:39:44

On Tue, 18 Feb 2003, William E. Kempf wrote:
> Douglas Gregor said:
> > You probably caught me messing with the scripts (and therefore
> > regenerating  the documentation in-place).
>
> Long term, this wouldn't be satisfactory.  The scripts should be generated
> in a seperate location to minimize the amount of time in which the online
> distribution is impacted.

Of course.

> >> 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.
>
> Not everyone will have the tools needed for generating docs.  So I don't
> think this is satisfactory either.

Well, it's one of several options. If you need up-to-date documentation,
you can either generate it, view it online, or download an archive. If
older documentation is acceptable, it'll be in the distribution (and, if
there is agreement on your next suggestion, in CVS).

> A reasonable concern.  But if we keep only release versions of generated
> documentation in CVS, I don't think it will be too severe.  Intermediate
> doc changes would either have to be accessed directly from the web or
> generated locally from CVS.  Seems a fair compromise to this issue to me.

I'm okay with this.

> > 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.
>
> Actually, today it's much different.  There's no Jam files for producing
> the documentation, and several tools are required to run the makefiles
> that not all developers will have on hand.  In the future I expect we'll
> be able to simplify the process, but you have to admit we're not there
> yet.

My intended analogy was with Boost.Build. To use Boost.Build, you need to
compile and install another program (Boost Jam), and perform a build step
to get updated binaries. BoostBook will be the same way: compile and
install another program (XSLT processor) and perform a build step to get
updated documentation. (Granted, Boost Jam comes with the Boost
distribution, but an XSLT processor should not; on the other hand, you
need Jam if you want to use Regex, Thread, Signals, or Date-Time, but
generally nobody is required to rebuild documentation).

> The only issue lies in the transition period when not all documentation
> has been converted to Boost.Book and some of the "static" documentation
> needs to link into a library that's been converted.

... and I don't know how to do that, yet.

> I think there's several of us interested who will be working on this when
> time permits.  But honestly, having it in the sandbox is at least a little
> inconvenient... and to me it makes little sense if some released
> documentation is going to depend on it.

If there are no complains, I would _love_ to move BoostBook out of the
sandbox and into its (presumably) permanent place in Boost CVS.

        Doug