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

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

Well, the man pages as they currently exist aren't what we want anyway.
See below.

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

Great. That is encouraging, and matches my impression of where we are
at. As v6.4 gets closer to release, you and others will be wanting to
update docs to reflect new features, so this is a good time to get
coordinated.

> Let me know how we should proceed.

Well, I think we are still short of a common view here, but closing in
on it :)

Remember, the man pages as they exist now will not exist in the future!
The information content in a single current man page does not fit with a
well structured document of any kind. The man pages in the future will
be the same as the sgml reference pages, which summarize syntax and give
examples. If you want the "whys and wherefores" then you go to the
User's Guide, Administrator's Manual, or Reference Manual. This isn't a
bad thing; it is the best way to present information. man pages will
provide quick reminders, while the full docs are meant for teaching and
informing. The man pages have more now because there was no other place
to put new information, so we kept adding more and more to them.

I'm just now generating a list of all files in the tree (as of last
Friday) which are (or might be) documentation resources. I'll send you
the list, and if you would remove any lines which are definitely not
documentation and return the result to me then I will generate an sgml
document/table from it and put it into a section of the "docguide"
appendix, with it marked-up as to what has been converted and what has
not.

I'll update the web site doc information, and generate a new output
version of the html docs for the web site and for our use.

I will indicate which man pages have been directly used in the sgml docs
(libpq, for example) and the other man pages are fair game for continued
maintenance. However, if we already have a place for the same
information in the sgml docs, I will call that out and ask that we try
to maintain both for a short while.

If we get some preliminary work on the man page conversion software done
(so we have some pretty good examples which are close to adequate) then
we can make the "hard switch" to sgml.

OK? Let me know if these suggestions are headed in the right direction,
and if so which ones you would like to support.

Talk to you soon.

- Tom