Update installation instructions to new realities. Combined into one file.

Improved automation of INSTALL file generation.

11 files changed, 1912 insertions, 1823 deletions

diff --git a/INSTALL b/INSTALL
index 75b9aa9a645..472b46db24b 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,417 +1,682 @@
-     Installation instructions for PostgreSQL 7.0.2.
+PostgreSQL Installation Instructions
 
-If you haven't gotten the PostgreSQL distribution, get it from
-ftp.postgresql.org, then unpack it:
+Table of Contents
+Short Version
+Requirements
+If You Are Upgrading
+Installation Procedure
+Post-Installation Setup
+Getting Started
+What Now?
+Supported Platforms
+
+Short Version
+
+./configure
+gmake
+gmake install
+adduser postgres
+su - postgres
+/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
+/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
+/usr/local/pgsql/bin/createdb test
+/usr/local/pgsql/bin/psql test
+
+The long version is the rest of this document.
+
+  ------------------------------------------------------------------------
+
+Requirements
+
+In general, a modern Unix-compatible platform should be able to run
+PostgreSQL. The platforms that had received explicit testing at the time of
+release are listed in the section called Supported Platforms below. In the
+doc subdirectory of the distribution there are several platform-specific FAQ
+documents you might wish to consult if you are having trouble.
+
+Compiler. You need a Standard ("ANSI") C compiler. Recent versions of GCC
+are recommendable, but PostgreSQL is known to build with a wide variety of
+compilers from different vendors.
+
+Make. Building PostgreSQL requires GNU make; it will not work with other
+make programs. GNU make is often installed under the name gmake. This
+document will always refer to it by that name. (On GNU/Linux systems GNU
+make is the default tool with the name make.) To test for GNU make enter
+
+gmake --version
+
+If at all possible you should try to use version 3.76.1 or later. If you
+need to get GNU make, you can find it at your local GNU mirror site (see
+http://www.gnu.org/order/ftp.html) or at ftp://ftp.gnu.org/gnu/make.
+
+Resources. Check that you have sufficient disk space. You will need about 30
+MB for the source tree during compilation and about 5 MB for the
+installation directory. An empty database takes about 1 MB, later it takes
+about five times the amount of space that a flat text file with the same
+data would take. If you are going to run the regression tests you will
+temporarily need an extra 20 MB. Use the df command to check for disk space.
+
+  ------------------------------------------------------------------------
+
+If You Are Upgrading
+
+The internal data storage format changes with new releases of PostgreSQL.
+Therefore, if you are upgrading an existing installation that does not have
+a version number "7.1.x", you must back up and restore your data as shown
+here. These instructions assume that your existing installation is under the
+/usr/local/pgsql directory, and that the data area is in
+/usr/local/pgsql/data. Substitute your paths appropriately.
 
-> gunzip postgresql-7.0.2.tar.gz
-> tar -xf postgresql-7.0.2.tar
-> mv postgresql-7.0.2 /usr/src
+  1. Make sure that your database is not updated during or after the backup.
+     This does not affect the integrity of the backup, but the changed data
+     would of course not be included. If necessary, edit the permissions in
+     the file /usr/local/pgsql/data/pg_hba.conf (or equivalent) to disallow
+     access from everyone except you.
 
+  2. To dump your database installation, type:
 
-Before you start
+     pg_dumpall > outputfile
 
-Building PostgreSQL requires GNU make. It will not work with other make
-programs. On GNU/Linux systems GNU make is the default tool, on other
-systems you may find that GNU make is installed under the name gmake. We
-will use that name from now on to indicate GNU make, no matter what name it
-has on your system. To test for GNU make enter
+     If you need to preserve the oids (such as when using them as foreign
+     keys), then use the -o option when running pg_dumpall.
 
-> gmake --version
+     Make sure that you use the pg_dumpall command from the version you are
+     currently running. 7.1's pg_dumpall should not be used on older
+     databases.
+
+  3. If you are installing the new version at the same location as the old
+     one then shut down the old server, at the latest before you install the
+     new files:
+
+     kill -INT `cat /usr/local/pgsql/data/postmaster.pid`
+
+     Versions prior to 7.0 do not have this postmaster.pid file. If you are
+     using such a version you must find out the process id of the server
+     yourself, for example by typing ps ax | grep postmaster, and supply it
+     to the kill command.
 
+     On systems which have PostgreSQL started at boot time, there is
+     probably a startup file that will accomplish the same thing. For
+     example, on a Redhat Linux system one might find that
 
-If you need to get GNU make, you can find it at ftp://ftp.gnu.org.
+     /etc/rc.d/init.d/postgres.init stop
 
-Up to date information on supported platforms is at
-http://www.postgresql.org/docs/admin/ports.htm. In general, most
-Unix-compatible platforms with modern libraries should be able to run
-PostgreSQL. In the doc subdirectory of the distribution are several
-platform-specific FAQ and README documents you might wish to consult if you
-are having trouble.
+     works.
 
-Although the minimum required memory for running PostgreSQL can be as little
-as 8MB, there are noticeable speed improvements when expanding memory up to
-96MB or beyond. The rule is you can never have too much memory.
+  4. If you are installing in the same place as the old version then it is
+     also a good idea to move the old installation out of the way, in case
+     you still need it later on. Use a command like this:
 
-Check that you have sufficient disk space. You will need about 30 Mbytes for
-the source tree during compilation and about 5 Mbytes for the installation
-directory. An empty database takes about 1 Mbyte, otherwise they take about
-five times the amount of space that a flat text file with the same data
-would take. If you run the regression tests you will temporarily need an
-extra 20MB.
+     mv /usr/local/pgsql /usr/local/pgsql.old
 
-To check for disk space, use
+After you have installed PostgreSQL 7.1, create a new database directory and
+start the new server. Remember that you must execute these commands while
+logged in to the special database user account (which you already have if
+you are upgrading).
 
-> df -k
+/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/bin
+/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/bin
 
-Considering today's prices for hard disks, getting a large and fast hard
-disk should probably be in your plans before putting a database into
-production use.
+Finally, restore your data with
 
+/usr/local/pgsql/bin/psql -d template1 -f outputfile
+
+using the new psql.
+
+You can also install the new version in parallel with the old one to
+decrease the downtime. These topic are discussed at length in the
+Administrator's Guide, which you are encouraged to read in any case. The
+pg_upgrade utility can also often be used.
+
+  ------------------------------------------------------------------------
 
 Installation Procedure
 
-PostgreSQL Installation
+  1. Configuration
 
-For a fresh install or upgrading from previous releases of PostgreSQL:
+     The first step of the installation procedure to configure the source
+     tree for your system and choose the options you would like. This is
+     done by running the configure script. For a default installation,
+     simply type
 
-  1. Create the PostgreSQL superuser account. This is the user the server
-     will run as. For production use you should create a separate,
-     unprivileged account (postgres is commonly used). If you do not have
-     root access or just want to play around, your own user account is
-     enough.
+     ./configure
 
-     Running PostgreSQL as root, bin, or any other account with special
-     access rights is a security risk; don't do it. The postmaster will in
-     fact refuse to start as root.
+     This script will run a number of tests to guess values for various
+     system dependent variables and detect some quirks of your operating
+     system, and finally creates several files in the build tree to record
+     what it found.
 
-     You need not do the building and installation itself under this account
-     (although you can). You will be told when you need to login as the
-     database superuser.
+     The default configuration will build the server and utilities, as well
+     as all client applications and interfaces that only require a C
+     compiler. All files will be installed under /usr/local/pgsql by
+     default.
 
-  2. 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 src
-     subdirectory and type:
+     You can customize the build and installation process by giving one or
+     more of the following command line options to configure:
 
-     > ./configure
+     --prefix=PREFIX
 
+          Install all files under the directory PREFIX instead of
+          /usr/local/pgsql. The actual files will be installed into various
+          subdirectories; no files will ever be installed directly into the
+          PREFIX directory.
 
-     followed by any options you might want to give it. For a first
-     installation you should be able to do fine without any. For a complete
-     list of options, type:
+          If you have special needs, you can also customize the individual
+          subdirectories with the following options.
 
-     > ./configure --help
+     --exec-prefix=EXEC-PREFIX
 
+          You can install architecture-dependent files under a different
+          prefix, EXEC-PREFIX, than what PREFIX was set to. This can be
+          useful to share architecture-independent files between hosts. If
+          you omit this, then EXEC-PREFIX is set equal to PREFIX and both
+          architecture dependent and independent files will be installed
+          under the same tree, which is probably what you want.
 
-     Some of the more commonly used ones are:
+     --bindir=DIRECTORY
 
-     --prefix=BASEDIR
+          Specifies the directory for executable programs. The default is
+          EXEC-PREFIX/bin, which normally means /usr/local/pgsql/bin.
 
-          Selects a different base directory for the installation of
-          PostgreSQL. The default is /usr/local/pgsql.
+     --datadir=DIRECTORY
 
-     --enable-locale
+          Sets the directory for read-only data files used by the installed
+          programs. The default is PREFIX/share. Note that this has nothing
+          to do with where your database files will be placed.
 
-          If you want to use locales.
+     --sysconfdir=DIRECTORY
 
-     --enable-multibyte
+          The directory for various configuration files, PREFIX/etc by
+          default.
 
-          Allows the use of multibyte character encodings. This is primarily
-          for languages like Japanese, Korean, or Chinese.
+     --libdir=DIRECTORY
 
-     --with-perl
+          The location to install libraries and dynamically loadable
+          modules. The default is EXEC-PREFIX/lib.
 
-          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 /usr/lib/perl), so you
-          must have root access to perform the installation step. (It is
-          often easiest to leave out --with-perl initially, and then build
-          and install the Perl interface after completing the installation
-          of PostgreSQL itself.)
+     --includedir=DIRECTORY
 
-     --with-odbc
+          The directory for installing C and C++ header files. The default
+          is PREFIX/include.
 
-          Builds the ODBC driver package.
+     --docdir=DIRECTORY
 
-     --with-tcl
+          Documentation files, except "man" pages, will be installed into
+          this directory. The default is PREFIX/doc.
 
-          Builds interface libraries and programs requiring Tcl/Tk,
-          including libpgtcl, pgtclsh, and pgtksh.
+     --mandir=DIRECTORY
 
-  3. Compile the program. Type
+          The man pages that come with PostgreSQL will be installed under
+          this directory, in their respective manx subdirectories.
+          PREFIX/man.
 
-     > gmake
+     --with-includes=DIRECTORIES
 
+          DIRECTORIES is a colon-separated list of directories that will be
+          added to the list the compiler searches for header files. If you
+          have optional packages (such as GNU Readline) installed in a
+          non-standard location you have to use this option and probably the
+          corresponding --with-libraries option.
 
-     The compilation process can take anywhere from 10 minutes to an hour.
-     Your mileage will most certainly vary. Remember to use GNU make.
+          Example: --with-includes=/opt/gnu/include:/usr/sup/include.
 
-     The last line displayed will hopefully be
+     --with-libraries=DIRECTORIES
 
-     All of PostgreSQL is successfully made. Ready to install.
+          DIRECTORIES is a colon-separated list of directories to search for
+          libraries. You will probably have to use this option (and the
+          corresponding --with-includes option) if you have packages
+          installed in non-standard locations.
 
+          Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib.
 
-  4. 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 PostgreSQL runs on your machine in the way
-     the developers expected it to. For detailed instructions see Regression
-     Test. (Be sure to use the "parallel regress test" method, since the
-     sequential method only works with an already-installed server.)
+     --enable-locale
 
-  5. If you are not upgrading an existing system, skip to step 7.
-     If you are running 7.*, skip to step 6.
+          Enables locale support. There is a performance penalty associated
+          with locale support, but if you are not in an English-speaking
+          environment you will most likely need this.
 
-     You now need to back up your existing database. To dump your 
-     database installation, type:
+     --enable-recode
 
-     > pg_dumpall > db.out
+          Enables character set recode support. See doc/README.Charsets for
+          details on this feature.
 
+     --enable-multibyte
 
-     If you wish to preserve object id's (oids), then use the -o option when
-     running pg_dumpall. However, unless you have a special reason for doing
-     this (such as using OIDs as keys in tables), don't do it.
+          Allows the use of multibyte character encodings. This is primarily
+          for languages like Japanese, Korean, and Chinese. Read
+          doc/README.mb for details.
 
-     Make sure to use the pg_dumpall command from the version you are
-     currently running. 7.0.2's pg_dumpall should not be used on older
-     databases.
+     --with-pgport=NUMBER
 
-                                        Caution
-      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
-      /usr/local/pgsql/data/pg_hba.conf to allow only you on, then bring
-      postmaster back up.
+          Set NUMBER as the default port number for server and clients. The
+          default is 5432. The port can always be changed later on, but if
+          you specify it here then both server and clients will have the
+          same default compiled in, which can be very convenient.
 
-      Rather than using pg_dumpall, pg_upgrade can often be used.
+     --with-CXX
 
-  6. If you are upgrading an existing system, kill the database server
-     now. Type
+          Build the C++ interface library. configure will automatically pick
+          the C++ compiler that goes with the C compiler you are using. It
+          is not recommended or supported to use C and C++ compilers of
+          different origin in the same build.
 
-     > ps ax | grep postmaster
+     --with-perl
 
+          Build the Perl interface module. The Perl interface will be
+          installed at the usual place for Perl modules (typically under
+          /usr/lib/perl), so you must have root access to perform the
+          installation step (see step 4). You need to have Perl 5 installed
+          to use this option.
 
-     or
+     --with-python
 
-     > ps -e | grep postmaster
+          Build the Python interface module. You need to have root access to
+          be able to install the Python module at its default place
+          (/usr/lib/pythonx.y). To be able to use this option, you must have
+          Python installed and your system needs to support shared
+          libraries. If you instead want to build a new complete interpreter
+          binary, you will have to do it manually.
 
+     --with-tcl
 
