Update information on alternate database locations.

These fixes are from Jeff Hoffmann <jeff@remapcorp.com>.

doc/src/sgml/manage.sgml

@@ -11,12 +11,14 @@ This section is currently a thinly disguised copy of the Tutorial. Needs to be a
 </Para>
 
 <Para>
-Although the <FirstTerm>site administrator</FirstTerm> is responsible for overall management of the
+Although the <FirstTerm>site administrator</FirstTerm> is responsible for overall management 
-<ProductName>Postgres</ProductName> installation, some databases within the
+of the <ProductName>Postgres</ProductName> installation, some databases within the
-installation may be managed by another person, designated the <FirstTerm>database administrator</FirstTerm>.
+installation may be managed by another person, 
-This assignment of responsibilities occurs when a database is created. A user may be assigned
+designated the <FirstTerm>database administrator</FirstTerm>.
-explicit privileges to create databases and/or to create new users. A user assigned both privileges
+This assignment of responsibilities occurs when a database is created. 
-can perform most administrative task within <ProductName>Postgres</ProductName>, but will
+A user may be assigned explicit privileges to create databases and/or to create new users. 
+A user assigned both privileges can perform most administrative task 
+within <ProductName>Postgres</ProductName>, but will
 not by default have the same operating system privileges as the site administrator.
 </Para>
 
@@ -82,18 +84,27 @@ occurs through the database backend, so that any location specified must
 be accessible by the backend.
 
 <Para>
- Either an absolute path name or an environment variable
+ Alternate database locations are created and referenced by an environment variable 
-may be specified as a location.
+which gives the absolute path to the intended storage location.  
-Any environment variable specifying an alternate location must have
+This environment variable must have been defined before the backend was started 
-been defined before the backend was started.
+and the location it points to must be writable by the postgres administrator account.
 Consult with the site administrator
-regarding preconfigured alternate database locations.
+regarding preconfigured alternate database locations.  
+Any valid environment variable name may be used to reference an alternate location, 
+although using variable names with a prefix of <quote>PGDATA</quote> is recommended 
+to avoid confusion 
+and conflict with other variables.
 
 <Note>
 <Para>
- The environment variable style of specification
+ In previous versions of <ProductName>Postgres</ProductName>, 
+it was also permissable to use an absolute path name to specify 
+an alternate storage location.  
+Although the environment variable style of specification
 is to be preferred since it allows the site administrator more flexibility in
-managing disk storage.
+managing disk storage, it is also possible to use an absolute path 
+to specify an alternate location.  
+The administrator's guide discusses how to enable this feature.
 </Para>
 </Note>
 
@@ -103,45 +114,29 @@ any path or environment variable specified has some
 additional path fields appended.
 
 <Para>
-Alternate database locations must be prepared by running <Application>initlocation</Application>.
+Alternate database locations must be prepared by running 
+<Application>initlocation</Application>.
 
 <Para>
-To create a data storage area in <FileName>/alt/postgres/data</FileName>, ensure
+To create a data storage area using the environment variable 
-that <FileName>/alt/postgres</FileName> already exists.
+<envar>PGDATA2</envar> (for this example set to <filename>/alt/postgres</filename>), 
-From the command line, type
+ensure that <FileName>/alt/postgres</FileName> already exists and is writable by 
-<ProgramListing>
+the Postgres administrator account.
-% initlocation /alt/postgres/data
+Then, from the command line, type
-Creating Postgres database system directory /alt/postgres/data
-
-Creating Postgres database system directory /alt/postgres/data/base
-
-</ProgramListing>
-
-<Para>
-To do the same using an environment variable PGDATA2, type
 <ProgramListing>
 % initlocation $PGDATA2
 Creating Postgres database system directory /alt/postgres/data
-
 Creating Postgres database system directory /alt/postgres/data/base
-
 </ProgramListing>
 
 <Para>
-To create a database in the alternate storage area <FileName>/alt/postgres/data</FileName>
+To create a database in the alternate storage area <envar>PGDATA2<envar>
-from the command line,
+from the command line, use the following command: 
-type
-<ProgramListing>
-% createdb -D /alt/postgres/data mydb
-</ProgramListing>
-
-or
-
 <ProgramListing>
 % createdb -D PGDATA2 mydb
 </ProgramListing>
 
-and to do the same from within <Application>psql</Application> type
+To do the same from within <Application>psql</Application> type
 <ProgramListing>
 * CREATE DATABASE mydb WITH LOCATION = 'PGDATA2';
 </ProgramListing>
