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

From: William E. Kempf (wekempf_at_[hidden])
Date: 2003-02-18 11:56:59

Douglas Paul Gregor said:
> On Tue, 18 Feb 2003, William E. Kempf wrote:
>> Douglas Gregor said:

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

What are other's thoughts on this compromise?

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

This a minor difference here, though.  The bjam executable boot straps
fairly easily on most platforms.  XSLT processors aren't quite as
convenient.  At least that was my experience that last time I tried to do
DocBook stuff on a Windows box (with out Cygwin).  Things may have
improved in this regard, and if not, I'm sure we can improve things
ourselves, but I'm nervous that we're not ready for this yet.

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

Which is the single biggest concern with the migration to Boost.Book. 
Here's where I see the real catch-22, and I'm not sure how to deal with
it.

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

Well, I'm in favor of that, since we're moving at least some of the
documentation to Boost.Book with this release (or so I gathered).  So
what's the group opinion on this one?

-- 
William E. Kempf