[boost] Boost Tools (was Documentation Redux (was Re: Boost 1.36.0 releasenotice))

From: Robert Ramey (ramey_at_[hidden])
Date: 2008-08-18 12:33:27

Daniel James wrote:
> 2008/8/18 Dean Michael Berris <mikhailberis_at_[hidden]>:
>>
>> Another option (that I think Dave Abrahams has been doing) is to use
>> RST [0] to make writing/reading the source documentation easier than
>> having to rely on Boostbook+XSLT (which I personally think is a
>> brittle tool-chain).
>
> We haven't a single problem with boostbook or xslt. It's actually
> quite stable. The problems have been with boost build, quickbook
> (possibly due to Spirit), doxygen and latex. Basically everything but
> boostbook. Most of the problems seem to involve poor support for
> windows. I've been testing on linux which is why they weren't
> discovered sooner.

I changed the subject to emphasize that my point isn't about
boost book but rather boost tools.  I picked boost book
as an example in part because I didn't remember who
was responsable for it.

But this illustrates the heart of my proposal.  Let suppose
that the following tools each had its own test suite, library,
review, etc. - the whole boost process.  Here is what we
would have

boost/
    /tools
        /bjam
        /boostbuild (depends upon bjam)
        /boostbook (depends upon fop, doxygen, docbook and ?)
        /quickbook (depends upon boostbook, and spirit)

Now how would things look now?

a) testing on windows would be done - it couldn't be avoided!
b) "Getting Started: would look a lot different.  toos/bjam would
contain the documentation for bjam. and boostbuild would
probably contain the rest of it.
c) The bjam tests would not depend on all the *.jam files
testing of boostbuild (all the *.jam) files would be run
whenever bjam was recompiled
c) boostbuild would be tested independently of quickbook.  I
know this would be helpful because I believe that docbook
has evolved somewhat.
d) quick book would be either tested independently or if
that isn't possible, it would be tested if and only if boostbook
tests passed.

Actually, I know that lots of stuff is sprinkled around the
directories already.  So a lot of it would be just moving things
around.

Here are a number of other advantages

a) I loaded my amended "Library Status" into the directory
which contains "compiler status" because that was a logical
place.  Its looked good on my windows and gcc compilers
but crashed the whole boost test process on certain compilers.
Further, this tool wasn't subjected to any kind of boost
review process.  Is this a good idea?  Application of the
"boost process" would permit ideas for tools to be
subjected to wider scrutiny and improve quality.

b) As noted above, it would be alot easier to find the source
of bugs.

c) It would more clearly delineate responsability.  That is
the author of bjam wouldn't necessarily get sucked in to
issues related to errors in the creation of Jamfiles - unless
he want's to.

d) Documentation would be more logical and easier to
maintain.  The "Getting Started" guide is an example.  It's
a heroic effort and quite well written.  But by trying to
cover bjam and boost build together, it's less clear than
it could be.  It's also much harder to maintain since it
covers such a wide territory in the area of responsability
of various persons.  By factoring the boost toolset in smaller
more orthogonal pieces, efforts such as the "Gettings
Started Guide" would be more productive and more
easily divided amongst several people.

e) It would improve tool usability and range of application.
There are two ways of looking at bjam.  The first is
"Key part of the boost build system".  The second is
"The next/great 'make'".  I believe that it's currently
thought of as the former - which leads to tight coupling
with Jamfiles in boostbuild.  If it were looked at as the
latter, it might be of wider use, this would benefit the
author with the exposure he deserves and lead to a
higher quality better defined, and tested product.

In short, applying the "boost process" to boost tools as well
as boost libraries would lead to a similar set of benefits.

In the above, I've used examples from bjam, boost book
etc.  Truth is I don't know the exact current state of all these tools
so I maybe wrong on some of the details or my examples
may not be the ideally suited to make my point.  If that's
the case - I'm sorry about that.  But, my proposal remains:

The "boost process" for libraries is effective in producing
better libraries and diminishing wasted effort.  Application
of the same process to boost tools would be expected
to achieve comparable results.

Robert Ramey