New blood and fresh air for tutorial

1 files changed, 341 insertions, 350 deletions

diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml
index ebbccfd042..61ca3a69b3 100644
--- a/doc/src/sgml/start.sgml
+++ b/doc/src/sgml/start.sgml
@@ -1,414 +1,405 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.16 2001/07/15 13:45:03 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.17 2001/09/02 23:27:49 petere Exp $
 -->
 
- <chapter id="start">
+ <chapter id="tutorial-start">
   <title>Getting Started</title>
 
-  <abstract>
+  <sect1 id="tutorial-install">
+   <title>Installation</title>
+
+   <para>
+    Before you can use <productname>PostgreSQL</productname> you need
+    to install it, of course.  It is possible that
+    <productname>PostgreSQL</productname> is already installed at your
+    site, either because it was included in your operating system
+    distribution or because the system administrator already installed
+    it.  If that is the case, you should obtain information from the
+    operating system documentation or your system administrator about
+    how to access <productname>PostgreSQL</productname>.
+   </para>
+
    <para>
-    How to begin work with <productname>Postgres</productname> for a new user.
+    If you are not sure whether <productname>PostgreSQL</productname>
+    is already available or whether you can use it for your
+    experimentation then you can install it yourself.  Doing so is not
+    hard and it can be a good exercise.
+    <productname>PostgreSQL</productname> can be installed by any
+    unprivileged user, no superuser (<systemitem>root</systemitem>)
+    access is required.
    </para>
-  </abstract>
-
-  <para>
-   Some  of the steps required to use <productname>Postgres</productname>
-   can be performed by any Postgres user, and some must be done by
-   the site database administrator.  This site administrator 
-   is the person who installed the  software,  created
-   the  database  directories  and  started the
-   <application>postmaster</application>
-   process.  This person does not  have  to  be  the  Unix
-   superuser ("root")
-   or the computer system administrator; a person can install and use
-   <productname>Postgres</productname> without any special accounts or 
-   privileges.
-  </para>
-
-  <para>
-   If you are installing <productname>Postgres</productname> yourself, then
-   refer to the Administrator's Guide for instructions on
-   installation, and return
-   to this guide when the installation is complete.
-  </para>
-
-  <para>
-   Throughout this manual, any examples  that  begin  with
-   the  character  "<literal>%</literal>" are commands that should be typed
-   at the Unix shell prompt.  Examples that begin with the
-   character "<literal>*</literal>" are commands in the Postgres query 
-   language, Postgres <acronym>SQL</acronym>.
-  </para>
-
-  <sect1 id="start-env">
-   <title>Setting Up Your Environment</title>
 
    <para>
-    This section discusses how to set up
-    your own environment  so  that  you  can  use  frontend
-    applications.  We assume <productname>Postgres</productname> has
-    already been 
-    successfully installed and started; refer to the Administrator's Guide
-    and the installation  notes
-    for how to install Postgres.
+    If you are installing <productname>PostgreSQL</productname>
+    yourself, then refer to the <citetitle>Administrator's
+    Guide</citetitle> for instructions on installation, and return to
+    this guide when the installation is complete.  Be sure to follow
+    closely the section about setting up the appropriate environment
+    variables.
    </para>
 
    <para>
-    <productname>Postgres</productname> is a client/server
-    application. As a user,
-    you only need access to the client portions of the installation
-    (an example
-    of a client application is the interactive monitor
-    <application>psql</application>).
-    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 <filename>.login</filename> 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 <quote>setting a shell  
-     variable</quote>  or  <quote>setting an environment
-     variable</quote> 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.
+    If your site administrator has 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 database, you should consult your
+    site administrator or, if that is you, the documentation to make
+    sure that your environment is properly set up.  If you did not
+    understand the preceding paragraph then read the next section.
    </para>
+  </sect1>
+
+
+  <sect1 id="tutorial-arch">
+   <title>Architectural Fundamentals</title>
 
    <para>
