Re: alternative DB locations

Bob Parkinson wrote:
>
> On Tue, 3 Oct 2000, Jeff Hoffmann wrote:
>
> :-)
>
> > RTFM. this is a pretty common problem. the environment variable
>
> I did. I've got the FM in front of me, and it does not mention
> this. Cheers.
>

not to be pedantic, but just to make sure, i looked in the 7.0 docs and
it says it plain as day on the "alternate locations" section from the
admin guide, second paragraph "This
environment variable must have been defined before the backend was
started" this is an incredibly common question for being spelled out
that directly in the documentation. this statement should probably be
bold or italic or otherwise emphasized, since it is such an important
point and apparently very easily overlooked. maybe tom lockhart & the
other document editors will look kindly on this suggestion to alleviate
some new user headaches in the future.

--

Jeff Hoffmann
PropertyKey.com

Jeff Hoffmann <jeff(at)propertykey(dot)com> writes:
> not to be pedantic, but just to make sure, i looked in the 7.0 docs and
> it says it plain as day on the "alternate locations" section from the
> admin guide, second paragraph "This
> environment variable must have been defined before the backend was
> started" this is an incredibly common question for being spelled out
> that directly in the documentation. this statement should probably be
> bold or italic or otherwise emphasized,

Actually, first it should be *corrected*. It should say "... defined
before the POSTMASTER is started". Or even more directly, "... supplied
in the postmaster's environment variable set".

As is, it can reasonably be read that you just have to define the variable
in your own environment before starting a psql session (which starts a
backend of course).

The critical distinction that people aren't making is between their
client environment and the postmaster/backend environment, and the
existing text doesn't seem to help them.

regards, tom lane

Jeff Hoffmann writes:

> not to be pedantic, but just to make sure, i looked in the 7.0 docs and
> it says it plain as day on the "alternate locations" section from the
> admin guide, second paragraph "This
> environment variable must have been defined before the backend was
> started" this is an incredibly common question for being spelled out
> that directly in the documentation. this statement should probably be
> bold or italic or otherwise emphasized, since it is such an important
> point and apparently very easily overlooked. maybe tom lockhart & the
> other document editors will look kindly on this suggestion to alleviate
> some new user headaches in the future.

The documentation for 7.1 emphasizes this point a bit more. See

http://www.postgresql.org/docs/admin/managing-databases.htm#AEN2065

If something is still less than optimially clear, please submit a
suggested new wording.

--
Peter Eisentraut peter_e(at)gmx(dot)net http://yi.org/peter-e/

Peter Eisentraut wrote:

> The documentation for 7.1 emphasizes this point a bit more. See
>
> http://www.postgresql.org/docs/admin/managing-databases.htm#AEN2065
>
> If something is still less than optimially clear, please submit a
> suggested new wording.

this is a lot better, although i'm still not a big fan of the online
documentation. has someone brought up the "annotated documentation"
format like that's used on the php web site? i think it's an excellent
combination of documentation, FAQ, and hints that makes it a lot easier
to find answers than the standard "RTFM - read FAQ - search mailing
lists".

--

Jeff Hoffmann
PropertyKey.com

On Tue, 3 Oct 2000, Jeff Hoffmann wrote:

> Peter Eisentraut wrote:
>
> > The documentation for 7.1 emphasizes this point a bit more. See
> >
> > http://www.postgresql.org/docs/admin/managing-databases.htm#AEN2065
> >
> > If something is still less than optimially clear, please submit a
> > suggested new wording.
>
> this is a lot better, although i'm still not a big fan of the online
> documentation. has someone brought up the "annotated documentation"
> format like that's used on the php web site? i think it's an excellent
> combination of documentation, FAQ, and hints that makes it a lot easier
> to find answers than the standard "RTFM - read FAQ - search mailing
> lists".

Yeah, but it's currently a matter of available time. When I get a few
things cleared up I'll give it a look.

Vince.
--
==========================================================================
Vince Vielhaber -- KA8CSH email: vev(at)michvhf(dot)com http://www.pop4.net
128K ISDN from $22.00/mo - 56K Dialup from $16.00/mo at Pop4 Networking
Online Campground Directory http://www.camping-usa.com
Online Giftshop Superstore http://www.cloudninegifts.com
==========================================================================

Jeff Hoffmann writes:

> has someone brought up the "annotated documentation" format like
> that's used on the php web site? i think it's an excellent
> combination of documentation, FAQ, and hints that makes it a lot
> easier to find answers than the standard "RTFM - read FAQ - search
> mailing lists".

