Rearrange steps in recommended install procedure to something more

reasonable, ie configure and build first, then optionally run regress
tests using new parallel (non-installed) test method, and only then
backup and kill old installation.

doc/src/sgml/install.sgml

@@ -96,8 +96,9 @@ your own user account is enough.
 </para>
 <para>
 Running <ProductName>PostgreSQL</ProductName> as <literal>root</literal>, <literal>bin</literal>,
-or any other account with special access rights is a security risk and therefore
-won't be allowed.
+or any other account with special access rights is a security risk;
+<emphasis>don't do it</emphasis>.  The postmaster will in fact refuse
+to start as root.
 </para>
 <Para>
 You need not do the building and installation itself under this account
@@ -108,99 +109,6 @@ database superuser.
 
 <Step Performance="required">
 <Para>
-If you are not upgrading an existing system then skip to 
-<xref linkend="continue">.
-</Para>
-
-<Para>
-You now need to back up your existing database.
-To dump your fairly recent post-6.0 database installation, type
-<programlisting>
-pg_dumpall > db.out
-</programlisting>
-If you wish to preserve object id's (oids), then use the -o
-option when running <application>pg_dumpall</application>.  
-However, unless you have a
-special reason for doing this (such as using OIDs as keys
-in tables), don't do it.
-</Para>
-
-<Para>
-Make sure to use the <application>pg_dumpall</application>
-command from the version you are currently running.
-However, do not use the <application>pg_dumpall</application> 
-script from 6.0 or everything will be owned by the
-<ProductName>PostgreSQL</ProductName> super user. In that case
-you should grab <application>pg_dumpall</application> from a later
-6.x.x release. 7.0's <application>pg_dumpall</application>
-will not work on older databases.
-If you are upgrading from a version prior to
-<ProductName>Postgres95</ProductName> v1.09 then you must back up your database,
-install <ProductName>Postgres95</ProductName> v1.09, restore your database,
-then back it up again.
-</Para>
-
-<caution>
-<Para>
-     You must make sure that your database is not updated in the middle of
-     your backup.  If necessary, bring down postmaster, edit the permissions
-     in file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>
- to allow only you on, then
-     bring <application>postmaster</application> back up.
-</Para>
-</caution>
-</Step>
-
-<Step Performance="required">
-<Para>
-If you are upgrading an existing system then kill the database server now. Type
-<ProgramListing>
-ps ax | grep postmaster
-</ProgramListing>
-or
-<ProgramListing>
-ps -e | grep postmaster
-</ProgramListing>
-(It depends on your system which one of these two works. No harm can be done
-by typing the wrong one.)
-This should list the process numbers for a number of processes, similar
-to this:
-<ProgramListing>
-  263  ?  SW   0:00 (postmaster)
-  777  p1 S    0:00 grep postmaster
-</ProgramListing>
-Type the following line, with <replaceable>pid</replaceable>
-replaced by the process id for process <literal>postmaster</literal>
-(263 in the above case). (Do not use the id for the process "grep postmaster".)
-<programlisting>
-kill <replaceable>pid</replaceable>
-</programlisting>
-</Para>
-
-<tip>
-<para>
-On systems which have <productname>PostgreSQL</productname> started at boot time, there
-is probably a startup file which will accomplish the same thing. For example, on a
-Redhat Linux system one might find that
-<programlisting>
-/etc/rc.d/init.d/postgres.init stop
-</programlisting>
-works.
-</para>
-</tip>
-
-<Para>
-Also move the old directories  out of the way. Type the following:
-<programlisting>
-mv /usr/local/pgsql /usr/local/pgsql.old
-</programlisting>
-or replace your particular paths.
-</Para>
-
-</Step>
-
-<Step Performance="required" id="continue">
-<Para>
 Configure the source code for your system.  It is this step at which
 you can specify your actual installation path for the build process
 and make choices about what gets installed. Change into the <filename>src</filename>
@@ -249,10 +157,14 @@ For a complete list of options, type:
   <term>--with-perl</term>
   <listitem>
    <para>