-    If your site administrator has 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 <acronym>PGHOST</acronym> environment
-    variable to the name
-    of the database server machine.   The  environment  variable
-    <acronym>PGPORT</acronym> 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 should immediately consult your site administrator to make
-    sure that your
-    environment is properly set up.
+    Before we proceed, you should understand the basic
+    <productname>PostgreSQL</productname> system architecture.
+    Understanding how the parts of
+    <productname>PostgreSQL</productname> interact will make the next
+    chapter somewhat clearer.
    </para>
 
+   <para>
+    In database jargon, <productname>PostgreSQL</productname> uses a
+    client/server model.  A <productname>PostgreSQL</productname>
+    session consists of the following cooperating processes
+    (programs):
+
+    <itemizedlist>
+     <listitem>
+      <para>
+       A server process, which manages the database files, accepts
+       connections to the database from client applications, and
+       performs actions on the database on behalf of the clients.  The
+       database server program is called
+       <filename>postmaster</filename>.
+       <indexterm><primary>postmaster</primary></indexterm>
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       The user's client (frontend) application that wants to perform
+       database operations.  Client applications can be very diverse
+       in nature:  They could be a text-oriented tool, a graphical
+       application, a web server that accesses the database to
+       display web pages, or a specialized database maintenance tool.
+       Some client applications are supplied with the
+       <productname>PostgreSQL</productname> distribution, most are
+       developed by users.
+      </para>
+     </listitem>
+
+    </itemizedlist>
+   </para>
+
+   <para>
+    As is typical of client/server applications, the client and the
+    server can be on different hosts.  In that case they communicate
+    over a TCP/IP network connection.  You should keep this in mind,
+    because the files that can be accessed on a client machine might
+    not be accessible (or might only be accessed using a different
+    file name) on the database server machine.
+   </para>
+
+   <para>
+    The <productname>PostgreSQL</productname> server can handle
+    multiple concurrent connections from clients.  For that purpose it
+    starts (<quote>forks</quote>) a new process for each connection.
+    From that point on, the client and the new server process
+    communicate without intervention by the original
+    <filename>postmaster</filename> process.  Thus, the
+    <filename>postmaster</filename> is always running, waiting for
+    client connections, whereas client and associated server processes
+    come and go.  (All of this is of course invisible to the user.  We
+    only mention it here for completeness.)
+   </para>
   </sect1>
 
-  <sect1 id="start-psql">
-   <title>Starting the Interactive Monitor (psql)</title>
+
+  <sect1 id="tutorial-createdb">
+   <title>Creating a Database</title>
+
+   <indexterm zone="tutorial-createdb">
+    <primary>database</primary>
+    <secondary>creating</secondary>
+   </indexterm>
+
+   <indexterm zone="tutorial-createdb">
+    <primary>createdb</primary>
+   </indexterm>
 
    <para>
-    Assuming that  your  site  administrator  has  properly
-    started  the  <application>postmaster</application>  process and
-    authorized you to
-    use the database, you (as a user) may begin to start up
-    applications.   As previously mentioned, you should add
-    <filename>/usr/local/pgsql/bin</filename> to your  shell  search path.
-    In  most  cases,  this  is all you should have to do in
-    terms of preparation.
+    The first test to see whether you can access the database server
+    is to try to create a database.  A running
+    <productname>PostgreSQL</productname> server can manage many
+    databases.  Typically, a separate database is used for each
+    project or for each user.
    </para>
 
    <para>
-    Two different styles of connections
-    are supported. The site administrator will have chosen to allow
-    TCP/IP network connections
-    or will have restricted database access to local (same-machine)
-    socket connections only.
-    These choices become significant if you encounter problems in
-    connecting to a database, since you will want to confirm that you
-    are choosing an allowed connection option.
+    Possibly, your site administrator has already created a database
+    for your use.  He should have told you what the name of your
+    database is.  In this case you can omit this step and skip ahead
+    to the next section.
    </para>
 
    <para>
