Re: [boost] Location of generated documentation in Boost tree?

From: Beman Dawes (bdawes_at_[hidden])
Date: 2002-12-30 15:40:11

At 11:43 AM 12/29/2002, Douglas Gregor wrote:

 >Where in the Boost tree should we put generated documentation?

We need to move carefully, and make sure we deal with the needs of several 
different constituents:

* Those who access docs directly via the web site.

The need here is to continue to have well-integrated HTML available.

* Those downloading and using Boost distributions.

A particular concern is the size of the distribution. Also, many people may 
just plain not want docs in formats they don't use.

* Those involved in maintenance activities, including automated scans of 
the directory tree.

These folks (or programs) need to be able to mechanically associate every 
file with a particular library. The bigger Boost gets, the more this 
becomes a necessity. Any library related files not part of the library's 
boost-root/libs/lib-name hierarchy are maintenance problems.

* CVS, and those downloading and using the daily CVS tarball.

We can't change CVS, so we have to deal with its oddities. CVS is great for 
source files, but with generated files CVS can have serious space/size 
problems. IIUC, binary files are a particular problem because they are kept 
in full, rather than diff, form, and rapidly increase CVS space (and 
therefore tarball) requirements.

We need a way with generated files to tell CVS, "yes, do keep this file, 
but only the current version; don't keep history."  Is there a way to do 
that?

 > I'm ready to
 >the use some of the documentation generated from C++XML/DocBook as the
 >documentation for some of my libraries, but I would first like to 
establish
 >
 >some conventions. I suggest:
 >  - We create a directory boost/doc that will contain generated Boost
 >documentation. This directory will have subdirectories for each
 >documentation
 >format (e.g., doc/html, doc/man, doc/pdf).

Would these further be broken down by library? If not, how to avoid name 
clashes?

 >  - We create forwarding pages libs/<library-name>/index.html and
 >libs/<library-name>/doc/index.html that reference the generated
 >documentation.

I'm undecided where the generated html should go, but for the other formats 
my initial feeling is that they shouldn't be in CVS, but rather should be 
available as separate downloads.

 >  - We place the C++XML/DocBook sources for each library in
 >libs/<library-name>/doc_src

That works for me.

 >  - We place the top-level DocBook sources in boost/doc_src

That seems OK, too.

How have others handled similar situations?

--Beman