-    Builds the Perl interface. Please note that the Perl interface will be
+    Builds the Perl interface and plperl extension language.
+    Please note that the Perl interface needs to be
     installed into the usual place for Perl modules (typically under
-    <filename>/usr/lib/perl</filename>), so you must have root access to use
-    this option successfully.
+    <filename>/usr/lib/perl</filename>), so you must have root access
+    to perform the installation step.  (It is often easiest to leave out
+    <term>--with-perl</term> initially, and then build and install the
+    Perl interface after completing the installation of PostgreSQL
+    itself.)
    </para>
   </listitem>
  </varlistentry>
@@ -287,7 +199,7 @@ Compile the program.  Type
 gmake
 </ProgramListing>
 The compilation process can take anywhere from 10 minutes to an hour.
-Your milage will most certainly vary. Remember to use GNU make.
+Your mileage will most certainly vary. Remember to use GNU make.
 </Para>
 
 <Para>
@@ -298,19 +210,132 @@ All of PostgreSQL is successfully made. Ready to install.
 </Para>
 </Step>
 
+<Step Performance="optional">
+<Para>
+If you want to test the newly built server before you install it,
+you can run the regression tests at this point.  The regression tests
+are a test suite to verify that <ProductName>PostgreSQL</ProductName>
+runs on your machine in the way the developers expected it to.
+For detailed instructions see <xref linkend="regress" endterm="regress-title">.
+(Be sure to use the "parallel regress test" method, since the sequential
+method only works with an already-installed server.)
+</Para>
+</Step>
+
 <Step Performance="required">
 <Para>
-Install the program.  Type
+If you are not upgrading an existing system then skip to 
+<xref linkend="continue">.
+</Para>
+
+<Para>
+You now need to back up your existing database.
+To dump your fairly recent post-6.0 database installation, type
+<programlisting>
+pg_dumpall > db.out
+</programlisting>
+If you wish to preserve object id's (oids), then use the -o
+option when running <application>pg_dumpall</application>.  
+However, unless you have a
+special reason for doing this (such as using OIDs as keys
+in tables), don't do it.
+</Para>
+
+<Para>
+Make sure to use the <application>pg_dumpall</application>
+command from the version you are currently running.
+7.0's <application>pg_dumpall</application> will not work on older databases.
+However, if you are still using 6.0, do not use the
+<application>pg_dumpall</application> script from 6.0 or everything will be
+owned by the <ProductName>PostgreSQL</ProductName> superuser after you
+reload. In that case
+you should grab <application>pg_dumpall</application> from a later
+6.x.x release.
+If you are upgrading from a version prior to
+<ProductName>Postgres95</ProductName> v1.09 then you must back up your database,
+install <ProductName>Postgres95</ProductName> v1.09, restore your database,
+then back it up again.
+</Para>
+
+<caution>
+<Para>
+     You must make sure that your database is not updated in the middle of
+     your backup.  If necessary, bring down postmaster, edit the permissions
+     in file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>
+ to allow only you on, then
+     bring <application>postmaster</application> back up.
+</Para>
+</caution>
+</Step>
+
+<Step Performance="required">
+<Para>
+If you are upgrading an existing system then kill the database server now. Type
+<ProgramListing>
+ps ax | grep postmaster
+</ProgramListing>
+or
+<ProgramListing>
+ps -e | grep postmaster
+</ProgramListing>
+(It depends on your system which one of these two works. No harm can be done
+by typing the wrong one.)
+This should list the process numbers for a number of processes, similar
+to this:
+<ProgramListing>
+  263  ?  SW   0:00 (postmaster)
+  777  p1 S    0:00 grep postmaster
+</ProgramListing>
+Type the following line, with <replaceable>pid</replaceable>
+replaced by the process id for process <literal>postmaster</literal>
+(263 in the above case). (Do not use the id for the process "grep postmaster".)
+<programlisting>
+kill <replaceable>pid</replaceable>
+</programlisting>
+</Para>
+
+<tip>
+<para>
+On systems which have <productname>PostgreSQL</productname> started at boot time, there
+is probably a startup file which will accomplish the same thing. For example, on a
+Redhat Linux system one might find that
+<programlisting>
+/etc/rc.d/init.d/postgres.init stop
+</programlisting>
+works.
+</para>
+</tip>
+
+<Para>
+Also move the old directories  out of the way. Type the following:
+<programlisting>
+mv /usr/local/pgsql /usr/local/pgsql.old
+</programlisting>
+(substitute your particular paths).
+</Para>
+
+</Step>
+
+<Step Performance="required" id="continue">
+<Para>
+Install the <ProductName>PostgreSQL</ProductName> executable files and
+libraries.  Type
 <ProgramListing>
 gmake install
 </ProgramListing>
 </Para>