-    If  you get the following error message from a
-    <productname>Postgres</productname>
-    command (such as <application>psql</application> or
-    <application>createdb</application>):
+    To create a new database, in this example named
+    <quote>mydb</quote>, you use the following command:
+<screen>
+<prompt>$</prompt> <userinput>createdb mydb</userinput>
+</screen>
+    This should produce as response:
+<screen>
+CREATE DATABASE
+</screen>
+    Is so, this step was successful and you can skip over the
+    remainder of this section.
+   </para>
 
-    <programlisting>
-% psql template1
+   <para>
+    If you see a message similar to
+<screen>
+createdb: command not found
+</screen>
+    then PostgreSQL was not installed properly.  Either it was not
+    installed at all or the search path was not set correctly.  Try
+    calling the command with an absolute path instead:
+<screen>
+<prompt>$</prompt> <userinput>/usr/local/pgsql/bin/createdb</userinput>
+</screen>
+    The path at your site might be different.  Contact your site
+    administrator or check back in the installation instructions to
+    correct the situation.
+   </para>
+
+   <para>
+    Another response could be this:
+<screen>
 psql: could not connect to server: Connection refused
         Is the server running locally and accepting
         connections on Unix domain socket "/tmp/.s.PGSQL.5432"?
-    </programlisting>
+createdb: database creation failed
+</screen>
+    This means that the server was not started, or it was not started
+    where <command>createdb</command> expected it.  Again, check the
+    installation instructions or consult the administrator.
+   </para>
 
-    or
+   <para>
+    If you do not have the privileges required to create a database,
+    you will see the following:
+<screen>
+ERROR:  CREATE DATABASE: permission denied
+createdb: database creation failed
+</screen>
+    Not every user has authorization to create new databases.  If
+    <productname>PostgreSQL</productname> refuses to create databases
+    for you then the site administrator needs to grant you permission
+    to create databases.  Consult your site administrator if this
+    occurs.  If you installed <productname>PostgreSQL</productname>
+    yourself then you should log in for the purposes of this tutorial
+    under the user account that you started the server as.
+
+    <footnote>
+     <para>
+      As an explanation for why this works:
+      <productname>PostgreSQL</productname> user names are separate
+      from operating system user accounts.  If you connect to a
+      database, you can choose what
+      <productname>PostgreSQL</productname> user name to connect as;
+      if you don't, it will default to the same name as your current
+      operating system account.  As it happens, there will always be a
+      <productname>PostgreSQL</productname> user account that has the
+      same name as the operating system user that started the server,
+      and it also happens that that user always has permission to
+      create databases.  Instead of logging in as that user you can
+      also specify the <option>-U</option> option everywhere to select
+      a <productname>PostgreSQL</productname> user name to connect as.
+     </para>
+    </footnote>
+   </para>
+
+   <para>
+    You can also create databases with other names.
+    <productname>PostgreSQL</productname> allows you to create any
+    number of databases at a given site.  Database names must have an
+    alphabetic first character and are limited to 32 characters in
+    length.  A convenient choice is to create a database with the same
+    name as your current user name.  Many tools assume that database
+    name as the default, so it can save you some typing.  To create
+    that database, simply type
+<screen>
+<prompt>$</prompt> <userinput>createdb</userinput>
+</screen>
+   </para>
+
+   <para>
+    If you don't want to use your database anymore you can remove it.
+    For example, if you are the owner (creator) of the database
+    <quote>mydb</quote>, you can destroy it using the following
+    command:
+<screen>
+<prompt>$</prompt> <userinput>dropdb mydb</userinput>
+</screen>
+    (In this case, the database name does not default to the user
+    account name.  You always need to specify it.)  This action
+    physically removes all files associated with the database and
+    cannot be undone, so this should only be done with a great deal of
+    forethought.
+   </para>
+  </sect1>
 
