Add introductory sections explaining what each book is about. Remove Y2K

statement.

19 files changed, 260 insertions, 210 deletions

diff --git a/doc/src/sgml/admin.sgml b/doc/src/sgml/admin.sgml
index 59174345063..f1cb16d9e10 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.39 2002/10/16 22:06:33 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.40 2002/10/24 17:48:54 petere Exp $
 -->
 
 <book id="admin">
@@ -13,14 +13,60 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.39 2002/10/16 22:06:33
   &legal;
  </bookinfo>
 
-<!--
-  Disable these extra intro chapters since some elements (e.g. y2k
-  statement) are included in the first intro.sgml and cause errors if
-  included twice.
--->
+ <preface id="admin-preface">
+  <title>Preface</title>
+
 <![%single-book;[
   &intro;
+  &history;
+]]>
+
+  <sect1 id="admin-preface-thisbook">
+   <title>What's In This Book</title>
+
+   <para>
+    This book covers topics that are of interest to a PostgreSQL
+    database administrator.  This includes installation of the
+    software, set up and configuration of the server, management of
+    users and databases, and maintenance tasks.  Anyone who runs a
+    PostgreSQL server, either for personal use, but especially in
+    production, should be familiar with the topics covered in this
+    book.
+   </para>
+
+   <para>
+    The information in this book is arranged approximately in the
+    order in which a new user should read it.  But the chapters are
+    self-contained and can be read individually as desired.  The
+    information in this book is presented in a narrative fashion in
+    topical units.  Readers looking for a complete description of a
+    particular command should look into the &cite-reference;.
+   </para>
+
+   <para>
+    The first few chapters are written so that they can be understood
+    without prerequisite knowledge, so that new users who need to set
+    up their own server can begin their exploration with this book.
+    The rest of this book which is about tuning and management
+    presupposes that the reader is familiar with the general use of
+    the PostgreSQL database system.  Readers are encouraged to look at
+    the &cite-tutorial; and the &cite-user; for additional
+    information.
+   </para>
+
+   <para>
+    This book covers <productname>PostgreSQL &version;</productname>
+    only.  For information on other versions, please read the
+    documentation that accompanies that release.
+   </para>
+  </sect1>
+
+<![%single-book;[
+  &info;
+  &notation;
+  &problems;
 ]]>
+ </preface>
 
   &installation;
   &installw;
diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml
index 2f7e43604d8..1a39a9b8ffa 100644
--- a/doc/src/sgml/advanced.sgml
+++ b/doc/src/sgml/advanced.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.29 2002/10/20 05:05:46 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.30 2002/10/24 17:48:54 petere Exp $
 -->
 
  <chapter id="tutorial-advanced">
@@ -130,7 +130,7 @@ ERROR:  &lt;unnamed&gt; referential integrity violation - key referenced from we
    <para>
     The behavior of foreign keys can be finely tuned to your
     application.  We will not go beyond this simple example in this
-    tutorial, but just refer you to &cite-reference;
+    tutorial, but just refer you to the &cite-reference;
     for more information.  Making correct use of
     foreign keys will definitely improve the quality of your database
     applications, so you are strongly encouraged to learn about them.
@@ -394,8 +394,8 @@ SELECT name, altitude
     <productname>PostgreSQL</productname> has many features not
     touched upon in this tutorial introduction, which has been
     oriented toward newer users of <acronym>SQL</acronym>.  These
-    features are discussed in more detail in both &cite-user;
-    and &cite-programmer;.
+    features are discussed in more detail in both the &cite-user;
+    and the &cite-programmer;.
    </para>
 
    <para>
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 253d163ede4..7921b4320d0 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ddl.sgml,v 1.6 2002/10/20 05:05:46 tgl Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ddl.sgml,v 1.7 2002/10/24 17:48:54 petere Exp $ -->
 
 <chapter id="ddl">
  <title>Data Definition</title>
