Add introductory sections explaining what each book is about. Remove Y2K
authorPeter Eisentraut
Thu, 24 Oct 2002 17:48:54 +0000 (17:48 +0000)
committerPeter Eisentraut
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 @@
 
 
 
@@ -13,14 +13,60 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.39 2002/10/16 22:06:33
   &legal;
  
 
-
+  Preface
+
 
   &intro;
+  &history;
+]]>
+
+  
+   What's In This Book
+
+   
+    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.
+   
+
+   
+    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;.
+   
+
+   
+    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.
+   
+
+   
+    This book covers PostgreSQL &version;
+    only.  For information on other versions, please read the
+    documentation that accompanies that release.
+   
+  
+
+
+  &info;
+  ¬ation;
+  &problems;
 ]]>
 
   &installation;
   &installw;
index 2f7e43604d8452b7ce7586d98f9759bce1347f54..1a39a9b8ffa10284a7347dd7f10d389b90777730 100644 (file)
@@ -1,5 +1,5 @@
 
 
  
@@ -130,7 +130,7 @@ ERROR:  <unnamed> referential integrity violation - key referenced from we
    
     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
     PostgreSQL has many features not
     touched upon in this tutorial introduction, which has been
     oriented toward newer users of SQL.  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;.
    
 
    
index 253d163ede4f8550a088053c4d53c1a81c0576c9..7921b4320d06f9fd12be431e7479311519a2a989 100644 (file)
@@ -1,4 +1,4 @@
-
+
 
 
  Data Definition
@@ -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;.
  
 
  
@@ -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 CREATE TABLE entry
-    in &cite-reference;.
+    in the &cite-reference;.
    
   
  
index 920ea5f1effcdca9079bba5f80beda52ae7d510c..d53c9e54aeb601a9e6e43543cc4ff815879e9d37 100644 (file)
@@ -1,5 +1,5 @@
 
 
 
@@ -798,7 +798,7 @@ ECPG = ecpg
 
   
    The complete syntax of the ecpg command is
-   detailed in &cite-reference;.
+   detailed in the &cite-reference;.
   
  
 
index 14f201fae61c7f08c42387b1eca41709aed1c5cc..66e4092cdb882e34a8c2c9116eddf801fd5c902a 100644 (file)
@@ -1,20 +1,20 @@
 
 
-the PostgreSQL Administrator's Guide">
-the PostgreSQL Developer's Guide">
-the PostgreSQL Programmer's Guide">
-the PostgreSQL Reference Manual">
-the PostgreSQL Tutorial">
-the PostgreSQL User's Guide">
+PostgreSQL Administrator's Guide">
+PostgreSQL Developer's Guide">
+PostgreSQL Programmer's Guide">
+PostgreSQL Reference Manual">
+PostgreSQL Tutorial">
+PostgreSQL User's Guide">
 
 ]]>
 
 
-the ">
-the ">
-the ">
-the ">
-the ">
-the ">
+">
+">
+">
+">
+">
+">
 
 ]]>
index 5fd2325988f49e88135b2362135544258dd81e3c..7331dcda736825fe3c3d7354368a20dfeec82dba 100644 (file)
@@ -1,4 +1,4 @@
-
+
 
 
 
@@ -6,7 +6,6 @@
 
 
 
-
 
 
 
index c3700650eddb590673115018f12ddc4ee471fac4..892292e553853154ffdea3683579b239108d4ac8 100644 (file)
@@ -1,71 +1,76 @@
 
 
 
Documentation Resources
<span class="marked">Overview of </span>Documentation Resources
 
  
-  This manual set is organized into several parts:
+  The PostgreSQL documentation is organized into several books:
 
   
    
-    Tutorial
+    &cite-tutorial;
     
      
-      An informal introduction for new users
+      An informal introduction for new users.
      
     
    
 
    
-    User's Guide
+    &cite-user;
     
      
-      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.
      
     
    
 
    
-    Programmer's Guide
+    &cite-admin;
     
      
-      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.
      
     
    
 
    
-    Administrator's Guide
+    &cite-programmer;
     
      
-      Installation and server management information
+      Advanced information for application programmers. Topics include
+      type and function extensibility, library interfaces, and
+      application design issues.
      
     
    
 
    
