[Boost-users] [Boost documentation] was Re: serialization1.36.0 extended_type_info exit issue(s)

Subject: [Boost-users] [Boost documentation] was Re: serialization1.36.0 extended_type_info exit issue(s)
From: Robert Ramey (ramey_at_[hidden])
Date: 2008-10-11 14:46:15

>From the boost build / merge
>> The same goes for boost documentation which I would
>> really like to use.  But I don't feel confident that "it
>> just works"
>
> Heh, there's nobody here who would disagree with that.

To me the sad part of this is

a) that I personally have a HUGE
need for something like the boost documentation system
in my own projects.

b) I feel that if it were subjected to the
normal boost testing regimen, it would be a dependable
product by now. Or at least we would have a good test
matrix which I could use to know what aspects I can't
use in my environment.

What I would like to see is:

a) a directory structures that looks like one of the following

.../libs
    serialization
        doc
            *.html // i.e. same as we have now

or

.../libs
    serialization
        doc
            Jamfile.v2 (optional)
                pdf (optional - built on demand by bjam from boost book)
                    *. pdf files
                windows html help (optional - built on demand by bjam from 
boost book
                    *.chm files
                html (included in distribution - optionally (re-built) by 
bjam from boost book)
                    *.html files
                boostbook (hand prepared - or built by bjam from quickbooks)
                    * .. boost book filles
                quickbooks (optional - hand prepared)

For any library I was interested in I could review the html or build the 
version I needed by
going to the doc directory and invoking something like

bjam -???? or bjam -????? pdf

And if I want to spend $300 on a proprietary package, I could do that as 
well - just
as I do for my compiler.

But to do this the following tools have to be tested on a regular basis like
the libraries are:

a) boostbook -> pdf
b) boostbook->windows html help
c) boostbook->html
d) quickbooks->boostbook

so there would be a couple of "new" tool/library directories

../tools
    boostbook
        build
            Jamfile.v2
        doc
            boost book documentation
        src
            ...
        test
     quickbooks
            ... same as above

And of course these tests would be part of the normal test matrix.

I realize that this sounds like a lot of effort.  But then a lot of the 
above
is already in boost somewhere so a large part of the effort would be 
shuffling a
round stuff that's already in there (boost).

I believe that reorganizing boost documentation along the above  would
result in a robust and very popular tool/library.

Robert Ramey