@@ -195,7 +190,8 @@ running the <ProductName>Postgres</ProductName>  terminal  monitor  programs  (e
 </ListItem>
 </ItemizedList>
 
-You might want to start up <Application>psql</Application>, to try out the examples in this manual.
+You might want to start up <Application>psql</Application>, 
+to try out the examples in this manual.
  It can be activated for the <Database>mydb</Database>
      database by typing the command:
 <ProgramListing>
@@ -237,7 +233,8 @@ mydb=> \g
 
      This  tells  the  server  to process the query.  If you
      terminate your query with a semicolon, the  <Quote>\g</Quote> is  not
-     necessary.   <Application>psql</Application> will automatically process semicolon terminated queries.
+     necessary.   
+<Application>psql</Application> will automatically process semicolon terminated queries.
      To read queries from a file,  say  myFile,  instead  of
      entering them interactively, type:
 <ProgramListing>

doc/src/sgml/start-ag.sgml

@@ -75,16 +75,32 @@ occurs through the database backend, so that any location specified must
 be accessible by the backend.
 
 <Para>
- Either an absolute path name or an environment variable
+ Alternate database locations are created and referenced by an environment variable
-may be specified as a location. Note that for security and integrity reasons,
+ which gives the absolute path to the intended storage location.
-all paths and environment variables so specified have some
+This environment variable must have been defined before the backend was started
-additional path fields appended.
+and must be writable by the postgres administrator account.
+Any valid environment variable name may be used to reference an alternate 
+location, although using variable name with a prefix of PGDATA is recommended
+to avoid confusion and conflict with other variables.
 
 <Note>
 <Para>
- The environment variable style of specification
+ In previous versions of <ProductName>Postgres</ProductName>, 
+it was also permissable to use an absolute path name to specify an alternate storage location.
+The environment variable style of specification
 is to be preferred since it allows the site administrator more flexibility in
 managing disk storage.
+If you prefer using absolute paths, you may do so by defining 
+"ALLOW_ABSOLUTE_DBPATHS" and recompiling <ProductName>Postgres</ProductName>
+ To do this, either add this line
+<ProgramListing>
+#define ALLOW_ABSOLUTE_DBPATHS 1
+</ProgramListing>
+to the file <filename>src/include/config.h</filename>, or by specifying
+<ProgramListing>
+ CFLAGS+= -DALLOW_ABSOLUTE_DBPATHS
+</ProgramListing>
+in your <filename>Makefile.custom</filename>.
 </Para>
 </Note>
 
@@ -92,24 +108,29 @@ managing disk storage.
 Remember that database creation is actually performed by the database backend.
 Therefore, any environment variable specifying an alternate location must have
 been defined before the backend was started. To define an alternate location
-PGDATA2 pointing to <filename>/home/postgres/data</filename>, type
+PGDATA2 pointing to <filename>/home/postgres/data</filename>, first type
 <ProgramListing>
 % setenv PGDATA2 /home/postgres/data
 </ProgramListing>
-
+to define the environment variable to be used with subsequent commands.
-<Para>
 Usually, you will want to define this variable in the 
 <ProductName>Postgres</ProductName> superuser's
 <filename>.profile</filename>
 or
 <filename>.cshrc</filename>
-initialization file to ensure that it is defined upon system startup.
+initialization file to ensure that it is defined upon system startup. 
+Any environment variable can be used to reference alternate location, 
+although it is preferred that the variables be prefixed with "PGDATA" 
+to eliminate confusion and the possibility of conflicting with or 
+overwriting other variables.
 
 <Para>
-To create a data storage area in <filename>/home/postgres/data</filename>, ensure
+To create a data storage area in PGDATA2, ensure
-that <filename>/home/postgres</filename> already exists and is writable.
+that <filename>/home/postgres</filename> already exists and is writable 
-From the command line, type
+by the postgres administrator.
+Then from the command line, type
 <ProgramListing>
+% setenv PGDATA2 /home/postgres/data
 % initlocation $PGDATA2
 Creating Postgres database system directory /home/postgres/data
 
@@ -132,8 +153,7 @@ To test the new location, create a database <Database>test</Database> by typing
 <Para>
      Assuming that  your  site  administrator  has  properly
      started  the  <Application>postmaster</Application>  process 
-and authorized you to
+and authorized you to use the database, you (as a user) may begin to start up
-     use the database, you (as a user) may begin to start up
      applications.   As previously mentioned, you should add
      <filename>/usr/local/pgsql/bin</filename> to your  shell  search  path.
      In  most  cases,  this  is all you should have to do in
@@ -147,7 +167,7 @@ and authorized you to
 <ProgramListing>
 connectDB() failed: Is the postmaster running at 'localhost' on port '5432'?
 </ProgramListing>
-     it is usually because either the <Application>postmaster</Application>  is  not  running,
+     it is usually because either the <Application>postmaster</Application> is not running,
  or you are attempting to connect to the wrong server host.
      If you get the following error message:
 <ProgramListing>