Re: [HACKERS] So what is the current documentation status?

> 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