pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedThoughts about the installation instructions
5+ messages / 4 participants
[nested] [flat]
* Thoughts about the installation instructions
@ 2002-03-11 21:53 Peter Eisentraut <peter_e@gmx.net>
0 siblings, 3 replies; 5+ messages in thread
From: Peter Eisentraut @ 2002-03-11 21:53 UTC (permalink / raw)
To: pgsql-docs
There are quite a few pieces of documentation that logically belong into
the installation instructions but are currently found elsewhere. For
instance in the ODBC and JDBC chapters, in the chapter on client
authentication (pieces about Kerberos), the pecularities of installing
PL/{Perl,Python}, and basically any place that mentions "configure".
It is my view that there should be a clean separation between installation
and use documentation. First of all, it's really useless to put
installation info into usage documentation because users see it too late.
Secondly, running "configure; make; make install" is really just one
several ways of installing PostgreSQL. Users of packages don't care about
what options you have to pass to "configure" to get at a certain feature.
(There should be some well-defined and documented way of figuring out
whether a certain build-time option was activated, but that could be as
easy as checking whether certain files exist in the installed set.)
I define the installation to have completed after "make install" finishes.
This is how it currently is defined, too. Running initdb is a grey area
because many packages handle it in different ways. Clearly once you start
the postmaster you are in "usage" time.
So what I would like to strive for is this:
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Thoughts about the installation instructions
@ 2002-03-11 22:04 Thomas Lockhart <thomas@fourpalms.org>
parent: Peter Eisentraut <peter_e@gmx.net>
2 siblings, 0 replies; 5+ messages in thread
From: Thomas Lockhart @ 2002-03-11 22:04 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs
...
> Furthermore, remove the chapter(s) on installation from the Admin Guide
> and make then a document of their own. This document need only exist in
> the source tree and does not need to be installed.
> Comments?
All good ideas. One small nit: the Installation Guide should be part of
the built-and-installed doc set, always. I know that sometimes (maybe
most times) folks reading it will be sitting in front of a clean machine
with a tarball and a beer, but in other cases folks will be sitting in
front of an RPM-installed machine wondering how to do a from-source
build for their next project. No need to make the docs harder to find
and read than necessary.
- Thomas
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Thoughts about the installation instructions
@ 2002-03-11 22:16 Bruce Momjian <pgman@candle.pha.pa.us>
parent: Peter Eisentraut <peter_e@gmx.net>
2 siblings, 0 replies; 5+ messages in thread
From: Bruce Momjian @ 2002-03-11 22:16 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs
> Furthermore, remove the chapter(s) on installation from the Admin Guide
> and make then a document of their own. This document need only exist in
> the source tree and does not need to be installed.
>
> Comments?
Makes sense. I assume the other stuff was just placed close to the
topic, like JDBC install near the JDBC chapter. Moving it into install
seems OK too.
--
Bruce Momjian | http://candle.pha.pa.us
pgman@candle.pha.pa.us | (610) 853-3000
+ If your life is a hard drive, | 830 Blythe Avenue
+ Christ can be your backup. | Drexel Hill, Pennsylvania 19026
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Thoughts about the installation instructions
@ 2002-03-12 02:20 Tom Lane <tgl@sss.pgh.pa.us>
parent: Peter Eisentraut <peter_e@gmx.net>
2 siblings, 1 reply; 5+ messages in thread
From: Tom Lane @ 2002-03-12 02:20 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs
Peter Eisentraut <peter_e@gmx.net> writes:
> It is my view that there should be a clean separation between installation
> and use documentation. First of all, it's really useless to put
> installation info into usage documentation because users see it too late.
This is too rigid a worldview.
The point of mentioning configuration issues in the usage docs is
that usage is when people will *find out* that they misconfigured
something. A link letting them know what they need to fix when they
observe some particular problem is not out of place in the usage docs.
I do agree that the installation procedures should mention all these
issues, too. Just don't strip out the references in the usage docs.
> Furthermore, remove the chapter(s) on installation from the Admin Guide
> and make then a document of their own. This document need only exist in
> the source tree and does not need to be installed.
Mumble. Certainly this could be a separate "book", but I strongly
disagree with removing it from the standard documentation set. To
my mind, the "integrated doc" *is* the standard documentation set and
should contain everything.
regards, tom lane
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Thoughts about the installation instructions
@ 2002-03-12 17:40 Peter Eisentraut <peter_e@gmx.net>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 5+ messages in thread
From: Peter Eisentraut @ 2002-03-12 17:40 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs
Tom Lane writes:
> The point of mentioning configuration issues in the usage docs is
> that usage is when people will *find out* that they misconfigured
> something. A link letting them know what they need to fix when they
> observe some particular problem is not out of place in the usage docs.
Yes, a link to the installation instructions is exactly what I'm
suggesting. Clearly these things belong into the installation
instructions at least. But I don't want to repeat the entire spiel about
the shared libperl everywhere PL/Perl is mentioned. Just say, if you
don't have have it, look into the installation instructions.
> Mumble. Certainly this could be a separate "book", but I strongly
> disagree with removing it from the standard documentation set. To
> my mind, the "integrated doc" *is* the standard documentation set and
> should contain everything.
OK.
--
Peter Eisentraut peter_e@gmx.net
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2002-03-12 17:40 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2002-03-11 21:53 Thoughts about the installation instructions Peter Eisentraut <peter_e@gmx.net>
2002-03-11 22:04 ` Thomas Lockhart <thomas@fourpalms.org>
2002-03-11 22:16 ` Bruce Momjian <pgman@candle.pha.pa.us>
2002-03-12 02:20 ` Tom Lane <tgl@sss.pgh.pa.us>
2002-03-12 17:40 ` Peter Eisentraut <peter_e@gmx.net>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox