From: Peter Eisentraut Date: Thu, 24 Oct 2002 17:48:54 +0000 (+0000) Subject: Add introductory sections explaining what each book is about. Remove Y2K X-Git-Tag: REL9_0_0~16456 X-Git-Url: http://git.osdn.net/view?a=commitdiff_plain;h=266a2805840ef37d12b3cc3fb67c09596c02f658;p=pg-rex%2Fsyncrep.git Add introductory sections explaining what each book is about. Remove Y2K statement. --- diff --git a/doc/src/sgml/admin.sgml b/doc/src/sgml/admin.sgml index 5917434506..f1cb16d9e1 100644 --- a/doc/src/sgml/admin.sgml +++ b/doc/src/sgml/admin.sgml @@ -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 + + + + 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. + + + + + &installation; &installw; diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml index 2f7e43604d..1a39a9b8ff 100644 --- a/doc/src/sgml/advanced.sgml +++ b/doc/src/sgml/advanced.sgml @@ -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;. diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index 253d163ede..7921b4320d 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -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;. diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml index 920ea5f1ef..d53c9e54ae 100644 --- a/doc/src/sgml/ecpg.sgml +++ b/doc/src/sgml/ecpg.sgml @@ -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;. diff --git a/doc/src/sgml/entities.sgml b/doc/src/sgml/entities.sgml index 14f201fae6..66e4092cdb 100644 --- a/doc/src/sgml/entities.sgml +++ b/doc/src/sgml/entities.sgml @@ -1,20 +1,20 @@ PostgreSQL Administrator's Guide"> -PostgreSQL Developer's Guide"> -PostgreSQL Programmer's Guide"> -PostgreSQL Reference Manual"> -PostgreSQL Tutorial"> -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"> ]]> "> -"> -"> -"> -"> -"> +"> +"> +"> +"> +"> +"> ]]> diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 5fd2325988..7331dcda73 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -1,4 +1,4 @@ - + @@ -6,7 +6,6 @@ - diff --git a/doc/src/sgml/info.sgml b/doc/src/sgml/info.sgml index c3700650ed..892292e553 100644 --- a/doc/src/sgml/info.sgml +++ b/doc/src/sgml/info.sgml @@ -1,71 +1,76 @@ - Documentation Resources + Overview of 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. diff --git a/doc/src/sgml/intro.sgml b/doc/src/sgml/intro.sgml index 5b98495e93..ba5653f155 100644 --- a/doc/src/sgml/intro.sgml +++ b/doc/src/sgml/intro.sgml @@ -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;. diff --git a/doc/src/sgml/notation.sgml b/doc/src/sgml/notation.sgml index e95735e11e..197e5cd913 100644 --- a/doc/src/sgml/notation.sgml +++ b/doc/src/sgml/notation.sgml @@ -1,17 +1,11 @@ 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 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 5494ce2788..10eebfaeba 100644 --- a/doc/src/sgml/programmer.sgml +++ b/doc/src/sgml/programmer.sgml @@ -1,5 +1,5 @@ @@ -12,9 +12,60 @@ PostgreSQL Programmer's Guide. &legal; - + Preface + + + + + 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. + + + + + Client Interfaces diff --git a/doc/src/sgml/query.sgml b/doc/src/sgml/query.sgml index 230baa276b..1ec9fba722 100644 --- a/doc/src/sgml/query.sgml +++ b/doc/src/sgml/query.sgml @@ -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;. diff --git a/doc/src/sgml/ref/ecpg-ref.sgml b/doc/src/sgml/ref/ecpg-ref.sgml index 310ef00060..c2c8ec6eed 100644 --- a/doc/src/sgml/ref/ecpg-ref.sgml +++ b/doc/src/sgml/ref/ecpg-ref.sgml @@ -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. diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml index b7eda72737..ca1550bd6e 100644 --- a/doc/src/sgml/start.sgml +++ b/doc/src/sgml/start.sgml @@ -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 diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index 99e7975b2b..be1a6e764f 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -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;. diff --git a/doc/src/sgml/tutorial.sgml b/doc/src/sgml/tutorial.sgml index ed7688de63..55d340362e 100644 --- a/doc/src/sgml/tutorial.sgml +++ b/doc/src/sgml/tutorial.sgml @@ -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 + + Preface - - 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. - + - - 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;. + + + + &start; &query; &advanced; diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml index aad8d93100..508277e840 100644 --- a/doc/src/sgml/user-manag.sgml +++ b/doc/src/sgml/user-manag.sgml @@ -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;. diff --git a/doc/src/sgml/user.sgml b/doc/src/sgml/user.sgml index f7ed4448ad..2b5c05e2d1 100644 --- a/doc/src/sgml/user.sgml +++ b/doc/src/sgml/user.sgml @@ -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 index 60ad62e51e..0000000000 --- a/doc/src/sgml/y2k.sgml +++ /dev/null @@ -1,95 +0,0 @@ - - - - Y2K Statement - - - Author - - - Written by Thomas Lockhart - (lockhart@fourpalms.org) - 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. - - - - -