-    <programlisting>
-% psql -h localhost template1
-psql: could not connect to server: Connection refused
-        Is the server running on host localhost and accepting
-        TCP/IP connections on port 5432?
-    </programlisting>
 
-    it is usually because
+  <sect1 id="tutorial-accessdb">
+   <title>Accessing a Database</title>
+
+   <indexterm zone="tutorial-accessdb">
+    <primary>psql</primary>
+   </indexterm>
+
+   <para>
+    Once you have created a database, you can access it by:
+
+    <itemizedlist spacing="compact" mark="bullet">
+     <listitem>
+      <para>
+       Running the <productname>PostgreSQL</productname> interactive
+       terminal program, called <quote>psql</quote>, which allows you
+       to interactively enter, edit, and execute
+       <acronym>SQL</acronym> commands.
+      </para>
+     </listitem>
 
-    <itemizedlist mark="bullet" spacing="compact">
      <listitem>
       <para>
-       the <application>postmaster</application>  is  not  running,
-       or
+       Using an existing graphical frontend tool like
+       <application>PgAccess</application> or
+       <application>ApplixWare</application> (via
+       <acronym>ODBC</acronym>) to create and manipulate a database.
+       These possibilities are not covered in this tutorial.
       </para>
      </listitem>
 
      <listitem>
       <para>
-       you are attempting to connect to the wrong server host.
+       Writing a custom application, using one of the several
+       available language bindings.  These possibilities are discussed
+       further in <citetitle>The PostgreSQL Programmer's
+       Guide</citetitle>.
       </para>
      </listitem>
     </itemizedlist>
+
+    You probably want to start up <command>psql</command>, to try out
+    the examples in this tutorial.  It can be activated for the
+    <quote>mydb</quote> database by typing the command:
+<screen>
+<prompt>$</prompt> <userinput>psql mydb</userinput>
+</screen>
+    If you leave off the database name then it will default to your
+    user account name.  You already discovered this scheme in the
+    previous section.
    </para>
 
    <para>
-    If you get the following error message:
-
-    <programlisting>
-FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268)
-    </programlisting>
-
-    it means that the site administrator started the
-    <application>postmaster</application>
-    as  the  wrong user.  Tell him to restart it as
-    the <productname>Postgres</productname> superuser.
+    In <command>psql</command>, you will be greeted with the following
+    message:
+<screen>
+Welcome to psql, the PostgreSQL interactive terminal.
+ 
+Type:  \copyright for distribution terms
+       \h for help with SQL commands
+       \? for help on internal slash commands
+       \g or terminate with semicolon to execute query
+       \q to quit
+ 
+mydb=&gt;
+</screen>
+    <indexterm><primary>superuser</primary></indexterm>
+    The last line could also be
+<screen>
+mydb=#
+</screen>
+    That would mean you are a database superuser, which is most likely
+    the case if you installed <productname>PostgreSQL</productname>
+    yourself.  Being a superuser means that you are not subject to
+    access controls.  For the purpose of this tutorial this is not of
+    importance.
    </para>
-  </sect1>
 
-  <sect1 id="start-manage-db">
-   <title>Managing a Database</title>
+   <para>
+    If you have encountered problems starting <command>psql</command>
+    then go back to the previous section.  The diagnostics of
+    <command>psql</command> and <command>createdb</command> are
+    similar, and if the latter worked the former should work as well.
+   </para>
 
    <para>
-    Now that <productname>Postgres</productname> is up and running we
-    can create  some
-    databases  to  experiment  with.  Here, we describe the
-    basic commands for managing a database.
+    The last line printed out by <command>psql</command> is the
+    prompt, and it indicates that <command>psql</command> is listening
+    to you and that you can type <acronym>SQL</acronym> queries into a
+    workspace maintained by <command>psql</command>.  Try out these
+    commands:
+    <indexterm><primary>version</primary></indexterm>
+<screen>
+<prompt>mydb=&gt;</prompt> <userinput>SELECT version();</userinput>
+                            version
+----------------------------------------------------------------
+ PostgreSQL 7.2devel on i586-pc-linux-gnu, compiled by GCC 2.96
+(1 row)
+
+<prompt>mydb=&gt;</prompt> <userinput>SELECT current_date;</userinput>
+    date
+------------
+ 2001-08-31
+(1 row)
+
+<prompt>mydb=&gt;</prompt> <userinput>SELECT 2 + 2;</userinput>
+ ?column?
+----------
+        4
+(1 row)
+</screen>
    </para>
 
    <para>
