Re: [HACKERS] Release date and docs - Mailing list pgsql-hackers

> > An alternative which I would support but am not yet as satisfied with
> > would be to decouple the hardcopy docs from the release package.
> Totally apart from any schedule considerations, I think it would be good
> if the derived forms of the docs (the .ps files and tarred .html files
> in pgsql/doc) were decoupled from the source distribution.  In
> particular, remove those files from the CVS archives and distribute
> them as a separate tarball rather than as part of the source tarballs.
> This'd be good on general principles (derived files should not be in
> CVS) and it'd also reduce the size of snapshot tarballs by a couple of
> meg, which is a useful savings.  Since the derived docs are always a
> version behind during the runup to a new release, I don't see much
> value in forcing people to download 'em.

These are good points.

> A further improvement, which oughta be pretty easy if the doc prep tools
> are installed at hub.org, is to produce a nightly tarball of the derived
> docs *generated from the currently checked-in sources*.  As someone who
> doesn't have the doc prep tools installed locally, I know I would find
> that very useful.  Right now, I have the choice of looking at 6.4.* docs
> or raw SGML :-(.

Really? We've been doing exactly as you suggest for several months now
:)

Look in ftp://postgresql.org/pub/doc/*.tar.gz for snapshot html, and
the web site docs are just untarred versions of the same thing. These
are all generated on a nightly basis directly from the CVS tree. We
should probably split those off into a developer's area rather than
have those be the *only* copy of web site docs, but it was a start.

Also, on hub.org ~thomas/CURRENT/docbuild is the script for the
nightly cron job, and my tree is set up to allow "committers" to use
it. If you use it from my tree, be sure to have your umask set to "2"
to allow group mods.

It's pretty nice having this run daily, because I get the cron log of
the run and can see when something new breaks the build from sgml.

> If you don't want to change our distribution practices to the extent
> of having separate source-code and doc tarfiles, then it'd at least be
> a good idea to regenerate the derived docs as part of the nightly
> snapshot-building run, so that the snapshots contain up-to-date derived
> files rather than historical artifacts...

Good idea, but we don't want to do CVS updates on those big tar files.

What do other folks think??
                     - Thomas

-- 
Thomas Lockhart                lockhart@alumni.caltech.edu
South Pasadena, California