+<Para>
+You should do this step as the user that you want the installed executables
+to be owned by.  This does not have to be the same as the database superuser;
+some people prefer to have the installed files be owned by root.
+</Para>
 </Step>
 
 <Step Performance="required">
 <Para>
-Tell your system how to find the new shared libraries. How to do this varies between
-platforms. What tends to work everywhere is to set the environment variable
+If necessary, tell your system how to find the new shared libraries.
+How to do this varies between platforms. The most widely usable method
+is to set the environment variable
 <envar>LD_LIBRARY_PATH</envar>:
 <programlisting>
 LD_LIBRARY_PATH=/usr/local/pgsql/lib
@@ -347,7 +372,8 @@ then the above was necessary.  Simply do this step then.
 
 <Step Performance="required">
 <Para>
-Create the database installation. To do this you must log in to your
+Create the database installation (the working data files).
+To do this you must log in to your
 <ProductName>PostgreSQL</ProductName> superuser account. It will not
 work as root.
 <ProgramListing>
@@ -361,21 +387,29 @@ su - postgres
 The <option>-D</option> option specifies the location where the data will be
 stored. You can use any path you want, it does not have to be under
 the installation directory. Just make sure that the superuser account
-can write to the directory (or create it) before starting <command>initdb</command>.
+can write to the directory (or create it, if it doesn't already exist)
+before starting <command>initdb</command>.
 (If you have already been doing the installation up to now as the <productname>PostgreSQL</productname>
-superuser, you may have to log in as root temporarily to create the data directory.)
+superuser, you may have to log in as root temporarily to create the data
+directory underneath a root-owned directory.)
 </Para>
 </Step>
 
 <Step Performance="required">
 <Para>
 The previous step should have told you how to start up the database server.
-Do so now.
+Do so now.  The command should look something like
 <programlisting>
 /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
 </programlisting>
 This will start the server in the foreground. To make it detach to
-the background, use the <option>-S</option>.
+the background, you can use the <option>-S</option> option, but then you won't
+see any log messages the server produces.  A better way to put the server
+in the background is
+<programlisting>
+nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
+    &lt;/dev/null &gt;>server.log 2&gt;>1 &amp;
+</programlisting>
 </Para>
 </Step>
 
@@ -400,7 +434,7 @@ you should look at the following optional steps and suggestions.
 <itemizedlist>
 <listitem>
 <Para>
-Life will be more convenient if you set up some enviroment variables. First of all
+Life will be more convenient if you set up some environment variables. First of all
 you probably want to include <filename>/usr/local/pgsql/bin</filename> (or equivalent)
 into your <envar>PATH</envar>. To do this, add the following to your shell startup
 file, such as <filename>~/.bash_profile</filename> (or <filename>/etc/profile</filename>,
@@ -537,12 +571,10 @@ Then make a softlink to this file from
 
 <listitem>
 <Para>
-Run the regression tests. The regression tests are a test suite to verify that
-PostgreSQL runs on your machine in the way the developers expected it to.
-You should definitely do this before putting a server into production use.
-The file <filename>/usr/src/pgsql/postgresql-7.0/src/test/regress/README</filename>
-has detailed
-instructions for running and interpreting the regression tests.
+Run the regression tests against the installed server (using the sequential
+test method).  If you didn't run the tests before installation, you should
+definitely do it now.
+For detailed instructions see <xref linkend="regress" endterm="regress-title">.
 </Para>
 </listitem>
 
@@ -558,8 +590,8 @@ Then enter
 <ProgramListing>
 psql testdb
 </ProgramListing>
-to connect to that database. At the prompt you can enter SQL and start
-experimenting.
+to connect to that database. At the prompt you can enter SQL commands
+and start experimenting.
 </Para>
 
 </Sect1>