Re: [HACKERS] So what is the current documentation status? - Mailing list pgsql-hackers
From | Thomas G. Lockhart |
---|---|
Subject | Re: [HACKERS] So what is the current documentation status? |
Date | |
Msg-id | 35D76676.17EFB4AB@alumni.caltech.edu Whole thread Raw |
In response to | So what is the current documentation status? (Tom Lane <tgl@sss.pgh.pa.us>) |
Responses |
Re: [HACKERS] So what is the current documentation status?
Re: [DOCS] Re: [HACKERS] So what is the current documentation status? |
List | pgsql-hackers |
> I need to make some more updates to the libpq documentation, and I'm > confused (again) about whether to work on libpq.sgml or libpq.3. > The last I heard libpq.3 was the primary doco, but I find that > yesterday someone stuck this notice on it: > > : Current documentation for this topic is available in the new > : Programmer's Guide chapter on libpq. This man page is obsolete, > : though in sync with the Programmer's Guide as of 1998/08/15. > > which I'd be willing to believe if it weren't an evident falsehood > (the files are NOT in sync). Do I have to do the syncing? Or should > I just wait for the docs crew to do whatever they're planning to do? The "doc's crew" is me, at least for this stuff :/ I put the note in, since Bruce pointed out that it is difficult to tell which versions of which docs should be maintained. I've also put a _complete_ list of all documentation resources into docguide.sgml, with notes for some of the files on the current status or future prospects. I hope that this helps the developers get on the same page with the direction the docs are going. Unfortunately, most developers don't actually read the docs, and it wouldn't help here anyway especially since recent changes aren't formatted for use yet (see below) :) How are the docs (sources) not in sync? I found some words on PQsetNoticeProcessor() in libpq.3 which were not in an earlier version, and moved those into libpq.sgml. I recall you (or someone else?) submitting some previous docs patches which covered both versions. Let me know the scope of the problem and we can work out the best way to remerge. I'm planning on updating the web page with new, intermediate versions of the sgml/html docs, both online and in tar files. That way people can see the results of contributions. Now, there *is* the issue of whether libpq.3 is appropriate for a man page. I believe it is not, since there is *so* much information needed to understand and since man pages have such a flat structure. Other interface libraries do not have man pages at all, for Postgres and for my system in general. At the moment, the man page comes out to 22 pages of info on my machine. The man pages which are not candidates for v6.4 replacement are those for SQL commands and for programs. The pages for SQL commands are partially replaced by Jose's and Oliver's sgml reference pages, but there is some info in the man pages which needs to move to the User's Guide for "how-to" reading. Don't know if we'll get to this for v6.4. If not then, that leaves something for me to do on v6.5... Let me know how this sounds and what would be easiest for you. I'll see if I can get enough finished on the web site pages to update them with new info today. - Tom
pgsql-hackers by date: