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