Skip site navigation (1) Skip section navigation (2)

Re: Docs refreshed

From: Thomas Lockhart <lockhart(at)alumni(dot)caltech(dot)edu>
To: Peter Eisentraut <peter_e(at)gmx(dot)net>
Cc: Postgres Hackers List <hackers(at)postgresql(dot)org>
Subject: Re: Docs refreshed
Date: 2000-04-03 01:21:22
Message-ID: 38E7F212.D32BE3FB@alumni.caltech.edu (view raw or flat)
Thread:
Lists: pgsql-hackers
> > Just as you, I assume that people using html read the integrated doc.
> Btw., the fact that the print docs are in US Letter format makes them
> slightly beyond useless for the rest of the world. :( I still think that a
> 200 page document is not any less unwieldy than a 600 page one. There's
> gotta be an option to only print pages x through y either way.

<bad attitude>
Hmm. I'm glad you appreciate the hundreds of hours of work I've put
into the docs :/ And I haven't seen anyone else stepping up to
providing hardcopy-style docs for "the rest of the world". And I
personally value hardcopy docs any time I try to learn something (as
opposed to just refreshing my memory on a detail) and think that it is
important for others too.
</bad attitude>

> Considering that this is pretty much what's holding up releases, would it
> be possible to consider not putting the postscript docs in the
> distribution and just put them on the ftp server at your convenience (and
> in A4 as well) for those who choose to get it? Not to break your heart or
> something but thinking practically ... :)

OK, there is a little known secret here: the docs are *not* holding up
the release. But, the release will be held up until both docs *and*
the release are ready to go, and at the moment neither are. In fact, a
fundamental part of our release cycle is that, for the last couple of
weeks before the actual release, the project is "waiting for docs",
and during that time, the old adage that "idle hands do the devil's
work" comes into play and people start poking at the release, trying
things, putting it into production, maybe, trying it on all platforms,
etc etc, and we find a few extra bugs and get our platform reports
finalized. And all of this is essential for a quality release. So
don't believe the docs story too much, but don't try doing away with
the sham either ;)

btw, I hadn't fully realized the above until you started poking at it,
so thanks :)

> Also don't put them in the CVS tree. They're just wasting space since
> they're out of date and not really useful for developers.

You haven't yet suggested enough other mechanisms to adequately
replace the current scheme, but I'll do it for you, under separate
cover sometime soon.

> In the same spirit I'd suggest not including the html tars in the CVS tree
> either. In the distribution I would like to have them *untarred* so users
> can browse them before/without installing. But for that they can be
> generated when making the distribution (make -C doc postgres.html, not too
> hard but we'd need to use a separate build dir), no need to keep out of
> date copies in CVS.

Well, the copies *aren't* out of date for the corresponding release
version, so that isn't the issue afaict. tar vs untar doesn't seem to
be a big issue either, though the tarball is pretty much required if
the html is in cvs since the names of the html files only occasionally
reproduce from one rev to the next (note the large number of random
generic names for internal portions of chapters).

                       - Thomas

-- 
Thomas Lockhart				lockhart(at)alumni(dot)caltech(dot)edu
South Pasadena, California

In response to

pgsql-hackers by date

Next:From: Tom LaneDate: 2000-04-03 05:32:20
Subject: Re: 7.0 release notes should call out incompatible changes more clearly
Previous:From: Ryan KirkpatrickDate: 2000-04-03 00:35:24
Subject: Re: Call for porting reports

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group