[Boost-docs] questions about boost documentation

Subject: [Boost-docs] questions about boost documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2007-08-14 16:56:40

In the beginning ....

It was pretty simple.  Each library had a directory,
In each library there was a directory named "docs".
and in that subdirectory there was a bunch of linked html files.

Now in the improved system - I don't know what there is.
Sometimes I get bumped over to www.boost.org/...

I find a directory in the boost_root/doc/html .. and ...

When I look at a quickbook document chapter - very
nice looking - but it starts out with chapter 24 or something.
What's up with that?

And generating local documentation for your system - like you
need if you want to have it available if you're not near a wi-fi
connections is a fragil process that takes a huge amount of time.
And the recommended way to do it doesn't permit one to do it
for just one or the other library - or test the process on just one
library.

Note that I've only spent some time looking at this.

Wouldn't it be much, much easier to organize things in
the following way?

boost_root
    libs
        serialization
            build...
            src...
            test...
            example...
            performance ...
            doc
                 html
                      files written by hand or generated by boost book
                 pdf
                      files made by ? some method or by boost book
                 boost book
                      Jamfile.v2
                      files made by hand or by quickbook
                 quickbook
                       Jamfile.v2
                       quickbook files

boost entry webpage
boost document navigator - frame with links to all library documentation.

This would permit building and maintainence of library documentation to
be independent of that for other libraries.  It doesn't conflict with the 
way
things were "In the beggining".  It would make it much easier
to convert to a new, "improved" system on a library by library basis.  It
would permit users to a subset of the documentation if they desired.
It provides a fallback if the boost documentation build is improved
beyond functionality.  It permits various distribution options - with
and without pre-built html, pdf. or with build directories
It would permit one to use the system to generate documentation for
his non-boost projects.  I would be easy to convert to this system.

Robert Ramey