-     (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:
+          Builds components that require Tcl, which are libpgtcl, pgtclsh,
+          and PL/Tcl.
 
-       263  ?  SW   0:00 (postmaster)
-       777  p1 S    0:00 grep postmaster
+     --with-x
 
+          Use the X Window System. If you specified --with-tcl then this
+          will enable the build of modules requiring Tcl/Tk, that is, pgtksh
+          and pgaccess.
 
-     Type the following line, with pid replaced by the process id for
-     process postmaster (263 in the above case). (Do not use the id for the
-     process "grep postmaster".)
+     --with-tclconfig=DIRECTORY, --with-tkconfig=DIRECTORY
 
-     > kill pid
+          Tcl/Tk installs the files tclConfig.sh and tkConfig.sh which
+          contain certain configuration information that is needed to build
+          modules interfacing to Tcl or Tk. These files are normally found
+          automatically at their well-known location, but if you want to use
+          a different version of Tcl or Tk you can specify the directory
+          where to find them.
 
+     --enable-odbc
 
-          Tip: On systems which have PostgreSQL started at boot time,
-          there is probably a startup file that will accomplish the
-          same thing. For example, on a Redhat Linux system one might
-          find that
+          Build the ODBC driver package.
 
-          > /etc/rc.d/init.d/postgres.init stop
+     --with-odbcinst=DIRECTORY
 
+          Specifies the directory where the ODBC driver will expect its
+          odbcinst.ini configuration file. The default is
+          /usr/local/pgsql/etc or whatever you specified as --sysconfdir. A
+          default file will be installed there.
 
-          works.
+     --with-krb4=DIRECTORY, --with-krb5=DIRECTORY
 
-     If you used pg_dumpall, move the old directory out of the
-     way.  Type the following:
+          Build with suppport for Kerberos authentication. You can use
+          either Kerberos version 4 or 5, but not both. The DIRECTORY
+          argument specifies the root directory of the Kerberos
+          installation; /usr/athena is assumed as default. If the relevant
+          headers files and libraries are not under a common parent
+          directory, then you must use the --with-includes and
+          --with-libraries options in addition to this option. If, on the
+          other hand, the required files are in a location that is searched
+          by default (e.g., /usr/lib), then you can leave off the argument.
 
-     > mv /usr/local/pgsql /usr/local/pgsql.old
+          configure will check for the required header files and libraries
+          to make sure that your Kerberos installation is sufficient before
+          proceeding.
 
+     --with-krb-srvnam=NAME
 
-     (substitute your particular paths).
+          The name of the Kerberos service principal. "postgres" is the
+          default. There's probably no reason to change this.
 
-  7. Install the PostgreSQL executable files and libraries. Type
+     --with-krb-srvtab=FILE
 
-     > gmake install
+          Specifies the location of the Kerberos server shared key file
+          ("srvtab"). If you are using Kerberos 4, this defaults to
+          /etc/srvtab, with Kerberos 5 to
+          FILE:/usr/local/pgsql/etc/krb5.keytab, or equivalent, depending on
+          what you set --sysconfdir to above.
 
+     --enable-syslog
 
-     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.
+          Enables the PostgreSQL server to use the syslog logging facility.
+          (Using this option does not mean that you have to log with syslog
+          or even that it will be done by default, it simply makes it
+          possible to turn this option on at run time.)
 
-  8. 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 LD_LIBRARY_PATH:
+     --enable-debug
 
-     > LD_LIBRARY_PATH=/usr/local/pgsql/lib
-     > export LD_LIBRARY_PATH
+          Compiles all programs and libraries with debugging symbols. This
+          means that you can run the programs through a debugger to analyze
+          problems. This option is not recommended for production use.
 
+     Environment variables. You can set the CC environment variable to
+     choose the C compiler to use. If you don't then configure will look for
+     one. For example:
 
-     on sh, ksh, bash, zsh or
+     CC=/opt/bin/gcc ./configure
 
-     > setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
+  2. Build
 
+     To start the build, type
 
-     on csh or tcsh. You might want to put this into a shell startup file
-     such as /etc/profile.
+     gmake
 
-     On some systems the following is the preferred method, but you must
-     have root access. Edit file /etc/ld.so.conf to add a line
+     (Remember to use GNU make.) The build can take anywhere from 5 minutes
+     to half an hour. The last line displayed should be
 
-     /usr/local/pgsql/lib
+     All of PostgreSQL is successfully made. Ready to install.
 
+  3. Regression Tests
 
-     Then run command /sbin/ldconfig.
+     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 PostgreSQL runs on your machine in the way
+     the developers expected it to. Type
 
-     If in doubt, refer to the manual pages of your system. If you later on
-     get a message like
+     gmake -C src/test/regress all runcheck
 
-     psql: error in loading shared libraries
-     libpq.so.2.1: cannot open shared object file: No such file or directory
+     It is possible that some tests fail, due to differences in error
+     message wording or floating point results. The file
+     src/test/regress/README and the Administrator's Guide contain detailed
+     information about interpreting the test results. You can repeat this
+     test at any later time by issuing the same command.
 
+  4. Installing The Files
 
-     then the above was necessary. Simply do this step then.
+          Note: If you are upgrading an existing system and are going
+          to install the new files over the old ones then you should
+          have backed up your data and shut down the old server by now,
+          as explained in the section called If You Are Upgrading
+          above.
 
-  9. If you moved the old directory out of the way, 
-     create the database installation (the working data files). To do this
-     you must log in to your PostgreSQL superuser account. It will not work
-     as root.
+     To install PostgreSQL enter
 
-     > mkdir /usr/local/pgsql/data
-     > chown postgres /usr/local/pgsql/data
-     > su - postgres
-     > /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
+     gmake install
 
+     This will install files into the directories that were specified in
+     step 1. Make sure that you have appropriate permissions to write into
+     that area. Normally you need to do this step as root. Alternatively,
+     you could create the target directories in advance and arrange for
+     appropriate permissions to be granted.
 
-     The -D 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, if it doesn't already exist)
-     before starting initdb. (If you have already been doing the
-     installation up to now as the PostgreSQL superuser, you may have to log
-     in as root temporarily to create the data directory underneath a
-     root-owned directory.)
+     If you built the Perl or Python interfaces and you were not the root
+     user when you executed the above command then that part of the
+     installation probably failed. In that case you should become the root
+     user and then do
 
- 10. The previous step should have told you how to start up the database
-     server. Do so now. The command should look something like
+     gmake -C src/interfaces/perl5 install
+     gmake -C src/interfaces/python install
 
-     > /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
+     Due to a quirk in the Perl build environment the first command will
+     actually rebuild the complete interface and then install it. This is
+     not harmful, just unusual. If you do not have superuser access you are
+     on your own: you can still take the required files and place them in
+     other directories where Perl or Python can find them, but how to do
+     that is left as an exercise.
 
+     Client-only installation. If you want to install only the client
+     applications and interfaces, then you can use these commands:
 
-     This will start the server in the foreground. To make it detach to the
-     background, you can use the -S option, but then you won't see any log
-     messages the server produces. A better way to put the server in the
-     background is
+     gmake -C src/bin install
+     gmake -C src/interfaces install
+     gmake -C doc install
 
-     > nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
-         </dev/null >>server.log 2>>1 &
+     To undo the installation use the command gmake uninstall. However, this
+     will not remove the Perl and Python interfaces and it will not remove
+     any directories.
 
+Cleanup. After the installation you can make room by removing the built
+files from the source tree with the gmake clean command. This will preserve
+the choices made by the configure program, so that you can rebuild
+everything with gmake later on. To reset the source tree to the state in
+which it was distributed, use gmake distclean. If you are going to build for
+several platforms from the same source tree you must do this and
+re-configure for each build.
 
- 11. If you did a pg_dumpall, reload your data back in:
+  ------------------------------------------------------------------------
 
-     > /usr/local/pgsql/bin/psql -d template1 -f db.out
+Post-Installation Setup
 
+Shared Libraries
 
-     You also might want to copy over the old pg_hba.conf file and any other
-     files you might have had set up for authentication, such as password
-     files.
+On most systems that have shared libraries (which most systems do) you need
+to tell your system how to find the newly installed shared libraries. How to
+do this varies between platforms, but the most widely usable method is to
+set the environment variable LD_LIBRARY_PATH like so: In Bourne shells (sh,
+ksh, bash, zsh)
 
-This concludes the installation proper. To make your life more productive
-and enjoyable you should look at the following optional steps and
-suggestions:
+LD_LIBRARY_PATH=/usr/local/pgsql/lib
+export LD_LIBRARY_PATH
 
-   * Life will be more convenient if you set up some environment variables.
-     First of all you probably want to include /usr/local/pgsql/bin (or
-     equivalent) into your PATH. To do this, add the following to your shell
-     startup file, such as ~/.bash_profile (or /etc/profile, if you want it
-     to affect every user):
+or in csh or tcsh
 
-     > PATH=$PATH:/usr/local/pgsql/bin
+setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
 
+Replace /usr/local/pgsql/lib with whatever you set --libdir to in step 1.
+You should put these commands into a shell startup file such as /etc/profile
+or ~/.bash_profile.
 
-     Furthermore, if you set PGDATA in the environment of the PostgreSQL
-     superuser, you can omit the -D for postmaster and initdb.
+On Linux systems the following is the preferred method, but you must have
+root access. Edit the file /etc/ld.so.conf to add a line
 
-   * You probably want to install the man and HTML documentation. Type
+/usr/local/pgsql/lib
 
-     > cd /usr/src/pgsql/postgresql-7.0.2/doc
-     > gmake install
+Then run command /sbin/ldconfig.
 
+If in doubt, refer to the manual pages of your system. If you later on get a
+message like
 
-     This will install files under /usr/local/pgsql/doc and
-     /usr/local/pgsql/man. To enable your system to find the man
-     documentation, you need to add a line like the following to a shell
-     startup file:
+psql: error in loading shared libraries
+libpq.so.2.1: cannot open shared object file: No such file or directory
 
-     > MANPATH=$MANPATH:/usr/local/pgsql/man
+then this step was necessary. Simply take care of it then.
 
+  ------------------------------------------------------------------------
 
-     The documentation is also available in Postscript format. If you have a
-     Postscript printer, or have your machine already set up to accept
-     Postscript files using a print filter, then to print the User's Guide
-     simply type
+Environment Variables
 
-     > cd /usr/local/pgsql/doc
-     > gunzip -c user.ps.tz | lpr
+If you installed into /usr/local/pgsql or some other location that is not
+searched for programs by default, you need to add /usr/local/pgsql/bin (or
+what you set --bindir to in step 1) into your PATH. To do this, add the
+following to your shell startup file, such as ~/.bash_profile (or
+/etc/profile, if you want it to affect every user):
 
+PATH=$PATH:/usr/local/pgsql/bin
 
-     Here is how you might do it if you have Ghostscript on your system and
-     are writing to a laserjet printer.
+If you are using csh or tcsh, then use this command:
 
-     > gunzip -c user.ps.gz \
-         | gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- \
-         | lpr
+set path = ( /usr/local/pgsql/bin path )
 
+To enable your system to find the man documentation, you need to add a line
+like the following to a shell startup file:
 
-     Printer setups can vary wildly from system to system. If in doubt,
-     consult your manuals or your local expert.
+MANPATH=$MANPATH:/usr/local/pgsql/man
 
-     The Adminstrator's Guide should probably be your first reading if you
-     are completely new to PostgreSQL, as it contains information about how
-     to set up database users and authentication.
+The environment variables PGHOST and PGPORT specify to client applications
+the host and port of the database server, overriding the compiled-in
+defaults. If you are going to run client applications remotely then it is
+convenient if every user that plans to use the database sets PGHOST, but it
+is not required and the settings can be communicated via command line
+options to most client programs.
 
-   * Usually, you will want to modify your computer so that it will
-     automatically start the database server whenever it boots. This is not
-     required; the PostgreSQL server can be run successfully from
-     non-privileged accounts without root intervention.
+  ------------------------------------------------------------------------
 
-     Different systems have different conventions for starting up daemons at
-     boot time, so you are advised to familiarize yourself with them. Most
-     systems have a file /etc/rc.local or /etc/rc.d/rc.local which is almost
-     certainly no bad place to put such a command. Whatever you do,
-     postmaster must be run by the PostgreSQL superuser (postgres) and not
-     by root or any other user. Therefore you probably always want to form
-     your command lines along the lines of su -c '...' postgres.
+Getting Started
 
-     It might be advisable to keep a log of the server output. To start the
-     server that way try:
+The following is a quick summary of how to get PostgreSQL up and running
+once installed. The Administrator's Guide contains more information.
 
-     > nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &
+  1. Create the PostgreSQL server account. This is the user the server will
+     run as. For production use you should create a separate, unprivileged
+     account ("postgres" is commonly used). If you do not have root access
+     or just want to play around, your own user account is enough, but
+     running the server as root is a security risk and therefore not
+     allowed.
 
+     adduser postgres
 
-     Here are a few more operating system specific suggestions.
+  2. Create a database installation with the initdb command. To run initdb
+     you must be logged in to your PostgreSQL server account. It will not
+     work as root.
 
-        o Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris 2.5.1
-          to contain the following single line:
+     root# mkdir /usr/local/pgsql/data
+     root# chown postgres /usr/local/pgsql/data
+     root# su - postgres
+     postgres$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
 
-          > su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
+     The -D 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 server account can
+     write to the directory (or create it, if it doesn't already exist)
+     before starting initdb, as illustrated here.
 
+  3. The previous step should have told you how to start up the database
+     server. Do so now. The command should look something like
 
-        o In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
-          contain the following lines and make it chmod 755 and chown
-          root:bin.
+     /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
 
-          #!/bin/sh
-          [ -x /usr/local/pgsql/bin/postmaster ] && {
-              su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
-                  -D/usr/local/pgsql/data
-                  -S -o -F > /usr/local/pgsql/errlog' &
-              echo -n ' pgsql'
-          }
+     This will start the server in the foreground. To put the server in the
+     background use something like
 
+     nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
+         </dev/null >>server.log 2>&1 </dev/null &
 
-          You may put the line breaks as shown above. The shell is smart
-          enough to keep parsing beyond end-of-line if there is an
-          expression unfinished. The exec saves one layer of shell under the
-          postmaster process so the parent is init.
+     To stop a server running in the background you can type
 
-        o In RedHat Linux add a file /etc/rc.d/init.d/postgres.init which is
-          based on the example in contrib/linux/. Then make a softlink to
-          this file from /etc/rc.d/rc5.d/S98postgres.init.
+     kill `cat /usr/local/psgql/data/postmaster.pid`
 
-   * 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 Regression Test.
+     In order to allow TCP/IP connections (rather than only Unix domain
+     socket ones) you need to pass the -i option to postmaster.
 
-To start experimenting with Postgres, set up the paths as explained above
-and start the server. To create a database, type
+  4. Create a database:
 
-> createdb testdb
+     createdb testdb
 
+     Then enter
 
-Then enter
+     psql testdb
 
-> psql testdb
+     to connect to that database. At the prompt you can enter SQL commands
+     and start experimenting.
 
+  ------------------------------------------------------------------------
 
-to connect to that database. At the prompt you can enter SQL commands and
-start experimenting.
+What Now?
+
+   * The Tutorial should be your first reading if you are completely new to
+     SQL databases. It should have been installed at
+     /usr/local/pgsql/doc/tutorial/index.html unless you changed the
+     installation directories.
+
+   * If you are familiar with database concepts then you want to proceed
+     with the Administrator's Guide, which contains information about how to
+     set up the database server, database users, and authentication. It can
+     be found at /usr/local/pgsql/doc/admin/index.html.
+
+   * Usually, you will want to modify your computer so that it will
+     automatically start the database server whenever it boots. Some
+     suggestions for this are in the Administrator's Guide.
+
+   * 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. This is also explained
+     in the Administrator's Guide.
+
+  ------------------------------------------------------------------------
+
+Supported Platforms
+
+At the time of release, PostgreSQL 7.1 has been verified by the developer
+community to work on the following platforms. A supported platform generally
+means that PostgreSQL builds and installs according to these instructions
+and that the regression tests pass, except for minor differences.
+
+     Note: If you are having problems with the installation on a
+     supported platform, please write to <pgsql-bugs@postgresql.org> or
+     <pgsql-ports@postgresql.org>, not to the people listed here.
+
+ OS           Processor Version Reported                            Remarks
+ AIX 4.3.2    RS6000    7.0     2000-04-05, Andread Zeugswetter     See also
+                                (<Andreas.Zeugswetter@telecom.at>)  doc/FAQ_AIX
+ BSDI 4.01    x86       7.0     2000-04-04, Bruce Momjian
+                                (<pgman@candle.pha.pa.us>)
+ Compaq Tru64 Alpha     7.0     2000-04-11, Andrew McMurry
+ 5.0                            (<andrew.mcmurry@astro.uio.no>)
+ FreeBSD 4.0  x86       7.0     2000-04-04, Marc Fournier
+                                (<scrappy@hub.org>)
+ HPUX 9.0x andPA-RISC   7.0     2000-04-12, Tom Lane
+ 10.20                          (<tgl@sss.pgh.pa.us>)
+ IRIX 6.5.6f  MIPS      6.5.3   2000-02-18, Kevin Wheatley          MIPSPro
+                                (<hxpro@cinesite.co.uk>)            7.3.1.1m N32
+                                                                    build
+ Linux 2.0.x  Alpha     7.0     2000-04-05, Ryan Kirkpatrick        with published
+                                (<pgsql@rkirkpat.net>)              patches
+ Linux 2.2.x  armv4l    7.0     2000-04-17, Mark Knox               Regression
+                                (<segfault@hardline.org>)           test needs
+                                                                    work.
+ Linux 2.2.x  x86       7.0     2000-03-26, Lamar Owen
+                                (<lamar.owen@wgcr.org>)
+ Linux 2.0.x  MIPS      7.0     2000-04-13, Tatsuo Ishii            Cobalt Qube
+                                (<t-ishii@sra.co.jp>)
+ Linux 2.2.5  Sparc     7.0     2000-04-02, Tom Szybist
+                                (<szybist@boxhill.com>)
+ LinuxPPC R4  PPC603e   7.0     2000-04-13, Tatsuo Ishii
+                                (<t-ishii@sra.co.jp>)
+ mklinux      PPC750    7.0     2000-04-13, Tatsuo Ishii
+                                (<t-ishii@sra.co.jp>)
+ NetBSD 1.4   arm32     7.0     2000-04-08, Patrick Welche
+                                (<prlw1@newn.cam.ac.uk>)
+ NetBSD 1.4U  x86       7.0     2000-03-26, Patrick Welche
+                                (<prlw1@newn.cam.ac.uk>)
+ NetBSD       m68k      7.0     2000-04-10, Henry B. Hotz           Mac 8xx
+                                (<hotz@jpl.nasa.gov>)
+ NetBSD       Sparc     7.0     2000-04-13, Tom I. Helbekkmo
+                                (<tih@kpnQwest.no>)
+ QNX 4.25     x86       7.0     2000-04-01, Dr. Andreas Kardos
+                                (<kardos@repas-aeg.de>)
+ SCO          x86       6.5     1999-05-25, Andrew Merrill
+ OpenServer 5                   (<andrew@compclass.com>)
+ SCO UnixWare x86       7.0     2000-04-18, Billy G. Allie          See also
+ 7                              (<Bill.Allie@mug.org>)              doc/FAQ_SCO
+ Solaris      x86       7.0     2000-04-12, Marc Fournier
+                                (<scrappy@hub.org>)
+ Solaris      Sparc     7.0     2000-04-12, Peter Eisentraut
+ 2.5.1-2.7                      (<peter_e@gmx.net>), Marc Fournier
+                                (<scrappy@hub.org>)
+ SunOS 4.1.4  Sparc     7.0     2000-04-13, Tatsuo Ishii
+                                (<t-ishii@sra.co.jp>)
+ Windows/Win32x86       7.0     2000-04-02, Magnus Hagander         Client-side
+                                (<mha@sollentuna.net>)              libraries or
+                                                                    ODBC/JDBC, no
+                                                                    server-side
+ WinNT/Cygwin x86       7.0     2000-03-30, Daniel Horak            with
+                                (<horak@sit.plzen-city.cz>)         RedHat/Cygnus
+                                                                    Cygwin toolset
+
+Unsupported Platforms. The following platforms have not been verified to
+work. Platforms listed for version 6.3.x and later should also work with
+7.1, but we did not receive explicit confirmation of such at the time this
+list was compiled. We include these here to let you know that these
+platforms could be supported if given some attention.
+
+ OS        Processor Version Reported                        Remarks
+ BeOS      x86       7.0     2000-05-01, Adam Haberlach      Client-side
+                             (<adam@newsnipple.com>)         coming soon?
+ DGUX      m88k      6.3     1998-03-01, Brian E Gallew      6.4 probably
+ 5.4R4.11                    (<geek+@cmu.edu>)               OK. Needs new
+                                                             maintainer.
+ NetBSD 1.3VAX       6.3     1998-03-01, Tom I Helbekkmo     7.0 should
+                             (<tih@kpnQwest.no>)             work.
+ System V  m88k      6.2.1   1998-03-01, Doug Winterburn     Needs new TAS
+ R4 4.4                      (<dlw@seavme.xroads.com>)       spinlock code
+ System V  MIPS      6.4     1998-10-28, Frank Ridderbusch   No 64-bit
+ R4                          (<ridderbusch.pad@sni.de>)      integer
+ Ultrix    MIPS, VAX 6.x     1998-03-01                      No recent
+                                                             reports.
+                                                             Obsolete?
+ MacOS     all       6.x     1998-03-01                      Not library
+                                                             compatible;
+                                                             use ODBC/JDBC.
+ NextStep  x86       6.x     1998-03-01, David Wetzel        Client-only
+                             (<dave@turbocat.de>)            support
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index db71acb2956..f9bf7b831fd 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -8,7 +8,7 @@
 #
 #
 # IDENTIFICATION
-#    $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.16 2000/07/16 14:50:38 petere Exp $
+#    $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.17 2000/07/21 00:44:11 petere Exp $
 #
 #----------------------------------------------------------------------------
 
@@ -199,3 +199,22 @@ distclean:
 %.gif:
 	cp -p ../graphics/$@ .
 
+
+# Generation of the INSTALL text file. Not fully automated, but better
+# than nothing.
+.PHONY: INSTALL
+INSTALL: INSTALL.html
+	@echo "|";\
+	 echo "| You should now take \`$<', save it as a text file in Netscape,";\
+	 echo "| and put it in place of the existing \`INSTALL' file.";\
+	 echo "|"
+	@rm -f tempfile.html tempfile.sgml
+
+INSTALL.html: tempfile.html
+	sed -e 's/Chapter 1. *//g' < $< > $@
+
+tempfile.html: tempfile.sgml
+	jade -d $(HDSL) -V nochunks -t sgml $< > $@
+
+tempfile.sgml: standalone-install.sgml installation.sgml
+	cat $+ > $@
diff --git a/doc/src/sgml/admin.sgml b/doc/src/sgml/admin.sgml
index 7eb80a71073..0fce2cc9af2 100644
--- a/doc/src/sgml/admin.sgml
+++ b/doc/src/sgml/admin.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.24 2000/06/30 16:14:21 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.25 2000/07/21 00:44:12 petere Exp $
 
 Postgres Administrator's Guide.
 Derived from postgres.sgml.
@@ -8,6 +8,9 @@ Derived from postgres.sgml.
 
 <!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
 
+<!entity version "7.1">
+<!entity majorversion "7.1">
+
 <!entity about     SYSTEM "about.sgml">
 <!entity history   SYSTEM "history.sgml">
 <!entity info      SYSTEM "info.sgml">
@@ -16,13 +19,9 @@ Derived from postgres.sgml.
 <!entity problems  SYSTEM "problems.sgml">
 <!entity y2k       SYSTEM "y2k.sgml">
 
-<!entity config    SYSTEM "config.sgml">
 <!entity intro-ag  SYSTEM "intro-ag.sgml">
-<!entity install   SYSTEM "install.sgml">
+<!entity installation SYSTEM "installation.sgml">
 <!entity installw  SYSTEM "install-win32.sgml">
-<!entity layout    SYSTEM "layout.sgml">
-<!entity ports     SYSTEM "ports.sgml">
-<!entity release   SYSTEM "release.sgml">
 <!entity runtime   SYSTEM "runtime.sgml">
 <!entity client-auth SYSTEM "client-auth.sgml">
 <!entity manage-ag SYSTEM "manage-ag.sgml">
@@ -30,8 +29,13 @@ Derived from postgres.sgml.
 <!entity backup    SYSTEM "backup.sgml">
 <!entity recovery  SYSTEM "recovery.sgml">
 <!entity regress   SYSTEM "regress.sgml">
+<!entity release   SYSTEM "release.sgml">
 
 <!entity biblio    SYSTEM "biblio.sgml">
+
+<!-- see standalone-install.sgml about these -->
+<!entity % flattext-install-ignore  "INCLUDE">
+<!entity % flattext-install-include "IGNORE">
 ]>
 
 <book id="admin">
@@ -75,19 +79,6 @@ Derived from postgres.sgml.
 
  </bookinfo>
 
-<!--
-<TOC> </TOC>
-<LOT> </LOT>
--->
-
-<!--
-<Dedication>
-<Para>
-Your name here...
-</Para>
-</Dedication>
--->
-
  <preface id="preface">
   <title>Summary</title>
 
@@ -104,11 +95,7 @@ Your name here...
  </preface>
 
   &intro-ag;
-
-  &ports;
-  &config;
-  &layout;
-  &install;
+  &installation;
   &installw;
   &runtime;
   &client-auth;
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 842cfec9d4c..204692705dc 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.1 2000/06/30 16:14:21 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.2 2000/07/21 00:44:12 petere Exp $ -->
 <chapter id="backup">
  <title>Backup and Restore</title>
 
@@ -340,7 +340,7 @@ tar -cf backup.tar /usr/local/pgsql/data
 
  </sect1>
 
- <sect1>
+ <sect1 id="migration">
   <title>Migration between releases</title>
 
   <para>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
deleted file mode 100644
index c80a8beb800..00000000000
--- a/doc/src/sgml/config.sgml
+++ /dev/null
@@ -1,282 +0,0 @@
- <chapter>
-  <title>Configuration Options</title>
-
-  <sect1>
-   <title>Parameters for Configuration
-    (<application>configure</application>)</title>
-
-   <para>
-    The full set of parameters available in <application>configure</application>
-    can be obtained by typing
-   
-    <programlisting>
-$ ./configure --help
-    </programlisting>
-   </para>
-
-   <para>
-    The following parameters may be of interest to installers:
-   
-    <programlisting>
-Directories to install PostgreSQL in:
-  --prefix=PREFIX         install architecture-independent files in PREFIX
-                          [/usr/local/pgsql]
-  --bindir=DIR            user executables in DIR [EPREFIX/bin]
-  --libdir=DIR            object code libraries in DIR [EPREFIX/lib]
-  --includedir=DIR        C header files in DIR [PREFIX/include]
-  --mandir=DIR            man documentation in DIR [PREFIX/man]
-Features and packages:
-  --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
-  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
-  --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
-  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
---enable and --with options recognized:
-  --with-template=<replaceable>template</replaceable>
-                          use operating system template file
-                              see template directory
-  --with-includes=<replaceable>dirs</replaceable>    look for header files for tcl/tk, etc in DIRS
-  --with-libraries=<replaceable>dirs</replaceable>   look for additional libraries in DIRS
-  --with-libs=<replaceable>dirs</replaceable>        alternate spelling of --with-libraries
-  --enable-locale         enable locale support
-  --enable-recode         enable cyrillic recode support
-  --enable-multibyte      enable multibyte character support
-  --with-pgport=<replaceable>portnum</replaceable>   change default postmaster port
-  --with-maxbackends=<replaceable>n</replaceable>    set default maximum number of server processes 
-  --with-tcl              build Tcl interfaces and pgtclsh
-  --with-tclconfig=<replaceable>tcldir</replaceable>
-                          tclConfig.sh and tkConfig.sh are in DIR
-  --with-perl             build Perl interface and plperl
-  --with-odbc             build ODBC driver package
-  --with-odbcinst=<replaceable>odbcdir</replaceable>
-                          change default directory for odbcinst.ini
-  --enable-cassert        enable assertion checks (for debugging)
-  --enable-debug          build with debugging symbols (-g) 
-  --with-CC=<replaceable>compiler</replaceable>
-                          use specific C compiler
-  --with-CXX=<replaceable>compiler</replaceable>
-                          use specific C++ compiler
-  --without-CXX           prevent building C++ code 
-    </programlisting>
-   </para>
-
-   <para>
-    Some systems may have trouble building a specific feature of
-    <productname>Postgres</productname>. For example, systems with a damaged
-    C++ compiler may need to specify <option>--without-CXX</option> to instruct
-    the build procedure to skip construction of <filename>libpq++</filename>.
-   </para>
-
-   <para>
-    Use the <option>--with-includes</option> and
-    <option>--with-libraries</option> options if you want to build
-    <productname>Postgres</productname> using include files or libraries
-    that are not installed in your system's standard search path.  For
-    example, you might use these to build with an experimental version of
-    Tcl.  If you need to specify more than one nonstandard directory for
-    include files or libraries, do it like this:
-
-    <programlisting>
---with-includes="/opt/tcl/include /opt/perl5/include"
-    </programlisting>
-   </para>
-  </sect1>
-
-  <sect1>
-   <title>Parameters for Building (<application>make</application>)</title>
-  
-   <para>
-    Many installation-related parameters can be set in the building
-    stage of <productname>Postgres</productname> installation.
-   </para>
-
-   <para>
-    In most cases, these parameters should be placed in a file,
-    <filename>Makefile.custom</filename>, intended just for that purpose.
-    The default distribution does not contain this optional file, so you
-    will create it using a text editor of your choice. When upgrading installations,
-    you can simply copy your old Makefile.custom to the new installation before
-    doing the build.
-   </para>
-
-   <para>
-    Alternatively, you can set variables on the <application>make</application>
-    command line:
-
-    <programlisting>
-make [ <replaceable>variable</replaceable>=<replaceable>value</replaceable> [...] ]
-    </programlisting>
-   </para>
-
-   <para>
-    A few of the many variables that can be specified are:
-   
-    <variablelist>
-     <varlistentry>
-      <term>
-       <envar>POSTGRESDIR</envar>
-      </term>
-      <listitem>
-       <para>
-	Top of the installation tree.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term>
-       <envar>BINDIR</envar>
-      </term>
-      <listitem>
-       <para>
-	Location of applications and utilities.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term>
-       <envar>LIBDIR</envar>
-      </term>
-      <listitem>
-       <para>
-	Location of object libraries, including shared libraries.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term>
-       <envar>HEADERDIR</envar>
-      </term>
-      <listitem>
-       <para>
-	Location of include files.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term>
-       <envar>ODBCINST</envar>
-      </term>
-      <listitem>
-       <para>
-	Location of installation-wide <application>psqlODBC</application>
-	(<acronym>ODBC</acronym>) configuration file.
-       </para>
-      </listitem>
-     </varlistentry>
-
-    </variablelist>
-   </para>
-   <para>
-    There are other optional parameters which are not as commonly used.
-    Many of those listed below are appropriate when doing 
-    <application>Postgres</application> server code development.
-
-    <variablelist>
-     <varlistentry>
-      <term>
-       <envar>CFLAGS</envar>
-      </term>
-      <listitem>
-       <para>
-	Set flags for the C compiler. 
-	Should be assigned with "+=" to retain relevant default parameters.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term>
-       <envar>YFLAGS</envar>
-      </term>
-      <listitem>
-       <para>
-	Set flags for the yacc/bison parser. <option>-v</option> might be
-	used to help diagnose problems building a new parser.
-	Should be assigned with "+=" to retain relevant default parameters.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term>
-       <envar>USE_TCL</envar>
-      </term>
-      <listitem>
-       <para>
-	Enable Tcl interface building.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term>
-       <envar>HSTYLE</envar>
-      </term>
-      <listitem>
-       <para>
-	DocBook <acronym>HTML</acronym> style sheets for building the 
-	documentation from scratch.
-	Not used unless you are developing new documentation from the
-	DocBook-compatible <acronym>SGML</acronym> source documents in
-	<filename>doc/src/sgml/</filename>.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term>
-       <envar>PSTYLE</envar>
-      </term>
-      <listitem>
-       <para>
-	DocBook style sheets for building printed documentation from scratch.
-	Not used unless you are developing new documentation from the
-	DocBook-compatible <acronym>SGML</acronym> source documents in
-	<filename>doc/src/sgml/</filename>.
-       </para>
-      </listitem>
-     </varlistentry>
-
-    </variablelist>
-   </para>
-
-   <para>
-    Here is an example <filename>Makefile.custom</filename> for a
-    PentiumPro Linux system:
-   
-    <programlisting>
-# Makefile.custom
-# Thomas Lockhart 1999-06-01
-
-POSTGRESDIR= /opt/postgres/current
-CFLAGS+= -m486 -O2
-
-# documentation
-
-HSTYLE= /home/tgl/SGML/db118.d/docbook/html
-PSTYLE= /home/tgl/SGML/db118.d/docbook/print
-    </programlisting>
-   </para>
-  </sect1>
-
-</chapter>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode:sgml
-sgml-omittag:nil
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"./reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:("/usr/lib/sgml/catalog")
-sgml-local-ecat-files:nil
-End:
--->
diff --git a/doc/src/sgml/install.sgml b/doc/src/sgml/install.sgml
deleted file mode 100644
index 50fe9695d48..00000000000
--- a/doc/src/sgml/install.sgml
+++ /dev/null
@@ -1,658 +0,0 @@
-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/install.sgml,v 1.45 2000/06/05 17:07:53 momjian Exp $
--->
-
- <chapter id="install">
-  <title>Installation</title>
-
-  <abstract>
-   <para>
-    Installation instructions for 
-    <productname>PostgreSQL</productname> 7.0.2.
-   </para>
-  </abstract>
-
-  <para>
-   If you haven't gotten the <productname>PostgreSQL</productname> distribution,
-   get it from <ulink url="ftp://ftp.postgresql.org">ftp.postgresql.org</ulink>,
-   then unpack it:
-
-   <programlisting>
-&gt; gunzip postgresql-7.0.2.tar.gz
-&gt; tar -xf postgresql-7.0.2.tar
-&gt; mv postgresql-7.0.2 /usr/src
-   </programlisting>
-  </para>
-
-  <sect1>
-   <title>Before you start</title>
-
-   <para>
-    Building <productname>PostgreSQL</productname> requires <acronym>GNU</acronym>
-    <application>make</application>.  It will <emphasis>not</emphasis>
-    work with other <application>make</application> programs. On GNU/Linux systems
-    GNU make is the default tool, on other systems you may find that
-    GNU <application>make</application> is installed under the name
-    <literal>gmake</literal>.
-    We will use that name from now on to indicate <acronym>GNU</acronym>
-    <application>make</application>, no matter what name it has on your system.
-    To test for <acronym>GNU</acronym> <application>make</application> enter
-    <programlisting>
-&gt; <userinput>gmake --version</userinput>
-    </programlisting>
-    If you need to get <acronym>GNU</acronym>
-    <application>make</application>, you can
-    find it at <ulink url="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ulink>.
-   </para>
-
-   <para>
-    Up to date information on supported platforms is at
-    <ulink url="http://www.postgresql.org/docs/admin/ports.htm">
-     http://www.postgresql.org/docs/admin/ports.htm</ulink>.
-    In general, most Unix-compatible platforms with modern libraries
-    should be able to run
-    <productname>PostgreSQL</productname>. In the
-    <filename>doc</filename> subdirectory
-    of the distribution are several platform-specific FAQ and README documents you
-    might wish to consult if you are having trouble.
-   </para>
-
-   <para>
-    Although the minimum required memory for running
-    <productname>PostgreSQL</productname> 
-    can be as little as 8MB, there are noticeable speed improvements
-    when expanding memory
-    up to 96MB or beyond. The rule is you can never have too much memory.
-   </para>
-   <para>
-    Check that you have sufficient disk space.  You will need about
-    30 Mbytes for the source tree during compilation and about 5 Mbytes for
-    the installation directory. An empty database takes about 1 Mbyte, otherwise
-    they take about five times the amount of space that a flat text file with the
-    same data would take. If you run the regression tests you will temporarily need
-    an extra 20MB.
-   </para>
-
-   <para>
-    To check for disk space, use 
-<programlisting>
-&gt; df -k
-</programlisting>
-   </para>
-
-   <para>
-    Considering today's prices for hard disks, getting a large and
-    fast hard disk should
-    probably be in your plans before putting a database into production use.
-   </para>
-  </sect1>
-
-  <sect1>
-   <title>Installation Procedure</title>
-
-   <procedure>
-    <title><productname>PostgreSQL</productname> Installation</title>
-
-    <para>
-     For a fresh install or upgrading from previous releases of
-     <productname>PostgreSQL</productname>:
-    </para>
-
-    <step performance="optional">
-     <para>
-      Create the <productname>PostgreSQL</productname> superuser account.
-      This is the user the server will run as. For production use you
-      should create a separate, unprivileged account
-      (<literal>postgres</literal> is commonly used).
-      If you do not have root access or just want to play around,
-      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;
-      <emphasis>don't do it</emphasis>.  The postmaster will in fact refuse
-      to start as <literal>root</literal>.
-     </para>
-     <para>
-      You need not do the building and installation itself under this account
-      (although you can). You will be told when you need to login as the
-      database superuser.
-     </para>
-    </step>
-
-    <step performance="required">
-     <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>
-      subdirectory and type:
-      <programlisting>
-&gt; ./configure
-      </programlisting>
-      followed by any options you might want to give it. For a first installation
-      you should be able to do fine without any.
-      For a complete list of options, type:
-      <programlisting>
-&gt; ./configure --help
-      </programlisting>
-      Some of the more commonly used ones are:
-      <variablelist>
-       <varlistentry>
-	<term>--prefix=BASEDIR</term>
-	<listitem>
-	 <para>
-	  Selects a different base directory for the installation of
-	  <productname>PostgreSQL</productname>. The default is
-	  <filename>/usr/local/pgsql</filename>. 
-	 </para>
-	</listitem>
-       </varlistentry>
-
-       <varlistentry>
-	<term>--enable-locale</term>
-	<listitem>
-	 <para>
-	  If you want to use locales.
-	 </para>
-	</listitem>
-       </varlistentry>
-
-       <varlistentry>
-	<term>--enable-multibyte</term>
-	<listitem>
-	 <para>
-	  Allows the use of multibyte character encodings. This is primarily for
-	  languages like Japanese, Korean, or Chinese.
-	 </para>
-	</listitem>
-       </varlistentry>
-
-       <varlistentry>
-	<term>--with-perl</term>
-	<listitem>
-	 <para>
-	  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 perform the installation step.  (It is often easiest to leave out
-	  <option>--with-perl</option> initially, and then build and install the
-	  Perl interface after completing the installation of PostgreSQL
-	  itself.)
-	 </para>
-	</listitem>
-       </varlistentry>
-
-       <varlistentry>
-	<term>--with-odbc</term>
-	<listitem>
-	 <para>
-	  Builds the ODBC driver package.
-	 </para>
-	</listitem>
-       </varlistentry>
-
-       <varlistentry>
-	<term>--with-tcl</term>
-	<listitem>
-	 <para>
-	  Builds interface libraries and programs requiring
-	  Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh.
-	 </para>
-	</listitem>
-       </varlistentry>
-      </variablelist>
-
-     </para>
-    </step>
-
-    <step performance="required">
-     <para>
-      Compile the program.  Type
-      <programlisting>
-&gt; gmake
-      </programlisting>
-      The compilation process can take anywhere from 10 minutes to an hour.
-      Your mileage will most certainly vary. Remember to use GNU make.
-     </para>
-
-     <para>
-      The last line displayed will hopefully be 
-      <programlisting>
-All of PostgreSQL is successfully made. Ready to install.
-      </programlisting>
-     </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 endterm="regress-title"
-       linkend="regress">.
-      (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>
-      If you are not upgrading an existing system, skip to 
-      <xref linkend="continue">.
-     </para>
-     <para>
-     If you are running 7.*, skip to step
-     <xref linkend="nodump">.
-      </para>
-     <para>
-      You now need to back up your existing database.
-      To dump your database installation, type:
-      <programlisting>
-&gt; 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.2's <application>pg_dumpall</application> should not
-      be used on older databases.
-     </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>
-     <para>
-     Rather than using <application>pg_dumpall</application>,
-     <application>pg_upgrade</application> can often be used.
-     </para>
-    </step>
-
-    <step performance="required" id="nodump">
-     <para>
-      If you are upgrading an existing system, kill the database
-      server now. Type
-      <programlisting>
-&gt; ps ax | grep postmaster
-      </programlisting>
-      or
-      <programlisting>
-&gt; 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>
-&gt; 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 that will accomplish the same
-       thing. For example, on a
-       Redhat Linux system one might find that
-       <programlisting>
-&gt; /etc/rc.d/init.d/postgres.init stop
-       </programlisting>
-       works.
-      </para>
-     </tip>
-
-     <para>
-      If you used pg_dumpall, move the old directory out of the way.
-      Type the following:      
-<programlisting>
-&gt; 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>
-&gt; 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>
-      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>
-&gt; LD_LIBRARY_PATH=/usr/local/pgsql/lib
-&gt; export LD_LIBRARY_PATH
-      </programlisting>
-      on sh, ksh, bash, zsh or
-      <programlisting>
-&gt; setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
-      </programlisting>
-      on csh or tcsh.
-      You might want to put this into a shell startup file such as
-      <filename>/etc/profile</filename>.
-     </para>
-
-     <para>
-      On some systems the following is the preferred method, but you must have root
-      access. Edit file <filename>/etc/ld.so.conf</filename> to add a line
-      <programlisting>
-<filename>/usr/local/pgsql/lib</filename>
-      </programlisting>
-      Then run command <command>/sbin/ldconfig</command>.
-     </para>
-
-     <para>
-      If in doubt, refer to the manual pages of your system. If you later on get
-      a message like
-      <programlisting>
-psql: error in loading shared libraries
-libpq.so.2.1: cannot open shared object file: No such file or directory
-      </programlisting>
-      then the above was necessary.  Simply do this step then.
-     </para>
-    </step>
-
-    <step performance="required">
-     <para>
-      If you moved the old directory out of the way, 
-      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>
-&gt; mkdir /usr/local/pgsql/data
-&gt; chown postgres /usr/local/pgsql/data
-&gt; su - postgres
-&gt; /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
-      </programlisting>
-     </para>
-     <para>
-      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, 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 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.  The command should look something like
-      <programlisting>
-&gt; /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, 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>
-&gt; nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
-    &lt;/dev/null &gt;>server.log 2&gt;>1 &amp;
-      </programlisting>
-     </para>
-    </step>
-
-    <step performance="optional">
-     <para>
-      If you did a pg_dumpall, reload your data back in:
-      <programlisting>
-&gt; /usr/local/pgsql/bin/psql -d template1 -f db.out
-      </programlisting>
-      You also might want to copy over the old <filename>pg_hba.conf</filename>
-      file and any other files you might have had set up for authentication, such
-      as password files.
-     </para>
-    </step>
-   </procedure>
-
-   <para>
-    This concludes the installation proper. To make your life more
-    productive and enjoyable
-    you should look at the following optional steps and suggestions:
-   </para>
-
-   <itemizedlist>
-    <listitem>
-     <para>
-      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>, 
-      if you want it to affect every user):
-      <programlisting>
-&gt; PATH=$PATH:/usr/local/pgsql/bin
-      </programlisting>
-     </para>
-     <para>
-      Furthermore, if you set <envar>PGDATA</envar> in the environment
-      of the PostgreSQL
-      superuser, you can omit the <option>-D</option> for
-      <filename>postmaster</filename> 
-      and <filename>initdb</filename>.
-     </para>
-    </listitem>
-
-    <listitem>
-     <para>
-      You probably want to install the <application>man</application> and
-      <acronym>HTML</acronym> documentation. Type
-      <programlisting>
-&gt; cd /usr/src/pgsql/postgresql-7.0.2/doc
-&gt; gmake install
-      </programlisting>
-      This will install files under <filename>/usr/local/pgsql/doc</filename>
-      and <filename>/usr/local/pgsql/man</filename>. To enable your system
-      to find the <application>man</application> documentation, you need to
-      add a line like the following to a shell startup file:
-      <programlisting>
-&gt; MANPATH=$MANPATH:/usr/local/pgsql/man
-      </programlisting>
-     </para>
-
-     <para>
-      The documentation is also available in Postscript format. If you have
-      a Postscript printer, or have your machine already set up to accept
-      Postscript files using a print filter, then to print the User's Guide
-      simply type
-      <programlisting>
-&gt; cd /usr/local/pgsql/doc
-&gt; gunzip -c user.ps.tz | lpr
-      </programlisting>
-      Here is how you might do it if you have Ghostscript on your system and are
-      writing to a laserjet printer.
-      <programlisting>
-&gt; gunzip -c user.ps.gz \
-    | gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- \
-    | lpr
-      </programlisting>
-      Printer setups can vary wildly from system to system.
-      If in doubt, consult your manuals or your local expert.
-     </para>
-
-     <para>
-      The Adminstrator's Guide should probably be your first reading if you
-      are completely new to <productname>PostgreSQL</productname>, as it contains
-      information about how to set up database users and authentication.
-     </para>
-    </listitem>
-
-    <listitem>
-     <para>
-      Usually, you will want to modify your computer so that it will automatically
-      start the database server whenever it boots.
-      This is not required; the <productname>PostgreSQL</productname> server can
-      be run successfully from non-privileged accounts without root intervention.
-     </para>
-     <para>
-      Different systems have different conventions for starting up
-      daemons at boot time,
-      so you are advised to familiarize yourself with them.
-      Most systems have a file <filename>/etc/rc.local</filename> or
-      <filename>/etc/rc.d/rc.local</filename> which is almost
-      certainly no bad place
-      to put such a command.
-      Whatever you do, postmaster must be run by the
-      <productname>PostgreSQL</productname> 
-      superuser (<literal>postgres</literal>) <emphasis>and not by
-       root</emphasis> or
-      any other user. Therefore you probably always want to form your command lines
-      along the lines of <literal>su -c '...' postgres</literal>.
-     </para>
-     <para>
-      It might be advisable to keep a log of the server output. To
-      start the server that way
-      try:
-      <programlisting>
-&gt; nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &
-      </programlisting>
-     </para>
-
-     <para>
-      Here are a few more operating system specific suggestions.
-
-      <itemizedlist>
-       <listitem>
-	<para>
-	 Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
-	 2.5.1 to contain the following single line:
-	 <programlisting>
-&gt; su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
-	 </programlisting>
-	</para>
-       </listitem>
-
-       <listitem>
-	<para>
-	 In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
-	 contain the following lines and make it chmod 755 and chown
-	 root:bin.
-
-	 <programlisting>
-#!/bin/sh
-[ -x /usr/local/pgsql/bin/postmaster ] && {
-    su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
-        -D/usr/local/pgsql/data
-        -S -o -F > /usr/local/pgsql/errlog' &
-    echo -n ' pgsql'
-}
-	 </programlisting>
-
-	 You may put the line breaks as shown above.  The shell is smart
-	 enough to keep parsing beyond end-of-line if there is an
-	 expression unfinished.  The exec saves one layer of shell under
-	 the postmaster process so the parent is init.
-	</para>
-       </listitem>
-
-       <listitem>
-	<para>
-	 In RedHat Linux add a file
-	 <filename>/etc/rc.d/init.d/postgres.init</filename> 
-	 which is based on the example in <filename>contrib/linux/</filename>.
-	 Then make a softlink to this file from
-	 <filename>/etc/rc.d/rc5.d/S98postgres.init</filename>.
-	</para>
-       </listitem>
-
-      </itemizedlist>
-
-     </para>
-    </listitem>
-
-    <listitem>
-     <para>
-      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 endterm="regress-title" linkend="regress">.
-     </para>
-    </listitem>
-
-   </itemizedlist>
-
-   <para>
-    To start experimenting with <productname>Postgres</productname>,
-    set up the paths as explained above
-    and start the server. To create a database, type
-
-    <programlisting>
-&gt; createdb testdb
-    </programlisting>
-
-    Then enter
-
-    <programlisting>
-&gt; psql testdb
-    </programlisting>
-
-    to connect to that database. At the prompt you can enter SQL commands
-    and start experimenting.
-   </para>
-
-  </sect1>
- </chapter>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode:sgml
-sgml-omittag:nil
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"./reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:("/usr/lib/sgml/catalog")
-sgml-local-ecat-files:nil
-End:
--->
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index ad6dada56fd..fe2fbcf6858 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1,141 +1,1317 @@
-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.11 2000/05/04 16:15:08 thomas Exp $
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.12 2000/07/21 00:44:12 petere Exp $ -->
 
-Postgres quick Installation Guide.
-- thomas 1998-10-26
--->
+<chapter id="installation">
+ <title><![%flattext-install-include[<productname>PostgreSQL</> ]]>Installation Instructions</title>
+
+ <sect1 id="short">
+  <title>Short Version</title>
+
+  <para>
+<programlisting>
+./configure
+gmake
+gmake install
+adduser postgres
+su - postgres
+/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
+/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data &gt;logfile 2&gt;&amp;1 &amp;
+/usr/local/pgsql/bin/createdb test
+/usr/local/pgsql/bin/psql test
+</programlisting>
+   The long version is the rest of this
+   <![%flattext-install-include;[document.]]>
+   <![%flattext-install-ignore;[chapter.]]>
+  </para>
+ </sect1>
 
-<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
-
-<!entity about    SYSTEM "about.sgml">
-<!entity history  SYSTEM "history.sgml">
-<!entity info     SYSTEM "info.sgml">
-<!entity legal    SYSTEM "legal.sgml">
-<!entity notation SYSTEM "notation.sgml">
-<!entity y2k      SYSTEM "y2k.sgml">
-
-<!entity config   SYSTEM "config.sgml">
-<!entity intro-ag SYSTEM "intro-ag.sgml">
-<!entity install  SYSTEM "install.sgml">
-<!entity options  SYSTEM "pg_options.sgml">
-<!entity ports    SYSTEM "ports.sgml">
-<!entity recovery SYSTEM "recovery.sgml">
-<!entity regress  SYSTEM "regress.sgml">
-<!entity release  SYSTEM "release.sgml">
-<!entity runtime  SYSTEM "runtime.sgml">
-<!entity start-ag SYSTEM "start-ag.sgml">
-
-<!entity biblio   SYSTEM "biblio.sgml">
-]>
-
-<book id="installation">
-
-<!-- Title information -->
-
- <title>PostgreSQL Installation Guide</title>
- <bookinfo>
-  <releaseinfo>Covering v7.0 for general release</releaseinfo>
-  <bookbiblio>
-   <authorgroup>
-    <corpauthor>The PostgreSQL Development Team</corpauthor>
-   </authorgroup>
-<!-- editor in authorgroup is not supported
-    <AuthorGroup>
--->
-   <editor>
-    <firstname>Thomas</firstname>
-    <surname>Lockhart</surname>
-    <affiliation>
-     <orgname>Caltech/JPL</orgname>
-    </affiliation>
-   </editor>
-<!--
-    </AuthorGroup>
--->
- 
-<!--
-    <AuthorInitials>TGL</AuthorInitials>
--->
 
