Обсуждение: Re: [HACKERS] Last call for docs

> > I can freeze docs in stages; which docs are
> > you planning on touching?
> I have committed all the SGML files I plan to touch except for
> xoper.sgml, libpq.sgml, and possibly start-ag.sgml.
> I had intended to try to write some things about troubleshooting
> postmaster startup failures (out of semaphores, etc) --- there is some
> material in the FAQ but almost none in the SGML files.  I could expand
> the very small "troubleshooting" chapter in start-ag.sgml, but I wonder
> whether you have a better idea.

Uh, sounds like I'd better have an idea, huh? :)

Hold off for an hour or so while I commit my current changes, which
include a bit of a reorg on the Admin Guide. There will be a separate
file, trouble.sgml, which is the troubleshooting chapter. A bit more
info in it (mostly about pg_options and log messages).

> I also want to make some improvements in the main FAQ document and
> in FAQ_HPUX, but I fear I am *still* confused about exactly which
> files represent the master copies.  Bruce?
> Finally, the plain-text FAQ_CVS document is now sadly behind
> cvs.sgml, and needs to be updated.  Is there a better way to
> update it than manually extracting and reformatting plain text
> from cvs.sgml?

istm that there is not need for a flat file FAQ_CVS, and that our web
site and our html and hardcopy docs can do a better job of showing
that info. I had started cvs.sgml from FAQ_CVS, adding some info about
CVSup culled from mailing list messages. Not done yet, but if FAQ_CVS
has not been updated recently it is bound to be more complete since
afaik FAQ_CVS did not even mention CVSup.

I'm planning on cleaning up some of the markup in cvs.sgml and
deep-sixing the CVS_FAQ.
                    - Thomas

-- 
Thomas Lockhart                lockhart@alumni.caltech.edu
South Pasadena, California

Thomas Lockhart <lockhart@alumni.caltech.edu> writes:
>> Finally, the plain-text FAQ_CVS document is now sadly behind
>> cvs.sgml, and needs to be updated.

> istm that there is not need for a flat file FAQ_CVS, and that our web
> site and our html and hardcopy docs can do a better job of showing
> that info.

That works for me ... *except* that last I checked the website's
CVS page was the flat-file version.  If you can update the website
from the SGML version then please do so; otherwise I still want to
update the flat file so that the webpage can be updated.

> I had started cvs.sgml from FAQ_CVS, adding some info about
> CVSup culled from mailing list messages. Not done yet, but if FAQ_CVS
> has not been updated recently it is bound to be more complete since
> afaik FAQ_CVS did not even mention CVSup.

Precisely; the flat file looks not to have been touched since I made
the original version last summer.  You and Marc have put a lot of
good stuff into the SGML version, but none of those updates are
visible on the website.
        regards, tom lane

> > I had started cvs.sgml from FAQ_CVS, adding some info about
> > CVSup culled from mailing list messages.
> Precisely; the flat file looks not to have been touched since I made
> the original version last summer.  You and Marc have put a lot of
> good stuff into the SGML version, but none of those updates are
> visible on the website.

It will be a trivial update to the web site (soon, when I've finished
marking up cvs.sgml so it can build with the rest of the docs). Since
the html generated by our doc system will produce a file "cvs.htm" in
a predictable directory, we can just have a URL on the web page
pointing at that rather than at the current flat file.
                     - Thomas

-- 
Thomas Lockhart                lockhart@alumni.caltech.edu
South Pasadena, California

I have checked in a major extension of xoper.sgml.  I am fairly happy
with the text, but the markup is shoddy to nonexistent.
Do you have time to go over it?
        regards, tom lane

OK, I'm signed off on trouble.sgml as well (but please check the
markup).  I still have to pester Bruce with FAQ updates, but I'm
done with the SGML docs for this release.
        regards, tom lane

> ... done with the SGML docs for this release.

OK. Will look at xoper.sgml soon. Thanks for keeping the docs up to
date!
                 - Thomas

-- 
Thomas Lockhart                lockhart@alumni.caltech.edu
South Pasadena, California