As a PHP user I find that kind of helpful, because the PHP documentation
is really bad, or at least it was last time I looked.

As a PostgreSQL documentation writer I don't think this is such a good
idea. It would create all kinds of alternative, unchecked,
non-authorative information that would be distributed under the official
PostgreSQL banner.

If users have a suggestion, correction, or improvement for the
documentation, all they have to do is write us and someone will surely
integrate it.

Additionally, I imagine a number of technical and logistical problems with
this. The documentation is organized logically into chapters, sections,
etc., not in terms of HTML pages. Other formats (ps, pdf, dvi, man) would
not carry the benefit of these annotations. Even just a new stylesheet
for HTML might invalidate the whole database.

--
Peter Eisentraut peter_e(at)gmx(dot)net http://yi.org/peter-e/

This has discussed before (I brougt it up) and there was talks of using
the http://openacs.org/ site to do this. But I don't think there has
happened anything on that matter.

I think we should either use the openACS site, or write our own
extension of the manual in PHP.

Poul L. Christiansen

Peter Eisentraut wrote:
>
> Jeff Hoffmann writes:
>
> > has someone brought up the "annotated documentation" format like
> > that's used on the php web site? i think it's an excellent
> > combination of documentation, FAQ, and hints that makes it a lot
> > easier to find answers than the standard "RTFM - read FAQ - search
> > mailing lists".
>
> As a PHP user I find that kind of helpful, because the PHP documentation
> is really bad, or at least it was last time I looked.
>
> As a PostgreSQL documentation writer I don't think this is such a good
> idea. It would create all kinds of alternative, unchecked,
> non-authorative information that would be distributed under the official
> PostgreSQL banner.
>
> If users have a suggestion, correction, or improvement for the
> documentation, all they have to do is write us and someone will surely
> integrate it.
>
> Additionally, I imagine a number of technical and logistical problems with
> this. The documentation is organized logically into chapters, sections,
> etc., not in terms of HTML pages. Other formats (ps, pdf, dvi, man) would
> not carry the benefit of these annotations. Even just a new stylesheet
> for HTML might invalidate the whole database.
>
> --
> Peter Eisentraut peter_e(at)gmx(dot)net http://yi.org/peter-e/

> Jeff Hoffmann <jeff(at)propertykey(dot)com> writes:
> > not to be pedantic, but just to make sure, i looked in the 7.0 docs and
> > it says it plain as day on the "alternate locations" section from the
> > admin guide, second paragraph "This
> > environment variable must have been defined before the backend was
> > started" this is an incredibly common question for being spelled out
> > that directly in the documentation. this statement should probably be
> > bold or italic or otherwise emphasized,
>
> Actually, first it should be *corrected*. It should say "... defined
> before the POSTMASTER is started". Or even more directly, "... supplied
> in the postmaster's environment variable set".

Agreed. Corrected. Man, initlocation is a mess of a configuration.

--
Bruce Momjian | http://candle.pha.pa.us
pgman(at)candle(dot)pha(dot)pa(dot)us | (610) 853-3000
+ If your life is a hard drive, | 830 Blythe Avenue
+ Christ can be your backup. | Drexel Hill, Pennsylvania 19026

> Jeff Hoffmann writes:
>
> > not to be pedantic, but just to make sure, i looked in the 7.0 docs and
> > it says it plain as day on the "alternate locations" section from the
> > admin guide, second paragraph "This
> > environment variable must have been defined before the backend was
> > started" this is an incredibly common question for being spelled out
> > that directly in the documentation. this statement should probably be
> > bold or italic or otherwise emphasized, since it is such an important
> > point and apparently very easily overlooked. maybe tom lockhart & the
> > other document editors will look kindly on this suggestion to alleviate
> > some new user headaches in the future.
>
> The documentation for 7.1 emphasizes this point a bit more. See
>
> http://www.postgresql.org/docs/admin/managing-databases.htm#AEN2065
>
> If something is still less than optimially clear, please submit a
> suggested new wording.

The current SGML stated it had to be set before the "backend" was
started. It says "postmaster" now.

--
Bruce Momjian | http://candle.pha.pa.us
pgman(at)candle(dot)pha(dot)pa(dot)us | (610) 853-3000
+ If your life is a hard drive, | 830 Blythe Avenue
+ Christ can be your backup. | Drexel Hill, Pennsylvania 19026