> > Another thing we should think about is to not tar.gz the documentation
> > files. That way we could create useful incremental diffs between releases
> > later on. Any comments here?
> I've never figured out why we do that.
Well...
> Since the thing is going to be
> inside a tarball anyway, there's no possible savings from distributing
> the built doco that way, rather than as ordinary files.
A couple of reasons, historically:
1) I was building docs locally, and moving them across to postgresql.org
over a modem. It wasn't for another year (?) before postgresql.org could
build them locally.
2) The first html docs were available before a release, and they needed
to be distributed.
3) We put the docs into cvs, but the jade/docbook output did not have
predictable file names. So each release would require wiping the output
docs and somehow guessing which files were obsolete and which were new.
4) We would have to install these individual files, and we didn't have a
technique for installing docs. Untarring seemed compatible with (2) and
(3).
Anyway, since we no longer put the docs tarball into cvs, then we could
rethink the techniques. Peter, you seem to have done enough work on this
to have an opinion, so what exactly would you prefer for packaging? I
recall that an unpacked tree was the suggestion??
I think that *requiring* that the html docs be built in place to effect
a release is an extra toolset burden that we should not accept. The fact
that the docs tools work well on postgresql.org as well as on other
machines is something to be enjoyed, not put into the critical path ;)
- Thomas