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

[Beman Dawes]

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


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost