]> granicus.if.org Git - postgresql/commitdiff
Add introductory sections explaining what each book is about. Remove Y2K
authorPeter Eisentraut <peter_e@gmx.net>
Thu, 24 Oct 2002 17:48:54 +0000 (17:48 +0000)
committerPeter Eisentraut <peter_e@gmx.net>
Thu, 24 Oct 2002 17:48:54 +0000 (17:48 +0000)
statement.

19 files changed:
doc/src/sgml/admin.sgml
doc/src/sgml/advanced.sgml
doc/src/sgml/ddl.sgml
doc/src/sgml/ecpg.sgml
doc/src/sgml/entities.sgml
doc/src/sgml/filelist.sgml
doc/src/sgml/info.sgml
doc/src/sgml/intro.sgml
doc/src/sgml/manage-ag.sgml
doc/src/sgml/notation.sgml
doc/src/sgml/programmer.sgml
doc/src/sgml/query.sgml
doc/src/sgml/ref/ecpg-ref.sgml
doc/src/sgml/start.sgml
doc/src/sgml/syntax.sgml
doc/src/sgml/tutorial.sgml
doc/src/sgml/user-manag.sgml
doc/src/sgml/user.sgml
doc/src/sgml/y2k.sgml [deleted file]

index 59174345063d21644eeaeacd3441e850ef349f2e..f1cb16d9e1045e54a346fb7af1c71e4ec02fcdbc 100644 (file)
@@ -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;
index 2f7e43604d8452b7ce7586d98f9759bce1347f54..1a39a9b8ffa10284a7347dd7f10d389b90777730 100644 (file)
@@ -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>
index 253d163ede4f8550a088053c4d53c1a81c0576c9..7921b4320d06f9fd12be431e7479311519a2a989 100644 (file)
@@ -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>
index 920ea5f1effcdca9079bba5f80beda52ae7d510c..d53c9e54aeb601a9e6e43543cc4ff815879e9d37 100644 (file)
@@ -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>
 
index 14f201fae61c7f08c42387b1eca41709aed1c5cc..66e4092cdb882e34a8c2c9116eddf801fd5c902a 100644 (file)
@@ -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'>">
 
 ]]>
index 5fd2325988f49e88135b2362135544258dd81e3c..7331dcda736825fe3c3d7354368a20dfeec82dba 100644 (file)
@@ -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">
index c3700650eddb590673115018f12ddc4ee471fac4..892292e553853154ffdea3683579b239108d4ac8 100644 (file)
@@ -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>
index 5b98495e93d9f2357da30fcb26cbfa79ee3b7e2e..ba5653f155c945e66b1552e2008b3c4738ff536f 100644 (file)
@@ -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
index e37864f79ee2b488231e2d883b314eb8d5ba2bc4..d761b8f18ac660077eaa65e673a99c65775ebd94 100644 (file)
@@ -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>
index e95735e11e1d9e4cb0deaff5cd046fddf80c44a4..197e5cd913eb6bf564e52fe982e7a2765d0408ec 100644 (file)
@@ -1,16 +1,10 @@
 <!--
-$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>
index 5494ce2788c073610d713318e1ca8212c2767f91..10eebfaeba2dadf6a9691eb7bf6a6f161e3edf13 100644 (file)
@@ -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>
index 230baa276bda157b6f164948075cc6a4f9c9ad01..1ec9fba7226ea5dcb3b2cd1504c12a48eb9480c5 100644 (file)
@@ -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>
 
index 310ef00060df97d2e39ca72a8a6ccc9960bbbc9b..c2c8ec6eed7fc3492e0b8ab5e4e5a703478f316e 100644 (file)
@@ -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>
 
index b7eda72737c6d8f67cac4f07ce82aa84e39cda4f..ca1550bd6e515ab674e9163aaaa3dd6ba3e6ce80 100644 (file)
@@ -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
index 99e7975b2b3b1ec5fe6ab65caf259b8cc08c8920..be1a6e764f7a2a31a464284699b2589e941b5417 100644 (file)
@@ -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>
 
index ed7688de6342a232c0417246b423ac26624fa2af..55d340362e286501514c5c4310cfd9f1bfc07260 100644 (file)
@@ -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;
index aad8d93100e7a910ef641f40b73ca1be3009b344..508277e840ca0093a7f0d4d315d4a84df65a5b78 100644 (file)
@@ -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>
 
index f7ed4448addc3241dabdba7d4b97fc5d5462a16f..2b5c05e2d18d4446d9883b76695f1c5d80a5aed0 100644 (file)
@@ -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 (file)
index 60ad62e..0000000
+++ /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:
--->