Update information on alternate database locations.

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

diff --git a/doc/src/sgml/manage.sgml b/doc/src/sgml/manage.sgml
index 22c0a918394d6946514ddbe6d991ac289146867e..c450f522ec94e12b36f5df995e4133a682a5d888 100644 (file)
--- a/doc/src/sgml/manage.sgml
+++ b/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
-<ProductName>Postgres</ProductName> installation, some databases within the
-installation may be managed by another person, designated the <FirstTerm>database administrator</FirstTerm>.
-This assignment of responsibilities occurs when a database is created. 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
+Although the <FirstTerm>site administrator</FirstTerm> is responsible for overall management 
+of the <ProductName>Postgres</ProductName> installation, some databases within the
+installation may be managed by another person, 
+designated the <FirstTerm>database administrator</FirstTerm>.
+This assignment of responsibilities occurs when a database is created. 
+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
-may be specified as a location.
-Any environment variable specifying an alternate location must have
-been defined before the backend was started.
+ Alternate database locations are created and referenced by an environment variable 
+which gives the absolute path to the intended storage location.  
+This environment variable must have 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
-that <FileName>/alt/postgres</FileName> already exists.
-From the command line, type
-<ProgramListing>
-% initlocation /alt/postgres/data
-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
+To create a data storage area using the environment variable 
+<envar>PGDATA2</envar> (for this example set to <filename>/alt/postgres</filename>), 
+ensure that <FileName>/alt/postgres</FileName> already exists and is writable by 
+the Postgres administrator account.
+Then, from the command line, 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>
-from the command line,
-type
-<ProgramListing>
-% createdb -D /alt/postgres/data mydb
-</ProgramListing>
-
-or
-
+To create a database in the alternate storage area <envar>PGDATA2<envar>
+from the command line, use the following command: 
 <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>

diff --git a/doc/src/sgml/start-ag.sgml b/doc/src/sgml/start-ag.sgml
index 49c37a3a8cc3f8f72b4503a5e8769726d0fede04..caa2cb6eec17c4ccfe181ea7770ad84a2c56b651 100644 (file)
--- a/doc/src/sgml/start-ag.sgml
+++ b/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
-may be specified as a location. Note that for security and integrity reasons,
-all paths and environment variables so specified have some
-additional path fields appended.
+ Alternate database locations are created and referenced by an environment variable
+ which gives the absolute path to the intended storage location.
+This environment variable must have been defined before the backend was started
+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>
-
-<Para>
+to define the environment variable to be used with subsequent commands.
 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
-that <filename>/home/postgres</filename> already exists and is writable.
-From the command line, type
+To create a data storage area in PGDATA2, ensure
+that <filename>/home/postgres</filename> already exists and is writable 
+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
-     use the database, you (as a user) may begin to start up
+and authorized you to 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>