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

> That is the problem.  There is no indication what has been converted
> and what has not been converted.  If you move to the sgml for some,
> you have to merge the post-6.3.2 man changes into sgml.
> With so many people involved, it seemed best to keep all changes in
> one area until everything was moved over, then do a diff against 6.3.2
> and merge them.  We can then auto-generate the man pages from sgml.

We do not currently have the mechanism for generating man pages from
sgml, though it is theoretically possible to do. Man pages are only one
of the important information formats (and in fact the least important of
them because of the limitations in man page structure and the flat
organization). See below.

> Oliver is working from the base 6.3.2 sources, so he has a nice stable
> base to do the conversions.

Not really (though I had forgotten why). See below.

> People are submiting changes from the man pages, and I install them.

That's fine. But this person was asking what to change, and you directed
them to the man pages for something converted 4 months ago. That's why I
spoke up. Not complaining, just trying to work something out here :)

> Again, keep it consistent for everyone, or we will spend hours trying
> to get it straight.

I'm trying to. I've already spent over a hundred hours getting the sgml
docs to where they are now. Lots has been converted already. Some still
needs to be done. We don't disagree on the facts, or on the goals. But
we do have a coordination problem here, and I'd like to try addressing
that.

If I generate a list of _all_ online document resources, and their
current state (converted, unconverted, not a candidate for conversion,
etc) would the hackers and docs people be willing to look at that when
making changes? Seems like that should help coordinate things.

For example, release notes and installation instructions have been
converted. Docs on libraries and interfaces have been converted. Man
pages are not actually being converted by Oliver, now that I think about
it; Jose' Soares had written a really nice text-based new version of
_reference_ information for each of the commands, perhaps using the man
page sources as a resource. Oliver is converting those text-based docs
to sgml. But the man pages try to span two separate documents: a User's
Guide and a Reference Manual. On their own, the man pages are not
suitable for a simple conversion, but must be split. We will need to
make sure _information_ in the man pages ends up in the right place. The
replacement man pages will be from the reference information, not the
User's Guide, so will not be identical to the current man pages.

One possible outcome of the docs conversion for the v6.4 release is that
the sgml sources, the html online docs and the Postscript hardcopy are
up to date for v6.4, and the SQL command man pages are up to date for
v6.3.x only. I think that this should be acceptable, and that we can
then focus on getting a man page output from the sgml sources for v6.5.
Brandon has expressed ongoing interest in working on this, and I have
some ideas for doing a "quick and dirty" stopgap. You are asking a lot
of one or two or three people to do _all_ of the docs conversion, _and_
the re-syncing of old docs, _and_ getting 3 separate output formats in
the span of 4 months. Especially when the docs are hundreds of pages and
the people are also contributing to the code itself!

Anyway, the issue really seems to have come up over a single topic
(libpq) which has _not_ been a coordination problem since its conversion
in February. So it isn't _that_ big a problem, and a
conversion/coordination list would seem be help address the lack of
information about what the current state of things is.

We both see a problem from two different angles, so let's try to work
out a solution :) I've been working on code for v6.4 for a bit now, but
am willing to stop that (I have most of my v6.4 coding goals
accomplished) and re-focus on docs.

                        - Tom