Re: [DOCS] Re: [INTERFACES] libpq & user - Mailing list pgsql-interfaces

> We need to continue making changes only to the src/man/* pages until
> they are converted all to sgml, and then any changes made to src/man/*
> from 6.3.2->current are merged into the sgml source. At that point, we
> switch over to making changes only to the sgml files, and generate
> src/man/* before each release.  We need to move to sgml, but we can't
> start making changes in two places.

Hmm. I guess I don't see the point in asking people to stay away from
the parts of the SGML docs which are _not_ derived from the parts of the
man pages which are actually being converted, especially parts which
were converted long ago. It just makes the document conversion work
harder. I believe that there are only two people actively working on the
reference page conversion to sgml, Oliver Elphick and myself, with
Oliver doing much of the work.

Here is the documentation plan for v6.4:

1) convert the man pages covering SQL syntax and commands to SGML
reference sections. That is roughly half-way completed.

2) convert the man pages covering utility programs to SGML reference
sections.

3) rebuild the User's Guide, Reference Guide, and Administrator's Guide
(the admin guide only if we get release notes and installation
information updated in sgml; I'm hoping you are willing to look at that
Bruce).

A _lot_ of information has already been converted. The libpq
documentation is one of those; I converted it back in March for the v6.3
release, and subsequent doc updates by Tom Lane and others have been
done to the sgml source. That should continue!

In the long run, the "reference docs" will be different from the user's
guide; the reference stuff says "how", and the user's guide says "why".
There will possibly be information currently in the man pages which will
not show up in Oliver's sgml reference pages, and that will need to move
to the User's Guide. There is not a good one-to-one mapping of the man
pages to sgml sources since the man pages tried to stuff everything on
one topic into one section; "real" docs will have a logical structure.

If you have a chance you might want to look through the sgml source
directories to see what is there; it is a lot of stuff. It will _not_ be
trivial to remerge the man page updates, but we said that we would do it
since the alternative was to bring some doc updates to a halt.

At some point the SGML docs will have more and better information than
the current man pages and other available docs. Actually, I think it is
already to that point but since the man pages have been the primary docs
for so long I haven't pushed the transition.

Anyway, if information is already available in SGML then that is where
updates should happen. OK? And as soon as Oliver finishes the SQL
reference pages, we will re-merge and work from the SGML sources for
others too.

Here's an idea: I'll go in and mark the man pages (as a comment in the
top) as to whether they have been or will be converted. Would that help?

Also, if there are any questions on what should be updated, or where,
perhaps checking on the docs list would be helpful? I know I wasn't
available for quite a while (pop server woes), but I should be from here
on...

                       - Tom