-    Reference Manual
+    &cite-reference;
     
      
-      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.
      
     
    
 
    
-    Developer's Guide
+    &cite-developer;
     
      
-      Information for PostgreSQL developers.
-      This is intended for those who are contributing to the
-      PostgreSQL project;
-      application development information appears in the 
-      Programmer's Guide.
+      Information for PostgreSQL
+      developers.  This is intended for those who are contributing to
+      the PostgreSQL project; application
+      development information appears in the Programmer's
+      Guide.
      
     
    
@@ -81,8 +86,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.15 2001/11/28 20:49:10 petere
     man pages
     
      
-      The Reference Manual's pages in the traditional
-      Unix man format.
+      The Reference Manual's pages in the
+      traditional Unix man format.  There is no difference in content.
      
     
    
index 5b98495e93d9f2357da30fcb26cbfa79ee3b7e2e..ba5653f155c945e66b1552e2008b3c4738ff536f 100644 (file)
@@ -1,10 +1,7 @@
 
 
-  Preface
-
   
     What is <productname>PostgreSQL</productname>?
 
@@ -95,14 +92,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.19 2002/01/07 02:29:12 peter
 
   
 
-   &history;
-   &info;
-   ¬ation;
-   &problems;
-   &y2k;
-
-
 
 
 
@@ -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;.
   
 
   
index e95735e11e1d9e4cb0deaff5cd046fddf80c44a4..197e5cd913eb6bf564e52fe982e7a2765d0408ec 100644 (file)
@@ -1,16 +1,10 @@
 
 
 
  Terminology and Notation
 
-  The terms PostgreSQL and Postgres will be
-  used interchangeably to refer to the software that accompanies this
-  documentation.
-
  
   An administrator is generally a person who is
   in charge of installing and running the server.  A user
index 5494ce2788c073610d713318e1ca8212c2767f91..10eebfaeba2dadf6a9691eb7bf6a6f161e3edf13 100644 (file)
@@ -1,5 +1,5 @@
 
@@ -12,9 +12,60 @@ PostgreSQL Programmer's Guide.
   &legal;
  
 
-
+  Preface
+
+
   &intro;
+  &history;
+]]>
+
+  
+   What's In This Book
+
+   
+    This book is for PostgreSQL application programmers.  It is divided into three parts.
+   
+
+   
+    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.
+   
+
+   
+    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.
+   
+
+   
+    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.
+   
+
+   
+    This book covers PostgreSQL &version;
+    only.  For information on other versions, please read the
+    documentation that accompanies that release.
+   
+  
+
+
+  &info;
+  ¬ation;
+  &problems;
 ]]>
 
  
   Client Interfaces
index 230baa276bda157b6f164948075cc6a4f9c9ad01..1ec9fba7226ea5dcb3b2cd1504c12a48eb9480c5 100644 (file)
@@ -1,5 +1,5 @@
 
 
  
@@ -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
-    COPY command in &cite-reference;.
+    COPY command in the &cite-reference;.
    
   
 
index 310ef00060df97d2e39ca72a8a6ccc9960bbbc9b..c2c8ec6eed7fc3492e0b8ab5e4e5a703478f316e 100644 (file)
@@ -1,5 +1,5 @@
 
 
@@ -49,7 +49,7 @@ PostgreSQL documentation
 
   
    This reference page does not describe the embedded SQL language.
-   See &cite-programmer; for that.
+   See the &cite-programmer; for that.
   
  
 
index b7eda72737c6d8f67cac4f07ce82aa84e39cda4f..ca1550bd6e515ab674e9163aaaa3dd6ba3e6ce80 100644 (file)
@@ -1,5 +1,5 @@
 
 
  
@@ -31,7 +31,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.25 2002/10/20 05:05:46 tgl E
 
    
     If you are installing PostgreSQL
-    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
       
        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;.
       
      
     
@@ -391,7 +391,7 @@ mydb=#
     command shell. (For more internal commands, type
     \? at the psql prompt.)  The
     full capabilities of psql are documented in
-    &cite-reference;.  If PostgreSQL is
+    the &cite-reference;.  If PostgreSQL is
     installed correctly you can also type man psql
     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 @@
 
 
 
@@ -73,7 +73,7 @@ INSERT INTO MY_TABLE VALUES (3, 'hi there');
    a SET token to appear in a certain position, and
    this particular variation of INSERT also
    requires a VALUES 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;.
   
 
index ed7688de6342a232c0417246b423ac26624fa2af..55d340362e286501514c5c4310cfd9f1bfc07260 100644 (file)
@@ -1,5 +1,5 @@
 
 
 
@@ -10,36 +10,48 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/tutorial.sgml,v 1.16 2002/10/20 05:05
   &legal;
  
 
welcome">
-  <span class="marked">Welcom</span>e
preface">
+  <span class="marked">Prefac</span>e
 
-  
-   Welcome to PostgreSQL and the
-   PostgreSQL Tutorial.  The following few
-   chapters are intended to give a simple introduction to
-   PostgreSQL, 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.
-  
+
+  &intro;
+  &history;
+]]>
 
-  
-   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
-   PostgreSQL.
-  
+  
+   What's In This Book
 
-  
-   We hope you have a pleasant experience with
-   PostgreSQL.
-  
+   
+    Welcome to PostgreSQL and the
+    PostgreSQL Tutorial.  The following few
+    chapters are intended to give a simple introduction to
+    PostgreSQL, 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.
+   
+
+   
+    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 PostgreSQL.
+    Those who set up and manage their own server should also read the
+    &cite-admin;.
+   
+  
 
 
-  &intro;
+  &info;
+  ¬ation;
+  &problems;
 ]]>
+
   &start;
   &query;
   &advanced;
index aad8d93100e7a910ef641f40b73ca1be3009b344..508277e840ca0093a7f0d4d315d4a84df65a5b78 100644 (file)
@@ -1,5 +1,5 @@
 
 
 
@@ -16,7 +16,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/user-manag.sgml,v 1.16 2002/09/25 21:16:10
  
   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;.
  
 
index f7ed4448addc3241dabdba7d4b97fc5d5462a16f..2b5c05e2d18d4446d9883b76695f1c5d80a5aed0 100644 (file)
@@ -1,5 +1,5 @@
 
 
 
@@ -13,8 +13,57 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.32 2002/09/25 21:16:10
   &legal;
  
 
- &intro;
+  Preface
 
+  &intro;
+  &history;
+
+  
+   What's In This Book
+
+   
+    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.
+   
+
+   
+    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;.
+   
+
+   
+    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 psql, but other programs that
+    have similar functionality can be used as well.
+   
+
+   
+    This book covers PostgreSQL &version;
+    only.  For information on other versions, please read the
+    documentation that accompanies that release.
+   
+  
+
+  &info;
+  ¬ation;
+  &problems;
  &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 @@
-
-
-
Y2K Statement
-
-  Author
-
-  
-   Written by Thomas Lockhart
-   on 1998-10-22. Updated 2000-03-31.
-  
-
-  The PostgreSQL Global Development Group provides
-  the PostgreSQL software code tree as a public service,
-  without warranty and without liability for its behavior or performance.
-  However, at the time of writing:
-
-  
-   
-    The author of this statement, a volunteer on the
-    PostgreSQL
-    support team since November, 1996, is not aware of 
-    any problems in the PostgreSQL code base related
-    to time transitions around Jan 1, 2000 (Y2K).
-   
-  
-
-  
-   
-    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 PostgreSQL. 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.
-   
-  
-
-  
-   
-    To the best of the author's knowledge, the
-    assumptions PostgreSQL
-    makes about dates specified with a two-digit year
-    are documented in the current User's Guide
-    in the chapter on data types.
-    For two-digit years, the significant transition year is 1970, not 2000;
-    e.g. 70-01-01 is interpreted as 1970-01-01,
-    whereas 69-01-01 is interpreted as 2069-01-01.
-   
-  
-
-  
-   
-    Any Y2K problems in the underlying OS related to obtaining the
-    current time may propagate into apparent Y2K problems in
-    PostgreSQL.
-   
-  
-
-  Refer to 
-  The GNU Project
-  and
-  The Perl Institute
-  for further discussion of Y2K issues, particularly
-  as it relates to open source, no fee software.
-
-
-
-