-    Most <productname>Postgres</productname>
-    applications assume that the database name, if not specified, is
-    the same as the name on your computer
-    account.
+    The <command>psql</command> program has a number of internal
+    commands that are not SQL commands.  They begin the backslash
+    character, <quote><literal>\</literal></quote>.  Some of these
+    commands were already listed in the welcome message.  For example,
+    you can get help on the syntax of various
+    <productname>PostgreSQL</productname> <acronym>SQL</acronym>
+    commands by typing:
+<screen>
+<prompt>mydb=&gt;</prompt> <userinput>\h</userinput>
+</screen>
    </para>
 
    <para>
-    If your database administrator has set up your account without
-    database creation privileges,
-    then she should have told you what the name of your database is. If
-    this is the case, then you
-    can skip the sections on creating and destroying databases.
+    To get out of <command>psql</command>, type
+<screen>
+<prompt>mydb=&gt;</prompt> <userinput>\q</userinput>
+</screen>
+    and <command>psql</command> will quit and return you to your
+    command shell. (For more internal commands, type
+    <literal>\?</literal> at the <command>psql</command> prompt.)  The
+    full capabilities of <command>psql</command> are documented in the
+    <citetitle>Reference Manual</citetitle>.  If PostgreSQL is
+    installed correctly you can also type <literal>man psql</literal>
+    at the operating system shell prompt to see the documentation.  In
+    this tutorial we will not use these features explicitly, but you
+    can use them yourself when you see it fit.
    </para>
 
