PGDATA confusion

Hi,

I notice that in the man page and the page for pg_ctl in the
documentation (http://www.postgresql.org/docs/current/static/app-pg-ctl.html)
it states that the -D parameter should point to the directory which
contains the database files:

"Specifies the file system location of the database files. If this is
omitted, the environment variable PGDATA is used."

This isn't necessarily true. It will only need to know where the
postgresql.conf file is. In Debian and Ubuntu, for example, the
"database files" reside in /var/lib/postgresql/x.x/main/, and the
configuration files in /etc/postgresql/x.x/main/, so a user might
assume they need to point it to the former as that's where the actual
database itself can be found, when in fact it needs to be the latter.

This same inaccuracy affects the "postgres" command
(http://www.postgresql.org/docs/current/static/app-postgres.html) to a
lesser extent:

"Specifies the file system location of the data directory or
configuration file(s)."

Which is it? This suggests it can be either, when only the latter
matters. If it also happens to be the data directory, that's
unimportant.

To add further confusion, the page describing PGDATA
(http://www.postgresql.org/docs/current/static/storage-file-layout.html)
refers to it like so:

"All the data needed for a database cluster is stored within the
cluster's data directory, commonly referred to as PGDATA...

*snip*

The PGDATA directory contains several subdirectories and control
files... ...In addition to these required items, the cluster
configuration files postgresql.conf, pg_hba.conf, and pg_ident.conf
are traditionally stored in PGDATA (although in PostgreSQL 8.0 and
later, it is possible to keep them elsewhere)."

Traditionally but not necessarily, and not by default in Debian and
Ubuntu. In fact Gentoo (and therefore probably Sabayon too) has also
elected for this separation of data files and config files as of 9.0.

So if one set PGDATA to somewhere which had no database files at all,
but just postgresql.conf, it could still work (assuming it, in turn,
set data_directory correctly), but not vice versa. It would make more
sense to call it PGCONFIG, although I'm not proposing that, especially
since PGDATA makes sense when it comes to initdb.

There are probably plenty of other places in the docs which also don't
adequately describe PGDATA or -D.

Any disagreements? If not, should I write a patch (since someone will
probably accuse me of volunteering anyway) or would someone like to
commit some adjustments?

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise PostgreSQL Company