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

> 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.

You have to do a cvs diff for the file from the time you created
libpq.sgml to current. You will see lots of things.

>
> 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

I really like libpq.3 as a manual page. I use it for quick reference.
I have printf as a manual pages, and that is a library function. How is
libpq.3 different? Perhaps we could remove the examples, but that is
really not going to save us much.

> 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.

--
Bruce Momjian | 830 Blythe Avenue
maillist(at)candle(dot)pha(dot)pa(dot)us | Drexel Hill, Pennsylvania 19026
+ If your life is a hard drive, | (610) 353-9879(w)
+ Christ can be your backup. | (610) 853-3000(h)