-   <date>(last updated 2000-05-01)</date>
-  </bookbiblio>
+ <sect1 id="requirements">
+  <title>Requirements</title>
 
-  <legalnotice>
+  <para>
+   In general, a modern Unix-compatible platform should be able to run
+   PostgreSQL. The platforms that had received explicit testing at the
+   time of release are listed in <xref linkend="supported-platforms">
+   below. In the <filename>doc</> subdirectory of the distribution
+   there are several platform-specific <acronym>FAQ</> documents you
+   might wish to consult if you are having trouble.
+  </para>
+
+  <formalpara>
+   <title>Compiler</>
+   <para>
+    You need a Standard (<quote>ANSI</>) C compiler. Recent versions
+    of <productname>GCC</> are recommendable, but <productname>PostgreSQL</> is known to
+    build with a wide variety of compilers from different vendors.
+   </para>
+  </formalpara>
+    
+  <formalpara>
+   <title>Make</title>
    <para>
-    <productname>PostgreSQL</productname> is Copyright &copy; 1996-2000
-    by PostgreSQL Inc.
+    Building <productname>PostgreSQL</> requires <acronym>GNU</> <application>make</>; it
+    will <emphasis>not</> work with other <application>make</>
+    programs. <acronym>GNU</> <application>make</> is often installed
+    under the name <filename>gmake</filename>. This document will
+    always refer to it by that name. (On GNU/Linux systems GNU make is
+    the default tool with the name <filename>make</filename>.) To test
+    for <acronym>GNU</acronym> <application>make</application> enter
+<screen>
+<userinput>gmake --version</userinput>
+</screen>
+    If at all possible you should try to use version 3.76.1 or later.
+    If you need to get <acronym>GNU</acronym>
+    <application>make</application>, you can find it at your local
+    <acronym>GNU</acronym> mirror site (see <ulink
+    url="http://www.gnu.org/order/ftp.html">http://www.gnu.org/order/ftp.html</>)
+    or at <ulink
+    url="ftp://ftp.gnu.org/gnu/make">ftp://ftp.gnu.org/gnu/make</ulink>.
    </para>
-  </legalnotice>
+  </formalpara>
 
- </bookinfo>
+  <formalpara>
+   <title>Resources</>
+   <para>
+    Check that you have sufficient disk space. You will need about 30
+    MB for the source tree during compilation and about 5 MB for the
+    installation directory. An empty database takes about 1 MB, later
+    it takes about five times the amount of space that a flat text
+    file with the same data would take. If you are going to run the
+    regression tests you will temporarily need an extra 20 MB. Use the
+    <command>df</command> command to check for disk space.
+   </para>
+  </formalpara>
+ </sect1>
 
-<!--
-<TOC> </TOC>
-<LOT> </LOT>
--->
+<![%flattext-install-ignore;[
+ <sect1>
+  <title>Getting The Source</title>
 
-<!--
-<Dedication>
-<Para>
-Your name here...
-</Para>
-</Dedication>
--->
+  <para>
+   The <productname>PostgreSQL</> &version; sources can by obtained from <ulink
+   url="ftp://ftp.postgresql.org/pub/postgresql-&version;.tar.gz"
+   >ftp://ftp.postgresql.org/pub/postgresql-&version;.tar.gz</ulink>.
+   Use a mirror if possible. Then unpack it:
+<screen>
+<userinput>gunzip postgresql-&version;.tar.gz</userinput>
+<userinput>tar xf postgresql-&version;.tar</userinput>
+</screen>
+   This will create a directory
+   <filename>postgresql-&version;</filename> with the <productname>PostgreSQL</> sources
+   in the current directory. Change into that directory for the rest
+   of the installation procedure.
+  </para>
+ </sect1>
+]]>
+
+ <sect1 id="install-upgrading">
+  <title>If You Are Upgrading</title>
+
+  <para>
+   The internal data storage format changes with new releases of
+   <productname>PostgreSQL</>. Therefore, if you are upgrading an existing installation
+   that does not have a version number
+   <quote>&majorversion;.x</quote>, you must back up and restore your
+   data as shown here. These instructions assume that your existing
+   installation is under the <filename>/usr/local/pgsql</> directory,
+   and that the data area is in <filename>/usr/local/pgsql/data</>.
+   Substitute your paths appropriately.
+  </para>
+
+  <procedure>
+   <step>
+    <para>
+     Make sure that your database is not updated during or after the
+     backup. This does not affect the integrity of the backup, but the
+     changed data would of course not be included. If necessary, edit
+     the permissions in the file
+     <filename>/usr/local/pgsql/data/pg_hba.conf</> (or equivalent) to
+     disallow access from everyone except you.
+    </para>
+   </step>
+
+   <step>
+    <para>
+     To dump your database installation, type:
+<screen>
+<userinput>pg_dumpall &gt; <replaceable>outputfile</></userinput>
+</screen>
+     If you need to preserve the oids (such as when using them as
+     foreign keys), then use the -o option when running
+     <application>pg_dumpall</>.
+    </para>
+
+    <para>
+     Make sure that you use the <application>pg_dumpall</> command
+     from the version you are currently running. &version;'s
+     <application>pg_dumpall</> should not be used on older databases.
+    </para>
+   </step>
 
- <preface>
-  <title>Summary</title>
+   <step>
+    <para>
+     If you are installing the new version at the same location as the
+     old one then shut down the old server, at the latest before you
+     install the new files:
+<screen>
+<userinput>kill -INT `cat /usr/local/pgsql/data/postmaster.pid`</>
+</screen>
+     Versions prior to 7.0 do not have this
+     <filename>postmaster.pid</> file. If you are using such a version
+     you must find out the process id of the server yourself, for
+     example by typing <userinput>ps ax | grep postmaster</>, and
+     supply it to the <command>kill</> command.
+    </para>
+
+    <para>
+     On systems which have <productname>PostgreSQL</> started at boot time, there is
+     probably a startup file that 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>
+   </step>
+
+   <step>
+    <para>
+     If you are installing in the same place as the old version then
+     it is also a good idea to move the old installation out of the
+     way, in case you still need it later on. Use a command like this:
+<screen>
+<userinput>mv /usr/local/pgsql /usr/local/pgsql.old</>
+</screen>
+    </para>
+   </step>
+  </procedure>
+
+  <para>
+   After you have installed <productname>PostgreSQL</> &version;, create a new database
+   directory and start the new server. Remember that you must execute
+   these commands while logged in to the special database user account
+   (which you already have if you are upgrading).
+<programlisting>
+<userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/bin</>
+<userinput>/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/bin</>
+</programlisting>
+   Finally, restore your data with
+<screen>
+<userinput>/usr/local/pgsql/bin/psql -d template1 -f <replaceable>outputfile</></userinput>
+</screen>
+   using the <emphasis>new</> <application>psql</>.
+  </para>
 
   <para>
-   <productname>Postgres</productname>, 
-   developed originally in the UC Berkeley Computer Science Department,
-   pioneered many of the object-relational concepts
-   now becoming available in some commercial databases.
-   It provides SQL92/SQL3 language support,
-   transaction integrity, and type extensibility.
-   <productname>PostgreSQL</productname> is an open-source descendant
-   of this original Berkeley code.
+   You can also install the new version in parallel with the old one
+   to decrease the downtime. These topic are discussed at length in
+   <![%flattext-install-include[the <citetitle>Administrator's Guide</>,]]>
+   <![%flattext-install-ignore[<xref linkend="migration">,]]>
+   which you are encouraged
+   to read in any case. The <application>pg_upgrade</> utility can
+   also often be used.
   </para>
- </preface>
+ </sect1>
+
+
+ <sect1>
+  <title>Installation Procedure</title>
+
+  <procedure>
+
+  <step id="configure">
+   <title>Configuration</>
+   <para>
+    The first step of the installation procedure to configure the
+    source tree for your system and choose the options you would like.
+    This is done by running the <filename>configure</> script. For a
+    default installation, simply type
+<screen>
+<userinput>./configure</userinput>
+</screen>
+    This script will run a number of tests to guess values for various
+    system dependent variables and detect some quirks of your
+    operating system, and finally creates several files in the build
+    tree to record what it found.
+   </para>
+
+   <para>
+    The default configuration will build the server and utilities, as
+    well as all client applications and interfaces that only require a
+    C compiler. All files will be installed under
+    <filename>/usr/local/pgsql</> by default.
+   </para>
+
+   <para>
+    You can customize the build and installation process by giving one
+    or more of the following command line options to
+    <filename>configure</filename>:
+
+     <variablelist>
+      <varlistentry>
+       <term>--prefix=<replaceable>PREFIX</></term>
+       <listitem>
+        <para>
+         Install all files under the directory <replaceable>PREFIX</>
+         instead of <filename>/usr/local/pgsql</filename>. The actual
+         files will be installed into various subdirectories; no files
+         will ever be installed directly into the
+         <replaceable>PREFIX</> directory.
+        </para>
+
+        <para>
+         If you have special needs, you can also customize the
+         individual subdirectories with the following options.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--exec-prefix=<replaceable>EXEC-PREFIX</></term>
+       <listitem>
+        <para>
+         You can install architecture-dependent files under a
+         different prefix, <replaceable>EXEC-PREFIX</>, than what
+         <replaceable>PREFIX</> was set to. This can be useful to
+         share architecture-independent files between hosts. If you
+         omit this, then <replaceable>EXEC-PREFIX</> is set equal to
+         <replaceable>PREFIX</> and both architecture dependent and
+         independent files will be installed under the same tree,
+         which is probably what you want.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--bindir=<replaceable>DIRECTORY</></term>
+       <listitem>
+        <para>
+         Specifies the directory for executable programs. The default
+         is <filename><replaceable>EXEC-PREFIX</>/bin</>, which
+         normally means <filename>/usr/local/pgsql/bin</>.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--datadir=<replaceable>DIRECTORY</></term>
+       <listitem>
+        <para>
+         Sets the directory for read-only data files used by the
+         installed programs. The default is
+         <filename><replaceable>PREFIX</>/share</>. Note that this has
+         nothing to do with where your database files will be placed.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--sysconfdir=<replaceable>DIRECTORY</></term>
+       <listitem>
+        <para>
+         The directory for various configuration files,
+         <filename><replaceable>PREFIX</>/etc</> by default.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--libdir=<replaceable>DIRECTORY</></term>
+       <listitem>
+        <para>
+         The location to install libraries and dynamically loadable
+         modules. The default is
+         <filename><replaceable>EXEC-PREFIX</>/lib</>.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--includedir=<replaceable>DIRECTORY</></term>
+       <listitem>
+        <para>
+         The directory for installing C and C++ header files. The
+         default is <filename><replaceable>PREFIX</>/include</>.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--docdir=<replaceable>DIRECTORY</></term>
+       <listitem>
+        <para>
+         Documentation files, except <quote>man</> pages, will be
+         installed into this directory. The default is
+         <filename><replaceable>PREFIX</>/doc</>.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--mandir=<replaceable>DIRECTORY</></term>
+       <listitem>
+        <para>
+         The man pages that come with <productname>PostgreSQL</> will be installed under
+         this directory, in their respective
+         <filename>man<replaceable>x</></> subdirectories.
+         <filename><replaceable>PREFIX</>/man</>.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--with-includes=<replaceable>DIRECTORIES</></term>
+       <listitem>
+        <para>
+         <replaceable>DIRECTORIES</> is a colon-separated list of
+         directories that will be added to the list the compiler
+         searches for header files. If you have optional packages
+         (such as GNU Readline) installed in a non-standard location
+         you have to use this option and probably the corresponding
+         <option>--with-libraries</> option.
+        </para>
+        <para>
+         Example: <literal>--with-includes=/opt/gnu/include:/usr/sup/include</>.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--with-libraries=<replaceable>DIRECTORIES</></term>
+       <listitem>
+        <para>
+         <replaceable>DIRECTORIES</> is a colon-separated list of
+         directories to search for libraries. You will probably have
+         to use this option (and the corresponding
+         <option>--with-includes</> option) if you have packages
+         installed in non-standard locations.
+        </para>
+        <para>
+         Example: <literal>--with-libraries=/opt/gnu/lib:/usr/sup/lib</>.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--enable-locale</term>
+       <listitem>
+        <para>
+         Enables locale support. There is a performance penalty
+         associated with locale support, but if you are not in an
+         English-speaking environment you will most likely need this.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--enable-recode</term>
+       <listitem>
+        <para>
+         Enables character set recode support. See
+         <filename>doc/README.Charsets</> for details on this feature.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--enable-multibyte</term>
+       <listitem>
+        <para>
+         Allows the use of multibyte character encodings. This is
+         primarily for languages like Japanese, Korean, and Chinese.
+         Read <filename>doc/README.mb</> for details.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--with-pgport=<replaceable>NUMBER</></term>
+       <listitem>
+        <para>
+         Set <replaceable>NUMBER</> as the default port number for
+         server and clients. The default is 5432. The port can always
+         be changed later on, but if you specify it here then both
+         server and clients will have the same default compiled in,
+         which can be very convenient.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--with-CXX</term>
+       <listitem>
+        <para>
+         Build the C++ interface library. <filename>configure</> will
+         automatically pick the C++ compiler that goes with the C
+         compiler you are using. It is not recommended or supported to
+         use C and C++ compilers of different origin in the same
+         build.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--with-perl</term>
+       <listitem>
+        <para>
+         Build the Perl interface module. The Perl interface
+         will be installed at the usual place for Perl modules
+         (typically under <filename>/usr/lib/perl</filename>), so you
+         must have root access to perform the installation step (see
+         <xref linkend="install">). You need to have Perl 5 installed to
+         use this option.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--with-python</term>
+       <listitem>
+        <para>
+         Build the Python interface module. You need to have root
+         access to be able to install the Python module at its default
+         place
+         (<filename>/usr/lib/python<replaceable>x</>.<replaceable>y</></>).
+         To be able to use this option, you must have Python installed
+         and your system needs to support shared libraries. If you
+         instead want to build a new complete interpreter binary, you
+         will have to do it manually.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--with-tcl</term>
+       <listitem>
+        <para>
+         Builds components that require Tcl, which are libpgtcl,
+         pgtclsh, and PL/Tcl.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--with-x</term>
+       <listitem>
+        <para>
+         Use the X Window System. If you specified --with-tcl then this
+         will enable the build of modules requiring Tcl/Tk, that is,
+         pgtksh and pgaccess.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--with-tclconfig=<replaceable>DIRECTORY</replaceable></term>
+       <term>--with-tkconfig=<replaceable>DIRECTORY</replaceable></term>
+       <listitem>
+        <para>
+         Tcl/Tk installs the files <filename>tclConfig.sh</filename> and
+         <filename>tkConfig.sh</filename> which contain certain
+         configuration information that is needed to build modules
+         interfacing to Tcl or Tk. These files are normally found
+         automatically at their well-known location, but if you want to
+         use a different version of Tcl or Tk you can specify the
+         directory where to find them.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--enable-odbc</term>
+       <listitem>
+        <para>
+         Build the ODBC driver package.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--with-odbcinst=<replaceable>DIRECTORY</></term>
+       <listitem>
+        <para>
+         Specifies the directory where the ODBC driver will expect its
+         <filename>odbcinst.ini</> configuration file. The default is
+         <filename>/usr/local/pgsql/etc</filename> or whatever you
+         specified as <option>--sysconfdir</option>. A default file
+         will be installed there.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--with-krb4=<replaceable>DIRECTORY</></term>
+       <term>--with-krb5=<replaceable>DIRECTORY</></term>
+       <listitem>
+        <para>
+         Build with suppport for Kerberos authentication. You can use
+         either Kerberos version 4 or 5, but not both. The
+         <replaceable>DIRECTORY</> argument specifies the root
+         directory of the Kerberos installation;
+         <filename>/usr/athena</> is assumed as default. If the
+         relevant headers files and libraries are not under a common
+         parent directory, then you must use the
+         <option>--with-includes</> and <option>--with-libraries</>
+         options in addition to this option. If, on the other hand,
+         the required files are in a location that is searched by
+         default (e.g., <filename>/usr/lib</>), then you can leave off
+         the argument.
+        </para>
+
+        <para>
+         <filename>configure</> will check for the required header
+         files and libraries to make sure that your Kerberos
+         installation is sufficient before proceeding.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--with-krb-srvnam=<replaceable>NAME</></term>
+       <listitem>
+        <para>
+         The name of the Kerberos service principal.
+         <quote>postgres</quote> is the default. There's probably no
+         reason to change this.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--with-krb-srvtab=<replaceable>FILE</></term>
+       <listitem>
+        <para>
+         Specifies the location of the Kerberos server shared key file
+         (<quote>srvtab</>). If you are using Kerberos 4, this
+         defaults to <filename>/etc/srvtab</>, with Kerberos 5 to
+         <filename>FILE:/usr/local/pgsql/etc/krb5.keytab</>, or
+         equivalent, depending on what you set <option>--sysconfdir</>
+         to above.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--enable-syslog</term>
+       <listitem>
+        <para>
+         Enables the <productname>PostgreSQL</> server to use the
+         syslog logging facility. (Using this option does not mean
+         that you have to log with syslog or even that it will be done
+         by default, it simply makes it possible to turn this option
+         on at run time.)
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>--enable-debug</term>
+       <listitem>
+        <para>
+         Compiles all programs and libraries with debugging symbols.
+         This means that you can run the programs through a debugger
+         to analyze problems. This option is not recommended for
+         production use.
+        </para>
+       </listitem>
+      </varlistentry>
+     </variablelist>
+   </para>
+
+   <formalpara>
+    <title>Environment variables</>
+    <para>
+     You can set the <envar>CC</> environment variable to choose the C
+     compiler to use. If you don't then <filename>configure</> will
+     look for one. For example:
+<screen>
+<userinput>CC=/opt/bin/gcc ./configure</>
+</screen>
+    </para>
+   </formalpara>
+    
+  </step>
+
+  <step>
+   <title>Build</title>
+
+   <para>
+    To start the build, type
+<screen>
+<userinput>gmake</userinput>
+</screen>
+    (Remember to use <acronym>GNU</> <application>make</>.) The build
+    can take anywhere from 5 minutes to half an hour. The last line
+    displayed should be
+<screen>
+All of PostgreSQL is successfully made. Ready to install.
+</screen>
+   </para>
+  </step>
+
+  <step>
+   <title>Regression Tests</title>
+
+   <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</> runs on your machine
+    in the way the developers expected it to. Type
+<screen>
+<userinput>gmake -C src/test/regress all runcheck</userinput>
+<!-- XXX How about just `gmake check'? -->
+</screen>
+    It is possible that some tests fail, due to differences in error
+    message wording or floating point results. The file
+    <filename>src/test/regress/README</> and
+    <![%flattext-install-include[the <citetitle>Administrator's Guide</citetitle>]]>
+    <![%flattext-install-ignore[<xref linkend="regress">]]>
+    contain detailed
+    information about interpreting the test results. You can repeat
+    this test at any later time by issuing the same command.
+   </para>
+  </step>
+
+  <step id="install">
+   <title>Installing The Files</title>
+
+   <note>
+    <para>
+     If you are upgrading an existing system and are going to install
+     the new files over the old ones then you should have backed up
+     your data and shut down the old server by now, as explained in
+     <xref linkend="install-upgrading"> above.
+    </para>
+   </note>
+
+   <para>
+    To install <productname>PostgreSQL</> enter
+<screen>
+<userinput>gmake install</userinput>
+</screen>
+    This will install files into the directories that were specified
+    in <xref linkend="configure">. Make sure that you have appropriate
+    permissions to write into that area. Normally you need to do this
+    step as root. Alternatively, you could create the target
+    directories in advance and arrange for appropriate permissions to
+    be granted.
+   </para>
+
+   <para>
+    If you built the Perl or Python interfaces and you were not the
+    root user when you executed the above command then that part of
+    the installation probably failed. In that case you should become
+    the root user and then do
+<screen>
+<userinput>gmake -C src/interfaces/perl5 install</userinput>
+<userinput>gmake -C src/interfaces/python install</userinput>
+</screen>
+    Due to a quirk in the Perl build environment the first command
+    will actually rebuild the complete interface and then install it.
+    This is not harmful, just unusual. If you do not have superuser
+    access you are on your own: you can still take the required files
+    and place them in other directories where Perl or Python can find
+    them, but how to do that is left as an exercise.
+   </para>
+
+   <formalpara>
+    <title>Client-only installation</title>
+    <para>
+     If you want to install only the client applications and
+     interfaces, then you can use these commands:
+<screen>
+<userinput>gmake -C src/bin install</>
+<userinput>gmake -C src/interfaces install</>
+<userinput>gmake -C doc install</>
+</screen>
+    </para>
+   </formalpara>
+
+   <para>
+    To undo the installation use the command <command>gmake
+    uninstall</>. However, this will not remove the Perl and Python
+    interfaces and it will not remove any directories.
+   </para>
+  </step>
+  </procedure>
+
+  <formalpara>
+   <title>Cleanup</>
+   <para>
+    After the installation you can make room by removing the built
+    files from the source tree with the <command>gmake clean</>
+    command. This will preserve the choices made by the configure
+    program, so that you can rebuild everything with <command>gmake</>
+    later on. To reset the source tree to the state in which it was
+    distributed, use <command>gmake distclean</>. If you are going to
+    build for several platforms from the same source tree you must do
+    this and re-configure for each build.
+   </para>
+  </formalpara>  
+
+ </sect1>
+
+ <sect1>
+  <title>Post-Installation Setup</title>
+
+  <sect2>
+   <title>Shared Libraries</title>
+   <para>
+    On most systems that have shared libraries (which most systems do)
+    you need to tell your system how to find the newly installed
+    shared libraries. How to do this varies between platforms, but the
+    most widely usable method is to set the environment variable
+    <envar>LD_LIBRARY_PATH</> like so: In Bourne shells (sh, ksh,
+    bash, zsh)
+<programlisting>
+LD_LIBRARY_PATH=/usr/local/pgsql/lib
+export LD_LIBRARY_PATH
+</programlisting>
+    or in csh or tcsh
+<programlisting>
+setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
+</programlisting>
+    Replace <literal>/usr/local/pgsql/lib</> with whatever you set
+    <option><literal>--libdir</></> to in <xref linkend="configure">.
+    You should put these commands into a shell startup file such as
+    <filename>/etc/profile</> or <filename>~/.bash_profile</>.
+   </para>
+
+   <para>
+    On Linux systems the following is the preferred method, but you
+    must have root access. Edit the file <filename>/etc/ld.so.conf</>
+    to add a line
+<programlisting>
+<filename>/usr/local/pgsql/lib</>
+</programlisting>
+    Then run command <command>/sbin/ldconfig</>.
+   </para>
+
+   <para>
+    If in doubt, refer to the manual pages of your system. If you later
+    on get a message like
+<screen>
+psql: error in loading shared libraries
+libpq.so.2.1: cannot open shared object file: No such file or directory
+</screen>
+    then this step was necessary.  Simply take care of it then.
+   </para>
+  </sect2>
+
+  <sect2>
+   <title>Environment Variables</title>
+   <para>
+    If you installed into <filename>/usr/local/pgsql</> or some other
+    location that is not searched for programs by default, you need to
+    add <filename>/usr/local/pgsql/bin</> (or what you set
+    <option><literal>--bindir</></> to in <xref linkend="configure">)
+    into your <envar>PATH</>. To do this, add the following to your
+    shell startup file, such as <filename>~/.bash_profile</> (or
+    <filename>/etc/profile</>, if you want it to affect every user):
+<programlisting>
+PATH=$PATH:/usr/local/pgsql/bin
+</programlisting>
+    If you are using csh or tcsh, then use this command:
+<programlisting>
+set path = ( /usr/local/pgsql/bin path )
+</programlisting>
+   </para>
+
+   <para>
+    To enable your system to find the <application>man</>
+    documentation, you need to add a line like the following to a
+    shell startup file:
+<programlisting>
+MANPATH=$MANPATH:/usr/local/pgsql/man
+</programlisting>
+   </para>
+
+   <para>
+    The environment variables <envar>PGHOST</> and <envar>PGPORT</>
+    specify to client applications the host and port of the database
+    server, overriding the compiled-in defaults. If you are going to
+    run client applications remotely then it is convenient if every
+    user that plans to use the database sets <envar>PGHOST</>, but it
+    is not required and the settings can be communicated via command
+    line options to most client programs.
+   </para>
+  </sect2>
+ </sect1>
 
- <chapter>
-  <title>Introduction</title>
+
+<![%flattext-install-include;[
+ <sect1>
+  <title>Getting Started</title>
 
   <para>
-   This installation procedure makes some assumptions about the desired configuration
-   and runtime environment for your system. This may be adequate for many installations,
-   and is almost certainly adequate for a first installation. But you may want to
-   do an initial installation up to the point of unpacking the source tree
-   and installing documentation, and then print or browse the 
-   <citetitle>Administrator's Guide</citetitle>.
+   The following is a quick summary of how to get <productname>PostgreSQL</> up and
+   running once installed. The <citetitle>Administrator's Guide</>
+   contains more information.
   </para>
 
- </chapter>
+  <procedure>
+   <step>
+    <para>
+     Create the <productname>PostgreSQL</> server account. This is the user the server
+     will run as. For production use you should create a separate,
+     unprivileged account (<quote>postgres</> is commonly used). If
+     you do not have root access or just want to play around, your own
+     user account is enough, but running the server as root is a
+     security risk and therefore not allowed.
+<screen>
+<userinput>adduser postgres</>
+</screen>
+    </para>
+   </step>
+
+   <step>
+    <para>
+     Create a database installation with the <command>initdb</>
+     command. To run <command>initdb</> you must be logged in to your
+     <productname>PostgreSQL</> server account. It will not work as
+     root.
+<screen>
+root# <userinput>mkdir /usr/local/pgsql/data</>
+root# <userinput>chown postgres /usr/local/pgsql/data</>
+root# <userinput>su - postgres</>
+postgres$ <userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
+</screen>
+    </para>
+
+    <para>
+     The <option>-D</> 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
+     server account can write to the directory (or create it, if it
+     doesn't already exist) before starting <command>initdb</>, as
+     illustrated here.
+    </para>
+   </step>
+
+   <step>
+    <para>
+     The previous step should have told you how to start up the
+     database server. 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 put the server
+     in the background use something like
+<programlisting>
+nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
+    &lt;/dev/null &gt;&gt;server.log 2&gt;&amp;1 &lt;/dev/null &amp;
+</programlisting>
+    </para>
+
+    <para>
+     To stop a server running in the background you can type
+<programlisting>
+kill `cat /usr/local/psgql/data/postmaster.pid`
+</programlisting>
+    </para>
+
+    <para>
+     In order to allow TCP/IP connections (rather than only Unix
+     domain socket ones) you need to pass the <option>-i</> option to
+     <filename>postmaster</>.
+    </para>
+   </step>
+
+   <step>
+    <para>
+     Create a database:
+<screen>
+<userinput>createdb testdb</>
+</screen>
+     Then enter
+<screen>
+<userinput>psql testdb</>
+</screen>
+     to connect to that database. At the prompt you can enter SQL
+     commands and start experimenting.
+    </para>
+   </step>
+  </procedure>
+ </sect1>
+
+ <sect1>
+  <title>What Now?</title>
+
+  <para>
+   <itemizedlist>
+    <listitem>
+     <para>
+      The <citetitle>Tutorial</> should be your first reading if you
+      are completely new to <acronym>SQL</> databases. It should have
+      been installed at
+      <filename>/usr/local/pgsql/doc/tutorial/index.html</> unless you
+      changed the installation directories.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      If you are familiar with database concepts then you want to
+      proceed with the <citetitle>Administrator's Guide</citetitle>,
+      which contains information about how to set up the database
+      server, database users, and authentication. It can be found at
+      <filename>/usr/local/pgsql/doc/admin/index.html</>.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      Usually, you will want to modify your computer so that it will
+      automatically start the database server whenever it boots. Some
+      suggestions for this are in the <citetitle>Administrator's
+      Guide</citetitle>.
+     </para>
+    </listitem>
 
- &ports;
- &install;
- &config;
- &release;
- &regress;
+    <listitem>
+     <para>
+      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. This is also
+      explained in the <citetitle>Administrator's Guide</citetitle>.
+     </para>
+    </listitem>
 
+   </itemizedlist>
+  </para>
+
+<!-- do we still ship this? -->
 <!--
-<INDEX> </INDEX>
+  <para>
+   The documentation is also available in Postscript format. If you
+   have a Postscript printer, or have your machine already set up to
+   accept Postscript files using a print filter, then to print, for
+   example the <citetitle>User's Guide</> simply type
+<programlisting>
+cd /usr/local/pgsql/doc
+gunzip -c user.ps.gz | lpr
+</programlisting>
+   Here is how you might do it if you have <productname>Ghostscript</>
+   installed on your system and are writing to a Laserjet printer.
+<programlisting>
+gunzip -c user.ps.gz \
+    | gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- \
+    | lpr
+</programlisting>
+   Printer setups can vary wildly from system to system. If in doubt,
+   consult your manuals or your local expert.
+  </para>
 -->
 
-</book>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode:sgml
-sgml-omittag:nil
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"./reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:("/usr/lib/sgml/catalog")
-sgml-local-ecat-files:nil
-End:
--->
+ </sect1>
+]]>
+
+
+ <sect1 id="supported-platforms">
+  <title>Supported Platforms</title>
+
+  <para>
+   At the time of release, <productname>PostgreSQL</> &version; has been verified by the
+   developer community to work on the following platforms. A supported
+   platform generally means that <productname>PostgreSQL</> builds and installs according
+   to these instructions and that the regression tests pass, except
+   for minor differences.
+  </para>
+
+  <note>
+   <para>
+    If you are having problems with the installation on a supported
+    platform, please write to <email>pgsql-bugs@postgresql.org</email>
+    or <email>pgsql-ports@postgresql.org</email>, not to the people
+    listed here.
+   </para>
+  </note>
+
+    <informaltable>
+     <tgroup cols="4">
+      <thead>
+       <row>
+	<entry><acronym>OS</acronym></entry>
+	<entry>Processor</entry>
+	<entry>Version</entry>
+	<entry>Reported</entry>
+	<entry>Remarks</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+	<entry>AIX 4.3.2</entry>
+	<entry>RS6000</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-05, Andread Zeugswetter (<email>Andreas.Zeugswetter@telecom.at</>)</entry>
+        <entry>See also <filename>doc/FAQ_AIX</></entry>
+       </row>
+       <row>
+	<entry>BSDI 4.01</entry>
+	<entry>x86</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-04, Bruce Momjian (<email>pgman@candle.pha.pa.us</>)</entry>
+        <entry></entry>
+       </row>
+       <row>
+	<entry>Compaq Tru64 5.0</entry>
+	<entry>Alpha</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-11, Andrew McMurry (<email>andrew.mcmurry@astro.uio.no</>)</entry>
+        <entry></>
+       </row>
+       <row>
+	<entry>FreeBSD 4.0</entry>
+	<entry>x86</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-04, Marc Fournier (<email>scrappy@hub.org</>)</entry>
+        <entry></>
+       </row>
+       <row>
+	<entry>HPUX 9.0x and 10.20</entry>
+	<entry>PA-RISC</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-12, Tom Lane (<email>tgl@sss.pgh.pa.us</>)</entry>
+        <entry></>
+       </row>
+       <row>
+	<entry>IRIX 6.5.6f</entry>
+	<entry>MIPS</entry>
+	<entry>6.5.3</entry>
+	<entry>2000-02-18, Kevin Wheatley (<email>hxpro@cinesite.co.uk</>)</entry>
+	<entry>MIPSPro 7.3.1.1m N32 build</entry>
+       </row>
+       <row>
+	<entry>Linux 2.0.x</entry>
+	<entry>Alpha</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-05, Ryan Kirkpatrick (<email>pgsql@rkirkpat.net</>)</entry>
+	<entry>with published patches</entry>
+       </row>
+       <row>
+	<entry>Linux 2.2.x</entry>
+	<entry>armv4l</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-17, Mark Knox (<email>segfault@hardline.org</>)</entry>
+	<entry>Regression test needs work.</entry>
+       </row>
+       <row>
+	<entry>Linux 2.2.x</entry>
+	<entry>x86</entry>
+	<entry>7.0</entry>
+	<entry>2000-03-26, Lamar Owen (<email>lamar.owen@wgcr.org</>)</entry>
+	<entry></>
+       </row>
+       <row>
+	<entry>Linux 2.0.x</entry>
+	<entry>MIPS</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-13, Tatsuo Ishii (<email>t-ishii@sra.co.jp</>)</entry>
+	<entry>Cobalt Qube</entry>
+       </row>
+       <row>
+	<entry>Linux 2.2.5</entry>
+	<entry>Sparc</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-02, Tom Szybist (<email>szybist@boxhill.com</>)</entry>
+	<entry></>
+       </row>
+       <row>
+	<entry>LinuxPPC R4</entry>
+	<entry>PPC603e</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-13, Tatsuo Ishii (<email>t-ishii@sra.co.jp</>)</entry>
+	<entry></>
+       </row>
+       <row>
+	<entry>mklinux</entry>
+	<entry>PPC750</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-13, Tatsuo Ishii (<email>t-ishii@sra.co.jp</>)</entry>
+	<entry></>
+       </row>
+       <row>
+	<entry>NetBSD 1.4</entry>
+	<entry>arm32</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-08, Patrick Welche (<email>prlw1@newn.cam.ac.uk</>)</entry>
+	<entry></>
+       </row>
+       <row>
+	<entry>NetBSD 1.4U</entry>
+	<entry>x86</entry>
+	<entry>7.0</entry>
+	<entry>2000-03-26, Patrick Welche (<email>prlw1@newn.cam.ac.uk</>)</entry>
+	<entry></>
+       </row>
+       <row>
+	<entry>NetBSD</entry>
+	<entry>m68k</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-10, Henry B. Hotz (<email>hotz@jpl.nasa.gov</>)</entry>
+	<entry>Mac 8xx</entry>
+       </row>
+       <row>
+	<entry>NetBSD</entry>
+	<entry>Sparc</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-13, Tom I. Helbekkmo (<email>tih@kpnQwest.no</>)</entry>
+	<entry></>
+       </row>
+       <row>
+	<entry>QNX 4.25</entry>
+	<entry>x86</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-01, Dr. Andreas Kardos (<email>kardos@repas-aeg.de</>)</entry>
+	<entry></>
+       </row>
+       <row>
+	<entry>SCO OpenServer 5</entry>
+	<entry>x86</entry>
+	<entry>6.5</entry>
+	<entry>1999-05-25, Andrew Merrill (<email>andrew@compclass.com</>)</entry>
+	<entry></>
+       </row>
+       <row>
+	<entry>SCO UnixWare 7</entry>
+	<entry>x86</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-18, Billy G. Allie (<email>Bill.Allie@mug.org</>)</entry>
+	<entry>See also <filename>doc/FAQ_SCO</></entry>
+       </row>
+       <row>
+	<entry>Solaris</entry>
+	<entry>x86</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-12, Marc Fournier (<email>scrappy@hub.org</>)</entry>
+	<entry></>
+       </row>
+       <row>
+	<entry>Solaris 2.5.1-2.7</entry>
+	<entry>Sparc</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-12, Peter Eisentraut (<email>peter_e@gmx.net</email>),
+                           Marc Fournier (<email>scrappy@hub.org</>)</entry>
+	<entry></>
+       </row>
+       <row>
+	<entry>SunOS 4.1.4</entry>
+	<entry>Sparc</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-13, Tatsuo Ishii (<email>t-ishii@sra.co.jp</>)</entry>
+	<entry></>
+       </row>
+       <row>
+	<entry>Windows/Win32</entry>
+	<entry>x86</entry>
+	<entry>7.0</entry>
+	<entry>2000-04-02, Magnus Hagander (<email>mha@sollentuna.net</>)</entry>
+	<entry>Client-side libraries or ODBC/JDBC, no server-side</entry>
+       </row>
+       <row>
+	<entry>WinNT/Cygwin</entry>
+	<entry>x86</entry>
+	<entry>7.0</entry>
+	<entry>2000-03-30, Daniel Horak (<email>horak@sit.plzen-city.cz</>)</entry>
+        <entry>with RedHat/Cygnus <productname>Cygwin</> toolset</entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </informaltable>
+
+  <formalpara>
+   <title>Unsupported Platforms</title>
+   <para>
+    The following platforms have not been verified to work. Platforms
+    listed for version 6.3.x and later should also work with
+    &version;, but we did not receive explicit confirmation of such at
+    the time this list was compiled. We include these here to let you
+    know that these platforms <emphasis>could</> be supported if given
+    some attention.
+   </para>
+  </formalpara>
+
+  <informaltable>
+   <tgroup cols="4">
+    <thead>
+     <row>
+      <entry><acronym>OS</acronym></entry>
+      <entry>Processor</entry>
+      <entry>Version</entry>
+      <entry>Reported</entry>
+      <entry>Remarks</entry>
+     </row>
+    </thead>
+
+    <tbody>
+     <row>
+      <entry>BeOS</entry>
+      <entry>x86</entry>
+      <entry>7.0</entry>
+      <entry>2000-05-01, Adam Haberlach (<email>adam@newsnipple.com</>)</entry>
+      <entry>Client-side coming soon?</entry>
+     </row>
+
+     <row>
+      <entry>DGUX 5.4R4.11</entry>
+      <entry>m88k</entry>
+      <entry>6.3</entry>
+      <entry>1998-03-01, Brian E Gallew (<email>geek+@cmu.edu</>)</entry>
+      <entry>6.4 probably OK. Needs new maintainer.</entry>
+     </row>
+
+     <row>
+      <entry>NetBSD 1.3</entry>
+      <entry>VAX</entry>
+      <entry>6.3</entry>
+      <entry>1998-03-01, Tom I Helbekkmo (<email>tih@kpnQwest.no</>)</entry>
+      <entry>7.0 should work.</entry>
+     </row>
+
+     <row>
+      <entry>System V R4 4.4</entry>
+      <entry>m88k</entry>
+      <entry>6.2.1</entry>
+      <entry>1998-03-01, Doug Winterburn (<email>dlw@seavme.xroads.com</>)</entry>
+      <entry>Needs new TAS spinlock code</entry>
+     </row>
+
+     <row>
+      <entry>System V R4</entry>
+      <entry>MIPS</entry>
+      <entry>6.4</entry>
+      <entry>1998-10-28, Frank Ridderbusch (<email>ridderbusch.pad@sni.de</>)</entry>
+      <entry>No 64-bit integer</entry>
+     </row>
+
+     <row>
+      <entry>Ultrix</entry>
+      <entry>MIPS, VAX</entry>
+      <entry>6.x</entry>
+      <entry>1998-03-01</entry>
+      <entry>No recent reports. Obsolete?</entry>
+     </row>
+
+     <row>
+      <entry>MacOS</entry>
+      <entry>all</entry>
+      <entry>6.x</entry>
+      <entry>1998-03-01</entry>
+      <entry>Not library compatible; use ODBC/JDBC.</entry>
+     </row>
+
+     <row>
+      <entry>NextStep</entry>
+      <entry>x86</entry>
+      <entry>6.x</entry>
+      <entry>1998-03-01, David Wetzel (<email>dave@turbocat.de</email>)</entry>
+      <entry>Client-only support</entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </informaltable>
+
+ </sect1>
+
+</chapter>
diff --git a/doc/src/sgml/layout.sgml b/doc/src/sgml/layout.sgml
deleted file mode 100644
index 46e265f443a..00000000000
--- a/doc/src/sgml/layout.sgml
+++ /dev/null
@@ -1,82 +0,0 @@
-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/layout.sgml,v 2.3 2000/03/31 03:27:40 thomas Exp $
--->
-
-<chapter id="layout">
-<Title>System Layout</Title>
-
-<Para>
-<Figure Id="ADMIN-LAYOUT">
-<Title><ProductName>Postgres</ProductName> file layout</Title>
-<Graphic Align="center" FileRef="layout.gif" Format="GIF"></Graphic>
-</Figure>
-
-<XRef LinkEnd="ADMIN-LAYOUT" EndTerm="ADMIN-LAYOUT">
-shows how the <ProductName>Postgres</ProductName>  distribution  is  laid
-     out  when installed in the default way. For simplicity,
-     we will assume that <ProductName>Postgres</ProductName>
- has been installed in  the
-     directory  <filename>/usr/local/pgsql</filename>.   Therefore, wherever
-     you see the directory <filename>/usr/local/pgsql</filename> you  should
-     substitute  the name of the directory where
- <ProductName>Postgres</ProductName> is
-     actually installed.
-     All <ProductName>Postgres</ProductName> commands are installed
-     in  the  directory
-     <filename>/usr/local/pgsql/bin</filename>.   Therefore,  you should add
-     this directory to your shell command path.  If you  use
-     a variant of the Berkeley C shell, such as csh or tcsh,
-     you would add
-<ProgramListing>
-set path = ( /usr/local/pgsql/bin path )
-</ProgramListing>
-     in the .login file in your home directory.  If you  use
-     a  variant  of  the  Bourne  shell, such as sh, ksh, or
-     bash, then you would add
-<ProgramListing>
-PATH=/usr/local/pgsql/bin:$PATH
-export PATH
-</ProgramListing>
-     to the .profile file in your home directory.
-     From now on, we will assume that  you  have  added  the
-     <ProductName>Postgres</ProductName>  bin  directory to your path.
-     In addition, we
-     will make frequent reference to "setting a shell  
-     variable"  or  "setting an environment variable" throughout
-     this document.  If you did  not  fully  understand  the
-     last  paragraph  on  modifying  your  search  path, you
-     should consult the Unix manual pages that describe your
-     shell before going any further.
-</Para>
-
-<Para>
-If you have not set things up in the
-default  way,  you may have some more work to do.  
-For example, if the database server machine is a remote machine, you
-will need to set the <envar>PGHOST</envar> environment variable to the name
-of the database server machine.   The  environment  variable
-<envar>PGPORT</envar> may also have to be set.  The bottom line is this: if
-you try to start an application  program  and  it  complains
-that it cannot connect to the <Application>postmaster</Application>,
-you must go back and make sure that your
-environment is properly set up.
-</Para>
-
-</Chapter>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode:sgml
-sgml-omittag:nil
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"./reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:("/usr/lib/sgml/catalog")
-sgml-local-ecat-files:nil
-End:
--->
diff --git a/doc/src/sgml/ports.sgml b/doc/src/sgml/ports.sgml
deleted file mode 100644
index 8965391eb5c..00000000000
--- a/doc/src/sgml/ports.sgml
+++ /dev/null
@@ -1,381 +0,0 @@
- <chapter id="ports">
-  <title>Ports</title>
-
-  <para>
-   This manual  describes version 7.0 of <productname>Postgres</productname>.
-   The <productname>Postgres</productname> developer community has
-   compiled  and  tested <productname>Postgres</productname> on a
-   number of platforms. Check
-   <ulink url="http://www.postgresql.org/docs/admin/ports.htm">the web site</ulink>
-   for the latest information.
-  </para>
-
-  <sect1>
-   <title>Currently Supported Platforms</title>
-
-   <para>
-    At the time of publication, the following platforms have been tested:
-
-    <table tocentry="1">
-     <title>Supported Platforms</title>
-     <tgroup cols="4">
-      <thead>
-       <row>
-	<entry><acronym>OS</acronym></entry>
-	<entry>Processor</entry>
-	<entry>Version</entry>
-	<entry>Reported</entry>
-	<entry>Remarks</entry>
-       </row>
-      </thead>
-      <tbody>
-       <row>
-	<entry>AIX 4.3.2</entry>
-	<entry>RS6000</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-05</entry>
-	<entry><ulink url="mailto:Andreas.Zeugswetter@telecom.at">Andreas Zeugswetter</ulink></entry>
-       </row>
-       <row>
-	<entry>BSDI 4.01</entry>
-	<entry>x86</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-04</entry>
-	<entry><ulink url="mailto:maillist@candle.pha.pa.us">Bruce Momjian</ulink></entry>
-       </row>
-       <row>
-	<entry>Compaq Tru64 5.0</entry>
-	<entry>Alpha</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-11</entry>
-	<entry><ulink url="mailto:andrew.mcmurry@astro.uio.no">Andrew McMurry</ulink></entry>
-       </row>
-       <row>
-	<entry>FreeBSD 4.0</entry>
-	<entry>x86</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-04</entry>
-	<entry><ulink url="mailto:scrappy@hub.org">Marc Fournier</ulink></entry>
-       </row>
-       <row>
-	<entry>HPUX</entry>
-	<entry>PA-RISC</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-12</entry>
-	<entry>Both 9.0x and 10.20.
-	 <ulink url="mailto:tgl@sss.pgh.pa.us">Tom Lane</ulink></entry>
-       </row>
-       <row>
-	<entry>IRIX 6.5.6f</entry>
-	<entry>MIPS</entry>
-	<entry>v6.5.3</entry>
-	<entry>2000-02-18</entry>
-	<entry>MIPSPro 7.3.1.1m N32 build.
-	 <ulink url="mailto:hxpro@cinesite.co.uk">Kevin Wheatley</ulink></entry>
-       </row>
-       <row>
-	<entry>Linux 2.0.x</entry>
-	<entry>Alpha</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-05</entry>
-	<entry>With published patches.
-	 <ulink url="mailto:pgsql@rkirkpat.net">Ryan Kirkpatrick</ulink></entry>
-       </row>
-       <row>
-	<entry>Linux 2.2.x</entry>
-	<entry>armv4l</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-17</entry>
-	<entry>Regression test needs work.
-	 <ulink url="mailto:segfault@hardline.org">Mark Knox</ulink></entry>
-       </row>
-       <row>
-	<entry>Linux 2.2.x</entry>
-	<entry>x86</entry>
-	<entry>v7.0</entry>
-	<entry>2000-03-26</entry>
-	<entry><ulink url="mailto:lamar.owen@wgcr.org">Lamar Owens</ulink></entry>
-       </row>
-       <row>
-	<entry>Linux 2.0.x</entry>
-	<entry>MIPS</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-13</entry>
-	<entry>Cobalt Qube.
-	 <ulink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ulink></entry>
-       </row>
-       <row>
-	<entry>Linux 2.2.5</entry>
-	<entry>Sparc</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-02</entry>
-	<entry><ulink url="mailto:szybist@boxhill.com">Tom Szybist</ulink></entry>
-       </row>
-       <row>
-	<entry>LinuxPPC R4</entry>
-	<entry>PPC603e</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-13</entry>
-	<entry><ulink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ulink></entry>
-       </row>
-       <row>
-	<entry>mklinux</entry>
-	<entry>PPC750</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-13</entry>
-	<entry><ulink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ulink></entry>
-       </row>
-       <row>
-	<entry>NetBSD 1.4</entry>
-	<entry>arm32</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-08</entry>
-	<entry><ulink url="mailto:prlw1@newn.cam.ac.uk">Patrick
-	  Welche</ulink></entry>
-       </row>
-       <row>
-	<entry>NetBSD 1.4U</entry>
-	<entry>x86</entry>
-	<entry>v7.0</entry>
-	<entry>2000-03-26</entry>
-	<entry><ulink url="mailto:prlw1@newn.cam.ac.uk">Patrick
-	  Welche</ulink></entry>
-       </row>
-       <row>
-	<entry>NetBSD</entry>
-	<entry>m68k</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-10</entry>
-	<entry>Mac 8xx.
-	 <ulink url="mailto:hotz@jpl.nasa.gov">Henry B. Hotz</ulink></entry>
-       </row>
-       <row>
-	<entry>NetBSD/sparc</entry>
-	<entry>Sparc</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-13</entry>
-	<entry><ulink url="mailto:tih@kpnQwest.no">Tom I Helbekkmo</ulink></entry>
-       </row>
-       <row>
-	<entry>QNX 4.25</entry>
-	<entry>x86</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-01</entry>
-	<entry><ulink url="mailto:kardos@repas-aeg.de">Dr. Andreas Kardos</ulink></entry>
-       </row>
-       <row>
-	<entry>SCO OpenServer 5</entry>
-	<entry>x86</entry>
-	<entry>v6.5</entry>
-	<entry>1999-05-25</entry>
-	<entry><ulink url="mailto:andrew@compclass.com">Andrew Merrill</ulink></entry>
-       </row>
-       <row>
-	<entry>SCO UnixWare 7</entry>
-	<entry>x86</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-18</entry>
-	<entry>See FAQ.
-	 <ulink url="mailto:Bill.Allie@mug.org">Billy G. Allie</ulink></entry>
-       </row>
-       <row>
-	<entry>Solaris</entry>
-	<entry>x86</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-12</entry>
-	<entry><ulink url="mailto:scrappy@hub.org">Marc Fournier</ulink></entry>
-       </row>
-       <row>
-	<entry>Solaris 2.5.1-2.7</entry>
-	<entry>Sparc</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-12</entry>
-	<entry><ulink url="mailto:peter_e@gmx.net">Peter Eisentraut</ulink>,
-	 <ulink url="mailto:scrappy@hub.org">Marc Fournier</ulink></entry>
-       </row>
-       <row>
-	<entry>SunOS 4.1.4</entry>
-	<entry>Sparc</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-13</entry>
-	<entry><ulink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ulink></entry>
-       </row>
-       <row>
-	<entry>Windows/Win32</entry>
-	<entry>x86</entry>
-	<entry>v7.0</entry>
-	<entry>2000-04-02</entry>
-	<entry>Client-side libraries or ODBC/JDBC. No server-side.
-	 <ulink url="mha@sollentuna.net">Magnus Hagander</ulink></entry>
-       </row>
-       <row>
-	<entry>WinNT/Cygwin</entry>
-	<entry>x86</entry>
-	<entry>v7.0</entry>
-	<entry>2000-03-30</entry>
-	<entry>Uses Cygwin library.
-	 <ulink url="mailto:horak@sit.plzen-city.cz">Daniel Horak</ulink></entry>
-       </row>
-      </tbody>
-     </tgroup>
-    </table>
-   </para>
-
-   <note>
-    <para>
-     For <productname>Windows NT</productname>, 
-     the server-side port of <productname>Postgres</productname> uses
-     the RedHat/Cygnus <productname>Cygwin</productname> library and
-     toolset. For <productname>Windows 9x</productname>, no
-     server-side port is available due to OS limitations.
-    </para>
-   </note>
-  </sect1>
-
-  <sect1>
-   <title>Unsupported Platforms</title>
-
-   <para>
-    Platforms listed for v6.3.x-v6.5.x should also work with v7.0,
-    but we did not receive explicit confirmation of such at the time this
-    list was compiled. We include these here to let you know that
-    these platforms <emphasis>could</emphasis> be supported if given some 
-    attention.
-   </para>
-
-   <para>
-    At the time of publication, the following platforms have not been
-    tested for v7.0 or v6.5.x:
-
-    <table tocentry="1">
-     <title>Unsupported Platforms</title>
-     <tgroup cols="4">
-      <thead>
-       <row>
-	<entry><acronym>OS</acronym></entry>
-	<entry>Processor</entry>
-	<entry>Version</entry>
-	<entry>Reported</entry>
-	<entry>Remarks</entry>
-       </row>
-      </thead>
-      <tbody>
-       <row>
-	<entry>BeOS</entry>
-	<entry>x86</entry>
-	<entry>v7.0</entry>
-	<entry>2000-05-01</entry>
-	<entry>Client-side coming soon?
-	 <ulink url="mailto:adam@newsnipple.com">Adam Haberlach</ulink></entry>
-       </row>
-       <row>
-	<entry>DGUX 5.4R4.11</entry>
-	<entry>m88k</entry>
-	<entry>v6.3</entry>
-	<entry>1998-03-01</entry>
-	<entry>v6.4 probably OK. Needs new maintainer.
-	 <ulink url="mailto:geek+@cmu.edu">Brian E Gallew</ulink></entry>
-       </row>
-       <row>
-	<entry>NetBSD-current</entry>
-	<entry>NS32532</entry>
-	<entry>v6.4</entry>
-	<entry>1998-10-27</entry>
-	<entry>Date math annoyances.
-	 <ulink url="mailto:jonb@metronet.com">Jon Buller</ulink></entry>
-       </row>
-       <row>
-	<entry>NetBSD 1.3</entry>
-	<entry>VAX</entry>
-	<entry>v6.3</entry>
-	<entry>1998-03-01</entry>
-	<entry>v7.0 should work.
-	 <ulink url="mailto:tih@kpnQwest.no">Tom I Helbekkmo</ulink></entry>
-       </row>
-       <row>
-	<entry>SVR4 4.4</entry>
-	<entry>m88k</entry>
-	<entry>v6.2.1</entry>
-	<entry>1998-03-01</entry>
-	<entry>v6.4.x will need TAS spinlock code.
-	 <ulink url="mailto:dlw@seavme.xroads.com">Doug Winterburn</ulink></entry>
-       </row>
-       <row>
-	<entry>SVR4</entry>
-	<entry>MIPS</entry>
-	<entry>v6.4</entry>
-	<entry>1998-10-28</entry>
-	<entry>No 64-bit int.
-	 <ulink url="mailto:ridderbusch.pad@sni.de">Frank Ridderbusch</ulink></entry>
-       </row>
-       <row>
-	<entry>Ultrix</entry>
-	<entry>MIPS, VAX</entry>
-	<entry>v6.x</entry>
-	<entry>1998-03-01</entry>
-	<entry>No recent reports; obsolete?</entry>
-       </row>
-      </tbody>
-     </tgroup>
-    </table>
-   </para>
-
-   <para>
-    There are a few platforms which have been attempted and which have been
-    reported to not work with the standard distribution.
-    Others listed here do not provide sufficient library support for an attempt.
-
-    <table tocentry="1">
-     <title>Incompatible Platforms</title>
-     <titleabbrev>Incompatibles</titleabbrev>
-     <tgroup cols="4">
-      <thead>
-       <row>
-	<entry><acronym>OS</acronym></entry>
-	<entry>Processor</entry>
-	<entry>Version</entry>
-	<entry>Reported</entry>
-	<entry>Remarks</entry>
-       </row>
-      </thead>
-      <tbody>
-       <row>
-	<entry>MacOS</entry>
-	<entry>all</entry>
-	<entry>v6.x</entry>
-	<entry>1998-03-01</entry>
-	<entry>Not library compatible; use ODBC/JDBC</entry>
-       </row>
-       <row>
-	<entry>NextStep</entry>
-	<entry>x86</entry>
-	<entry>v6.x</entry>
-	<entry>1998-03-01</entry>
-	<entry>Client-only support; v1.0.9 worked with patches
-	 <ulink url="mailto:dave@turbocat.de">David Wetzel</ulink></entry>
-       </row>
-      </tbody>
-     </tgroup>
-    </table>
-   </para>
-
-  </sect1>
-
- </chapter>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode:sgml
-sgml-omittag:nil
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"./reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:("/usr/lib/sgml/catalog")
-sgml-local-ecat-files:nil
-End:
--->
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 1a85b1e580b..012569550a6 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -1,9 +1,12 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.38 2000/07/01 15:05:47 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.39 2000/07/21 00:44:13 petere Exp $
 -->
 
 <!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
 
+<!entity version "7.1">
+<!entity majorversion "7.1">
+
 <!entity about      SYSTEM "about.sgml">
 <!entity history    SYSTEM "history.sgml">
 <!entity info       SYSTEM "info.sgml">
@@ -47,12 +50,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.38 2000/07/01 15:05:47 pe
 %allfiles;
 
 <!-- administrator's guide -->
-<!entity config      SYSTEM "config.sgml">
 <!entity intro-ag    SYSTEM "intro-ag.sgml">
-<!entity install     SYSTEM "install.sgml">
+<!entity installation SYSTEM "installation.sgml">
 <!entity installw    SYSTEM "install-win32.sgml">
-<!entity layout      SYSTEM "layout.sgml">
-<!entity ports       SYSTEM "ports.sgml">
 <!entity recovery    SYSTEM "recovery.sgml">
 <!entity regress     SYSTEM "regress.sgml">
 <!entity release     SYSTEM "release.sgml">
@@ -103,6 +103,12 @@ $Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.38 2000/07/01 15:05:47 pe
 <!entity page       SYSTEM "page.sgml">
 <!entity protocol   SYSTEM "protocol.sgml">
 <!entity sources    SYSTEM "sources.sgml">
+
+
+<!-- see standalone-install.sgml about these -->
+<!entity % flattext-install-ignore  "INCLUDE">
+<!entity % flattext-install-include "IGNORE">
+
 ]>
 <!-- entity manpages SYSTEM "man/manpages.sgml" subdoc -->
 
@@ -217,10 +223,7 @@ Your name here...
   included twice.
    &intro-ag;
 -->
-   &ports;
-   &config;
-   &layout;
-   &install;
+   &installation;
    &installw;
    &runtime;
    &client-auth;
diff --git a/doc/src/sgml/standalone-install.sgml b/doc/src/sgml/standalone-install.sgml
new file mode 100644
index 00000000000..b1a3a929bdc
--- /dev/null
+++ b/doc/src/sgml/standalone-install.sgml
@@ -0,0 +1,42 @@
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/standalone-install.sgml,v 2.1 2000/07/21 00:44:13 petere Exp $ -->
+
+<!--
+This file helps in generating the INSTALL text file that lives in the
+top level directory of the distribution. The exact process is like
+this:
+
+1. Paste together with installation.sgml
+
+2. Process with jade to HTML (use -V nochunks)
+
+3. Remove "Chapter 1" heading
+
+4. Save as text file in Netscape
+
+5. Put in place of old INSTALL file
+
+Running `make INSTALL' in the doc/src/sgml directory will do 1 through
+3 for you.
+-->
+
+<!doctype chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+
+ <!entity version "7.1">
+ <!entity majorversion "7.1">
+
+<!--
+The standalone version has some portions that are different from the
+version that is integrated into the Administrator's Guide, in
+particular as regards links. The following are essentially SGML's
+equivalent of C's #ifdef and friends. The other end of this is in
+installation.sgml.
+-->
+
+ <!entity % flattext-install-ignore  "IGNORE">
+ <!entity % flattext-install-include "INCLUDE">
+
+<!--
+When you're building the Administrator's Guide, you want to flip the
+IGNORE and INCLUDE.
+-->
+]>