-   <sect2>
-    <title>Creating a Database</title>
-
-    <para>
-     Let's say you want to create  a  database  named
-     <database>mydb</database>.
-     You can do this with the following command:
-     <programlisting>
-% createdb mydb
-     </programlisting>
-    </para>
-
-    <para>
-     If you do not have the privileges required to create a database,
-     you will see
-     the following:
-     <programlisting>
-% createdb mydb
-NOTICE:user "your username" is not allowed to create/destroy databases
-createdb: database creation failed on mydb.
-     </programlisting>
-    </para>
-
-    <para>
-     <productname>Postgres</productname>  allows  you to create any
-     number of databases
-     at a  given  site  and  you  automatically  become  the
-     database  administrator  of  the database you just created.
-     Database names must  have  an  alphabetic  first
-     character and are limited to 32 characters in length.
-     Not  every  user has authorization to become a database
-     administrator.  If <productname>Postgres</productname> refuses to 
-     create databases
-     for you, then the site administrator needs to grant you
-     permission to  create  databases.   Consult  your  site
-     administrator if this occurs.
-    </para>
-   </sect2>
-
-   <sect2>
-    <title>Accessing a Database</title>
-
-    <para>
-     Once you have constructed a database, you can access it
-     by:
-
-     <itemizedlist spacing="compact" mark="bullet">
-      <listitem>
-       <para>
-	Running the <productname>Postgres</productname>  terminal
-	monitor  programs
-	(e.g. <application>psql</application>) which allows you to
-	interactively
-        enter, edit, and execute <acronym>SQL</acronym> commands.
-       </para>
-      </listitem>
-
-      <listitem>
-       <para>
-	Using an existing native frontend tool like
-	<application>pgaccess</application> or
-	<application>ApplixWare</application> (via
-	<acronym>ODBC</acronym>) to create and manipulate a 
-	database.
-       </para>
-      </listitem>
-
-      <listitem>
-       <para>
-	Using a language like perl or tcl which has a supported
-	interface for <productname>Postgres</productname>. Some of
-	these languages also have convenient and powerful GUI toolkits 
-	which can help you construct custom
-	applications. <application>pgaccess</application>, mentioned
-	above, is one such application written in tk/tcl and can be
-	used as an example.
-       </para>
-      </listitem>
-
-      <listitem>
-       <para>
-	Writing a <acronym>C</acronym>  program  using
-	the  LIBPQ  subroutine
-        library.   This  allows  you  to submit
-	<acronym>SQL</acronym> commands
-        from <acronym>C</acronym> and get answers and
-	status messages  back  to
-        your  program.   This interface is discussed further
-        in <citetitle>The PostgreSQL Programmer's Guide</citetitle>.
-       </para>
-      </listitem>
-     </itemizedlist>
-
-     You might want to start up <application>psql</application>, 
-     to try out the examples in this manual.
-     It can be activated for the <database>mydb</database>
-     database by typing the command:
-     <programlisting>
-% psql mydb
-     </programlisting>
-
-     You will be greeted with the following message:
-     <programlisting>
-Welcome to the POSTGRESQL interactive sql monitor:
-  Please read the file COPYRIGHT for copyright terms of POSTGRESQL
-
-   type \? for help on slash commands
-   type \q to quit
-   type \g or terminate with semicolon to execute query
- You are currently connected to the database: template1
-
-mydb=>
-     </programlisting>
-    </para>
-
-    <para>
-     This prompt indicates that the terminal monitor is listening
-     to you and that you can type <acronym>SQL</acronym> queries into a
-     workspace maintained by the terminal monitor.
-     The <application>psql</application> program responds to escape
-     codes  that  begin
-     with  the  backslash  character, "<literal>\</literal>"  For example, you
-     can get help on the syntax of various
-     <productname>Postgres</productname> <acronym>SQL</acronym>
-     commands by typing:
-     <programlisting>
-mydb=> \h
-     </programlisting>
-    </para>
-
-    <para>
-     Once  you  have finished entering your queries into the
-     workspace, you can pass the contents of  the  workspace
-     to the <productname>Postgres</productname> server by typing:
-     <programlisting>
-mydb=> \g
-     </programlisting>
-
-     This  tells  the  server  to process the query.  If you
-     terminate your query with a semicolon, the  "<literal>\g</literal>" is  not
-     necessary.
-     <application>psql</application> will automatically process
-     semicolon terminated queries.
-     To read queries from a file,  say  myFile,  instead  of
-     entering them interactively, type:
-     <programlisting>
-mydb=> \i fileName
-     </programlisting>
-
-     To get out of <application>psql</application> and return to Unix, type
-     <programlisting>
-mydb=> \q
-     </programlisting>
-
-     and  <application>psql</application>  will  quit  and  return
-     you to your command
-     shell. (For more escape codes, type <command>\h</command> at  the 
-     monitor prompt.)
-     White  space  (i.e.,  spaces, tabs and newlines) may be
-     used freely in <acronym>SQL</acronym> queries.  Single-line
-     comments  are  denoted  by
-     "<literal>--</literal>".   Everything  after the dashes up to the end of the
-     line is ignored. Multiple-line comments, and comments within a line,
-     are denoted by "<literal>/* ... */</literal>".
-    </para>
-   </sect2>
-
-   <sect2>
-    <title>Destroying a Database</title>
-
-    <para>
-     If you are the database administrator for the  database
-     <database>mydb</database>,  you can destroy it using the
-     following Unix command:
-     <programlisting>
-% dropdb mydb
-     </programlisting>
-     This action physically removes all of  the  Unix  files
-     associated  with  the database and cannot be undone, so
-     this should only be done with a  great  deal  of  forethought.
-    </para>
-   </sect2>
   </sect1>
-
  </chapter>
 
 <!-- Keep this comment at the end of the file