@@ -13,7 +13,7 @@
   schemas, and how privileges can be assigned to tables.  Finally,
   we will briefly look at other features that affect the data storage,
   such as views, functions, and triggers.  Detailed information on
-  these topics is found in &cite-programmer;.
+  these topics is found in the &cite-programmer;.
  </para>
 
  <sect1 id="ddl-basics">
@@ -786,7 +786,7 @@ CREATE TABLE order_items (
     If the foreign key references a unique constraint, there are some
     additional possibilities regarding how null values are matched.
     These are explained in the <literal>CREATE TABLE</literal> entry
-    in &cite-reference;.
+    in the &cite-reference;.
    </para>
   </sect2>
  </sect1>
diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml
index 920ea5f1eff..d53c9e54aeb 100644
--- a/doc/src/sgml/ecpg.sgml
+++ b/doc/src/sgml/ecpg.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.38 2002/10/21 18:04:05 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.39 2002/10/24 17:48:54 petere Exp $
 -->
 
 <chapter id="ecpg">
@@ -798,7 +798,7 @@ ECPG = ecpg
 
   <para>
    The complete syntax of the <command>ecpg</command> command is
-   detailed in &cite-reference;.
+   detailed in the &cite-reference;.
   </para>
  </sect1>
 
diff --git a/doc/src/sgml/entities.sgml b/doc/src/sgml/entities.sgml
index 14f201fae61..66e4092cdb8 100644
--- a/doc/src/sgml/entities.sgml
+++ b/doc/src/sgml/entities.sgml
@@ -1,20 +1,20 @@
 <![%single-book;[
 
-<!entity cite-admin "the <citetitle>PostgreSQL Administrator's Guide</citetitle>">
-<!entity cite-developer "the <citetitle>PostgreSQL Developer's Guide</citetitle>">
-<!entity cite-programmer "the <citetitle>PostgreSQL Programmer's Guide</citetitle>">
-<!entity cite-reference "the <citetitle>PostgreSQL Reference Manual</citetitle>">
-<!entity cite-tutorial "the <citetitle>PostgreSQL Tutorial</citetitle>">
-<!entity cite-user "the <citetitle>PostgreSQL User's Guide</citetitle>">
+<!entity cite-admin "<citetitle>PostgreSQL Administrator's Guide</citetitle>">
+<!entity cite-developer "<citetitle>PostgreSQL Developer's Guide</citetitle>">
+<!entity cite-programmer "<citetitle>PostgreSQL Programmer's Guide</citetitle>">
+<!entity cite-reference "<citetitle>PostgreSQL Reference Manual</citetitle>">
+<!entity cite-tutorial "<citetitle>PostgreSQL Tutorial</citetitle>">
+<!entity cite-user "<citetitle>PostgreSQL User's Guide</citetitle>">
 
 ]]>
 <![%set-of-books;[
 
-<!entity cite-admin "the <xref linkend='admin'>">
-<!entity cite-developer "the <xref linkend='developer'>">
-<!entity cite-programmer "the <xref linkend='programmer'>">
-<!entity cite-reference "the <xref linkend='reference'>">
-<!entity cite-tutorial "the <xref linkend='tutorial'>">
-<!entity cite-user "the <xref linkend='user'>">
+<!entity cite-admin "<xref linkend='admin'>">
+<!entity cite-developer "<xref linkend='developer'>">
+<!entity cite-programmer "<xref linkend='programmer'>">
+<!entity cite-reference "<xref linkend='reference'>">
+<!entity cite-tutorial "<xref linkend='tutorial'>">
+<!entity cite-user "<xref linkend='user'>">
 
 ]]>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 5fd2325988f..7331dcda736 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.24 2002/10/16 22:06:33 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.25 2002/10/24 17:48:54 petere Exp $ -->
 
 <!entity history    SYSTEM "history.sgml">
 <!entity info       SYSTEM "info.sgml">
@@ -6,7 +6,6 @@
 <!entity legal      SYSTEM "legal.sgml">
 <!entity notation   SYSTEM "notation.sgml">
 <!entity problems   SYSTEM "problems.sgml">
-<!entity y2k        SYSTEM "y2k.sgml">
 
 <!entity bookindex  SYSTEM "bookindex.sgml">
 <!entity setindex   SYSTEM "setindex.sgml">
diff --git a/doc/src/sgml/info.sgml b/doc/src/sgml/info.sgml
index c3700650edd..892292e5538 100644
--- a/doc/src/sgml/info.sgml
+++ b/doc/src/sgml/info.sgml
@@ -1,71 +1,76 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.15 2001/11/28 20:49:10 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.16 2002/10/24 17:48:54 petere Exp $
 -->
 
 <sect1 id="resources">
- <title>Documentation Resources</title>
+ <title>Overview of Documentation Resources</title>
 
  <para>
-  This manual set is organized into several parts:
+  The PostgreSQL documentation is organized into several books:
 
   <variablelist>
    <varlistentry>
-    <term>Tutorial</term>
+    <term>&cite-tutorial;</term>
     <listitem>
      <para>
-      An informal introduction for new users
+      An informal introduction for new users.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-    <term>User's Guide</term>
+    <term>&cite-user;</term>
     <listitem>
      <para>
-      Documents the SQL query language environment, including data types
-      and functions.
+      Documents the SQL query language environment, including data
+      types and functions, as well as user-level performance tuning.
+      Every PostgreSQL user should read this.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-    <term>Programmer's Guide</term>
+    <term>&cite-admin;</term>
     <listitem>
      <para>
-      Advanced information for application programmers. Topics include
-      type and function extensibility, library interfaces,
-      and application design issues.
+      Installation and server management information.  Everyone who
+      runs a PostgreSQL server, either for personal use or for other
+      users, needs to read this.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-    <term>Administrator's Guide</term>
+    <term>&cite-programmer;</term>
     <listitem>
      <para>
-      Installation and server management information
+      Advanced information for application programmers. Topics include
+      type and function extensibility, library interfaces, and
+      application design issues.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-    <term>Reference Manual</term>
+    <term>&cite-reference;</term>
     <listitem>
      <para>
-      Reference pages for SQL command syntax and client and server programs
+      Reference pages for SQL command syntax, and client and server
+      programs.  This book is auxiliary to the User's,
+      Administrator's, and Programmer's Guides.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-    <term>Developer's Guide</term>
+    <term>&cite-developer;</term>
     <listitem>
      <para>
-      Information for <productname>PostgreSQL</productname> developers.
-      This is intended for those who are contributing to the
-      <productname>PostgreSQL</productname> project;
-      application development information appears in the 
-      <citetitle>Programmer's Guide</citetitle>.
+      Information for <productname>PostgreSQL</productname>
+      developers.  This is intended for those who are contributing to
+      the <productname>PostgreSQL</productname> project; application
+      development information appears in the <citetitle>Programmer's
+      Guide</citetitle>.
      </para>
     </listitem>
    </varlistentry>
@@ -81,8 +86,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.15 2001/11/28 20:49:10 petere
     <term>man pages</term>
     <listitem>
      <para>
-      The <citetitle>Reference Manual</citetitle>'s pages in the traditional
-      Unix man format.
+      The <citetitle>Reference Manual</citetitle>'s pages in the
+      traditional Unix man format.  There is no difference in content.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/intro.sgml b/doc/src/sgml/intro.sgml
index 5b98495e93d..ba5653f155c 100644
--- a/doc/src/sgml/intro.sgml
+++ b/doc/src/sgml/intro.sgml
@@ -1,10 +1,7 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.19 2002/01/07 02:29:12 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.20 2002/10/24 17:48:54 petere Exp $
 -->
 
- <preface id="preface">
-  <title>Preface</title>
-
   <sect1 id="intro-whatis">
    <title> What is <productname>PostgreSQL</productname>?</title>
 
@@ -95,14 +92,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.19 2002/01/07 02:29:12 peter
 
   </sect1>
 
-   &history;
-   &info;
-   &notation;
-   &problems;
-   &y2k;
-
- </preface>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode:sgml
diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml
index e37864f79ee..d761b8f18ac 100644
--- a/doc/src/sgml/manage-ag.sgml
+++ b/doc/src/sgml/manage-ag.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.21 2002/09/25 21:16:10 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.22 2002/10/24 17:48:54 petere Exp $
 -->
 
 <chapter id="managing-databases">
@@ -47,7 +47,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.21 2002/09/25 21:16:10 p
    into separate databases.  If the projects or users are interrelated
    and should be able to use each other's resources they should be put
    in the same databases but possibly into separate schemas.  More
-   information about managing schemas is in &cite-user;.
+   information about managing schemas is in the &cite-user;.
   </para>
 
   <note>
diff --git a/doc/src/sgml/notation.sgml b/doc/src/sgml/notation.sgml
index e95735e11e1..197e5cd913e 100644
--- a/doc/src/sgml/notation.sgml
+++ b/doc/src/sgml/notation.sgml
@@ -1,17 +1,11 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.19 2001/11/23 22:06:20 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.20 2002/10/24 17:48:54 petere Exp $
 -->
 
 <sect1 id="notation">
  <title>Terminology and Notation</title>
 
  <para>
-  The terms <quote>PostgreSQL</quote> and <quote>Postgres</quote> will be
-  used interchangeably to refer to the software that accompanies this
-  documentation.
- </para>
-
- <para>
   An <firstterm>administrator</firstterm> is generally a person who is
   in charge of installing and running the server.  A <firstterm>user</firstterm>
   could be anyone who is using, or wants to use, any part of the
diff --git a/doc/src/sgml/programmer.sgml b/doc/src/sgml/programmer.sgml
index 5494ce2788c..10eebfaeba2 100644
--- a/doc/src/sgml/programmer.sgml
+++ b/doc/src/sgml/programmer.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.42 2002/09/21 18:32:53 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.43 2002/10/24 17:48:54 petere Exp $
 
 PostgreSQL Programmer's Guide.
 -->
@@ -12,9 +12,60 @@ PostgreSQL Programmer's Guide.
   &legal;
  </bookinfo>
 
-<![%single-book[
+ <preface id="programmer-preface">
+  <title>Preface</title>
+
+<![%single-book;[
   &intro;
+  &history;
+]]>
+
+  <sect1 id="programmer-preface-thisbook">
+   <title>What's In This Book</title>
+
+   <para>
+    This book is for PostgreSQL application programmers.  It is divided into three parts.
+   </para>
+
+   <para>
+    The first part of this book describes the client programming
+    interfaces distributed with PostgreSQL.  Each of these chapters
+    can be read independently.  Note that there are many other
+    programming interfaces for client programs that are distributed
+    separately and contain their own documentation.  Readers of the
+    first part should be familiar with using SQL commands to
+    manipulate and query the database (see the &cite-user;) and of
+    course with the programming language that the interface uses.
+   </para>
+
+   <para>
+    The second part of this book is about extending the server
+    functionality with user-defined functions, data types, triggers,
+    etc.  These are advanced topics which should probably be
+    approached only after all the other user documentation about
+    PostgreSQL has been understood.
+   </para>
+
+   <para>
+    The third part of this book described the available server-side
+    programming languages.  This information is related to the second
+    part and is only useful to readers that have read at least the
+    first few chapters thereof.
+   </para>
+
+   <para>
+    This book covers <productname>PostgreSQL &version;</productname>
+    only.  For information on other versions, please read the
+    documentation that accompanies that release.
+   </para>
+  </sect1>
+
+<![%single-book[
+  &info;
+  &notation;
+  &problems;
 ]]>
+ </preface>
 
  <part id="programmer-client">
   <title>Client Interfaces</title>
diff --git a/doc/src/sgml/query.sgml b/doc/src/sgml/query.sgml
index 230baa276bd..1ec9fba7226 100644
--- a/doc/src/sgml/query.sgml
+++ b/doc/src/sgml/query.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.26 2002/10/20 05:05:46 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.27 2002/10/24 17:48:54 petere Exp $
 -->
 
  <chapter id="tutorial-sql">
@@ -259,7 +259,7 @@ COPY weather FROM '/home/user/weather.txt';
     where the file name for the source file must be available to the
     backend server machine, not the client, since the backend server
     reads the file directly.  You can read more about the
-    <command>COPY</command> command in &cite-reference;.
+    <command>COPY</command> command in the &cite-reference;.
    </para>
   </sect1>
 
diff --git a/doc/src/sgml/ref/ecpg-ref.sgml b/doc/src/sgml/ref/ecpg-ref.sgml
index 310ef00060d..c2c8ec6eed7 100644
--- a/doc/src/sgml/ref/ecpg-ref.sgml
+++ b/doc/src/sgml/ref/ecpg-ref.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.21 2002/10/21 18:04:05 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.22 2002/10/24 17:48:54 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -49,7 +49,7 @@ PostgreSQL documentation
 
   <para>
    This reference page does not describe the embedded SQL language.
-   See &cite-programmer; for that.
+   See the &cite-programmer; for that.
   </para>
  </refsect1>
 
diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml
index b7eda72737c..ca1550bd6e5 100644
--- a/doc/src/sgml/start.sgml
+++ b/doc/src/sgml/start.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.25 2002/10/20 05:05:46 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.26 2002/10/24 17:48:54 petere Exp $
 -->
 
  <chapter id="tutorial-start">
@@ -31,7 +31,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.25 2002/10/20 05:05:46 tgl E
 
    <para>
     If you are installing <productname>PostgreSQL</productname>
-    yourself, then refer to &cite-admin;
+    yourself, then refer to the &cite-admin;
     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
@@ -292,7 +292,7 @@ createdb: database creation failed
       <para>
        Writing a custom application, using one of the several
        available language bindings.  These possibilities are discussed
-       further in &cite-programmer;.
+       further in the &cite-programmer;.
       </para>
      </listitem>
     </itemizedlist>
@@ -391,7 +391,7 @@ mydb=#
     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
-    &cite-reference;.  If <productname>PostgreSQL</> is
+    the &cite-reference;.  If <productname>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
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 99e7975b2b3..be1a6e764f7 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.71 2002/10/20 05:05:46 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.72 2002/10/24 17:48:54 petere Exp $
 -->
 
 <chapter id="sql-syntax">
@@ -73,7 +73,7 @@ INSERT INTO MY_TABLE VALUES (3, 'hi there');
    a <token>SET</token> token to appear in a certain position, and
    this particular variation of <command>INSERT</command> also
    requires a <token>VALUES</token> in order to be complete.  The
-   precise syntax rules for each command are described in
+   precise syntax rules for each command are described in the
    &cite-reference;.
   </para>
 
diff --git a/doc/src/sgml/tutorial.sgml b/doc/src/sgml/tutorial.sgml
index ed7688de634..55d340362e2 100644
--- a/doc/src/sgml/tutorial.sgml
+++ b/doc/src/sgml/tutorial.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/tutorial.sgml,v 1.16 2002/10/20 05:05:46 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/tutorial.sgml,v 1.17 2002/10/24 17:48:54 petere Exp $
 -->
 
 <book id="tutorial">
@@ -10,36 +10,48 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/tutorial.sgml,v 1.16 2002/10/20 05:05
   &legal;
  </bookinfo>
 
- <preface id="tutorial-welcome">
-  <title>Welcome</title>
+ <preface id="tutorial-preface">
+  <title>Preface</title>
 
-  <para>
-   Welcome to <productname>PostgreSQL</productname> and the
-   <citetitle>PostgreSQL Tutorial</citetitle>.  The following few
-   chapters are intended to give a simple introduction to
-   <productname>PostgreSQL</productname>, relational database
-   concepts, and the SQL language to those who are new to any one of
-   these aspects.  We only assume some general knowledge about how to
-   use computers.  No particular Unix or programming experience is
-   required.
-  </para>
+<![%single-book;[
+  &intro;
+  &history;
+]]>
 
-  <para>
-   After you have worked through this tutorial you might want to move on to
-   reading &cite-user; to gain a more formal knowledge of the SQL language,
-   or &cite-programmer; for information about developing applications for
-   <productname>PostgreSQL</productname>.
-  </para>
+  <sect1 id="tutorial-preface-thisbook">
+   <title>What's In This Book</title>
 
-  <para>
-   We hope you have a pleasant experience with
-   <productname>PostgreSQL</productname>.
-  </para>
- </preface>
+   <para>
+    Welcome to <productname>PostgreSQL</productname> and the
+    <citetitle>PostgreSQL Tutorial</citetitle>.  The following few
+    chapters are intended to give a simple introduction to
+    <productname>PostgreSQL</productname>, relational database
+    concepts, and the SQL language to those who are new to any one of
+    these aspects.  We only assume some general knowledge about how to
+    use computers.  No particular Unix or programming experience is
+    required.  This book is mainly intended to give you a hands-on
+    experience with important aspects of the PostgreSQL system.  It
+    makes no attempt to be a complete or thorough treatment of the
+    topics it covers.
+   </para>
+
+   <para>
+    After you have worked through this tutorial you might want to move
+    on to reading the &cite-user; to gain a more formal knowledge of
+    the SQL language, or the &cite-programmer; for information about
+    developing applications for <productname>PostgreSQL</productname>.
+    Those who set up and manage their own server should also read the
+    &cite-admin;.
+   </para>
+  </sect1>
 
 <![%single-book;[
-  &intro;
+  &info;
+  &notation;
+  &problems;
 ]]>
+ </preface>
+
   &start;
   &query;
   &advanced;
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index aad8d93100e..508277e840c 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/user-manag.sgml,v 1.16 2002/09/25 21:16:10 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/user-manag.sgml,v 1.17 2002/10/24 17:48:54 petere Exp $
 -->
 
 <chapter id="user-manag">
@@ -16,7 +16,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/user-manag.sgml,v 1.16 2002/09/25 21:16:10
  <para>
   This chapter describes how to create and manage users and introduces
   the privilege system.  More information about the various types of
-  database objects and the effects of privileges can be found in
+  database objects and the effects of privileges can be found in the
   &cite-user;.
  </para>
 
diff --git a/doc/src/sgml/user.sgml b/doc/src/sgml/user.sgml
index f7ed4448add..2b5c05e2d18 100644
--- a/doc/src/sgml/user.sgml
+++ b/doc/src/sgml/user.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.32 2002/09/25 21:16:10 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.33 2002/10/24 17:48:54 petere Exp $
 -->
 
 <book id="user">
@@ -13,8 +13,57 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.32 2002/09/25 21:16:10
   &legal;
  </bookinfo>
 
- &intro;
+ <preface id="user-preface">
+  <title>Preface</title>
 
+  &intro;
+  &history;
+
+  <sect1 id="user-preface-thisbook">
+   <title>What's In This Book</title>
+
+   <para>
+    This book describes the use of the SQL language in PostgreSQL.  We
+    start with describing the general syntax of SQL, then explain how
+    to create the structures to hold data, how to populate the
+    database, and how to query it.  The middle part lists the
+    available data types and functions for use in SQL data commands.
+    The rest of the book treats several aspects that are important for
+    tuning a database for optimial performance.
+   </para>
+
+   <para>
+    The information in this book is arranged so that a novice user can
+    follow it start to end to gain a full understanding of the topics
+    without having to refer forward too many times.  The chapters are
+    intended to be self-contained, so that advanced users can read the
+    chapters individually as they choose.  The information in this
+    book is presented in a narrative fashion in topical units.
+    Readers looking for a complete description of a particular command
+    should look into the &cite-reference;.
+   </para>
+
+   <para>
+    Readers of this book should know how to connect to a PostgreSQL
+    database and issue SQL commands.  Readers that are unfamiliar with
+    these issues are encouraged to read the &cite-tutorial; first.  SQL
+    commands are typically entered using the PostgreSQL interactive
+    terminal <application>psql</application>, but other programs that
+    have similar functionality can be used as well.
+   </para>
+
+   <para>
+    This book covers <productname>PostgreSQL &version;</productname>
+    only.  For information on other versions, please read the
+    documentation that accompanies that release.
+   </para>
+  </sect1>
+
+  &info;
+  &notation;
+  &problems;
+ </preface>
+ 
  &syntax;
  &ddl;
  &dml;
diff --git a/doc/src/sgml/y2k.sgml b/doc/src/sgml/y2k.sgml
deleted file mode 100644
index 60ad62e51ed..00000000000
--- a/doc/src/sgml/y2k.sgml
+++ /dev/null
@@ -1,95 +0,0 @@
-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/y2k.sgml,v 1.14 2002/01/08 20:03:58 momjian Exp $
--->
-
-<sect1 id="y2k">
- <title>Y2K Statement</title>
-
- <note>
-  <title>Author</title>
-
-  <para>
-   Written by Thomas Lockhart
-   (<email>lockhart@fourpalms.org</email>)
-   on 1998-10-22. Updated 2000-03-31.
-  </para>
- </note>
-
- <para>
-  The <productname>PostgreSQL</productname> Global Development Group provides
-  the <productname>PostgreSQL</productname> software code tree as a public service,
-  without warranty and without liability for its behavior or performance.
-  However, at the time of writing:
- </para>
-
- <itemizedlist>
-  <listitem>
-   <para>
-    The author of this statement, a volunteer on the
-    <productname>PostgreSQL</productname>
-    support team since November, 1996, is not aware of 
-    any problems in the <productname>PostgreSQL</productname> code base related
-    to time transitions around Jan 1, 2000 (Y2K).
-   </para>
-  </listitem>
-
-  <listitem>
-   <para>
-    The author of this statement is not aware of any reports of Y2K problems 
-    uncovered in regression testing
-    or in other field use of recent or current versions
-    of <productname>PostgreSQL</productname>. We might have expected
-    to hear about problems if they existed, given the installed base and
-    the active participation of users on the support mailing lists.
-   </para>
-  </listitem>
-
-  <listitem>
-   <para>
-    To the best of the author's knowledge, the
-    assumptions <productname>PostgreSQL</productname>
-    makes about dates specified with a two-digit year
-    are documented in the current <citetitle>User's Guide</citetitle>
-    in the chapter on data types.
-    For two-digit years, the significant transition year is 1970, not 2000;
-    e.g. <literal>70-01-01</literal> is interpreted as 1970-01-01,
-    whereas <literal>69-01-01</literal> is interpreted as 2069-01-01.
-   </para>
-  </listitem>
-
-  <listitem>
-   <para>
-    Any Y2K problems in the underlying OS related to obtaining the
-    <quote>current time</quote> may propagate into apparent Y2K problems in
-    <productname>PostgreSQL</productname>.
-   </para>
-  </listitem>
- </itemizedlist>
-
- <para>
-  Refer to 
-  <ulink url="http://www.gnu.org/software/year2000.html">The GNU Project</ulink>
-  and
-  <ulink url="http://language.perl.com/news/y2k.html">The Perl Institute</ulink>
-  for further discussion of Y2K issues, particularly
-  as it relates to open source, no fee software.
- </para>
-
-</sect1>
-
-<!-- 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:
--->