Re: [DOCS] Re: [INTERFACES] libpq & user

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

Yikes.  I did not know.  Do we have a solution for this, or are we going
to maintain multiple version of this information?

I can't imagine trying to maintain muliple versions of this information.

I did look at the libpq sgml version, and it looks identical to the man
version, though of course, I have been updating the man version and not
the sgml version.


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

Yes, I want the sgml to be kept up-to-date.

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

Yep, a guide to what is converted would be great.  We need to know where
to make changes for each section.  If we need to make changes in two
places, let us know.  If one file is generated from another, let us
know.

For example, I added a missing part of a query structure because we not
mention the AS part of DISTINCT.  I added it the SELECT man page and
psql help.  I probably missed something in sgml.  Maybe we should make
only changes in man pages, and before each release, we merge those
changes into the sgml?  I am afraid only a few people will know where
the sgml changes are to be placed.  I would be glad to add it to my
release checklist and make sure someone does it before each release.

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

Oh, this is what I was hoping not to do.  Going too long with changes
only to sgml could be a problem.  People use the man pages from the
command line.

Again, how about keeping the man pages up-to-date, and merging the diffs
before every release until we have a plan to move sgml to man.  Perhaps
we should consider moving man to sgml.  I know I can generate html and
postscript from man pages very easily.

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

Yes, we both see the same problem.  Let's agree on how to handle things
consistently.  Perhaps I can keep the sgml changes up-to-date with the
man pages.  However, I need to do it at fixed periods, like before each
release, so I know people are not converting old documents as I am
moving in changes from the man pages.  If they work on 6.3.2 sources up
until the 6.3.2 beta, I can then update sgml, and they can start
converting again with the 6.4 sources, which I will not touch until 6.5.

If people took the current man version of a file, converted it into
sgml, and deleted the old man file, that would be even better.  No
duplication, but then you have to have a way to generate the man file,
and currently we don't.

I just did a context diff of the man directory since 6.3.2, and I have
5k lines of diffs.  Most of them are additions of underscores in man
pages names.  This was done so the man->html could create proper links
for man pages.  The rest are small wording changes or new libpq
functions.  Not much.

Let me know how we should proceed.

--
Bruce Momjian                          |  830 Blythe Avenue
maillist@candle.pha.pa.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)