Re: Docs refreshed - Mailing list pgsql-hackers
From | Thomas Lockhart |
---|---|
Subject | Re: Docs refreshed |
Date | |
Msg-id | 38E7F212.D32BE3FB@alumni.caltech.edu Whole thread Raw |
In response to | Re: Docs refreshed (Peter Eisentraut <peter_e@gmx.net>) |
List | 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@alumni.caltech.edu South Pasadena, California
pgsql-hackers by date: