mirror/postgresql
2
0
Fork 0
mirror of https://git.postgresql.org/git/postgresql.git synced 2025-02-17 19:30:00 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update, polish, consistencify preface/intro sections.

Browse Source
This commit is contained in:
Peter Eisentraut 2001-02-03 19:03:27 +00:00
parent 80dbae395d
commit 7c164dca0b
19 changed files with 364 additions and 625 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/src/sgml/Makefile
View File

@ -8,7 +8,7 @@
#
#
# IDENTIFICATION
# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.28 2001/01/06 16:54:16 petere Exp $
# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.29 2001/02/03 19:03:26 petere Exp $
#
#----------------------------------------------------------------------------
@ -85,7 +85,7 @@ man: $(ALLSGML)
## HTML
##
JADE.html = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) -d $(HDSL) -V %use-id-as-filename% -t sgml
JADE.html = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) -d $(HDSL) -V %use-id-as-filename% -V %generate-legalnotice-link% -t sgml
postgres.html: postgres.sgml $(ALLSGML)
@rm -f *.htm

37
doc/src/sgml/about.sgml
View File

@ -1,37 +0,0 @@
<sect1 id="about">
<title>About This Release</title>
<para>
<productname>PostgreSQL</productname> is available without cost. This manual
describes version &version; of <productname>PostgreSQL</productname>.
</para>
<para>
We will use <productname>Postgres</productname>
to mean the version distributed as <productname>PostgreSQL</productname>.
</para>
<para>
Check the Administrator's Guide for a list of currently supported machines.
In general,
<productname>Postgres</productname> is portable to any Unix/Posix-compatible system
with full libc library support.
</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:
-->

41
doc/src/sgml/admin.sgml
View File

@ -1,55 +1,27 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.31 2001/01/24 23:15:19 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.32 2001/02/03 19:03:26 petere Exp $
-->
<book id="admin">
<!-- Title information -->
<title><![%single-book;[PostgreSQL &version;]]> Administrator's Guide</title>
<title>PostgreSQL &version; Administrator's Guide</title>
<bookinfo>
<corpauthor>The PostgreSQL Global Development Group</corpauthor>
<editor>
<firstname>Thomas</firstname>
<surname>Lockhart</surname>
<affiliation>
<orgname>Caltech/JPL</orgname>
</affiliation>
</editor>
<legalnotice>
<para>
<productname>PostgreSQL</productname> is Copyright &copy; 1996-2001
by PostgreSQL Global Development Group
</para>
</legalnotice>
&legal;
</bookinfo>
<preface id="ag-preface">
<title>Summary</title>
<para>
<productname>Postgres</productname>,
developed originally in the UC Berkeley Computer Science Department,
pioneered many of the object-relational concepts
now becoming available in some commercial databases.
It provides SQL92/SQL99 language support,
transaction integrity, and type extensibility.
<productname>PostgreSQL</productname> is an open-source descendant
of this original Berkeley code.
</para>
</preface>
<!--
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.
-->
<![%single-book;[
&intro-ag;
&intro;
]]>
&installation;
&installw;
&runtime;
@ -62,6 +34,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.31 2001/01/24 23:15:19
&recovery;
&regress;
&release;
<![%single-book;[
&biblio;
]]>

9
doc/src/sgml/developer.sgml
View File

@ -1,18 +1,19 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/developer.sgml,v 1.3 2000/11/29 20:15:59 petere Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/developer.sgml,v 1.4 2001/02/03 19:03:26 petere Exp $ -->
<!-- PostgreSQL Developer's Guide -->
<book id="developer">
<title><![%single-book;[PostgreSQL &version;]]> Developer's Guide</title>
<title>PostgreSQL &version; Developer's Guide</title>
<bookinfo>
<corpauthor>The PostgreSQL Global Development Group</corpauthor>
&legal;
<abstract>
<simpara>
This document contains assorted information that can be of use to
<productname>PostgreSQL</> developers.
</simpara>
</abstract>
<corpauthor>The PostgreSQL Global Development Group</corpauthor>
</bookinfo>
&sources;

5
doc/src/sgml/filelist.sgml
View File

@ -1,6 +1,5 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.6 2001/01/24 23:15:19 petere Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.7 2001/02/03 19:03:26 petere Exp $ -->
<!entity about SYSTEM "about.sgml">
<!entity history SYSTEM "history.sgml">
<!entity info SYSTEM "info.sgml">
<!entity legal SYSTEM "legal.sgml">
@ -45,7 +44,6 @@
<!entity backup SYSTEM "backup.sgml">
<!entity charset SYSTEM "charset.sgml">
<!entity client-auth SYSTEM "client-auth.sgml">
<!entity intro-ag SYSTEM "intro-ag.sgml">
<!entity installation SYSTEM "installation.sgml">
<!entity installw SYSTEM "install-win32.sgml">
<!entity manage-ag SYSTEM "manage-ag.sgml">
@ -63,7 +61,6 @@
<!entity extend SYSTEM "extend.sgml">
<!entity func-ref SYSTEM "func-ref.sgml">
<!entity gist SYSTEM "gist.sgml">
<!entity intro-pg SYSTEM "intro-pg.sgml">
<!entity indexcost SYSTEM "indexcost.sgml">
<!entity jdbc SYSTEM "jdbc.sgml">
<!entity libpgeasy SYSTEM "libpgeasy.sgml">

10
doc/src/sgml/history.sgml
View File

@ -1,22 +1,22 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.12 2000/12/22 21:51:57 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.13 2001/02/03 19:03:26 petere Exp $
-->
<sect1 id="history">
<title>A Short History of <productname>Postgres</productname></title>
<para>
The Object-Relational Database Management System now known as
The object-relational database management system now known as
<productname>PostgreSQL</productname> (and briefly called
<productname>Postgres95</productname>) is derived from the
<productname>Postgres</productname> package written at Berkeley.
With over a decade of
<productname>Postgres</productname> package written at the University of
California at Berkeley. With over a decade of
development behind it, <productname>PostgreSQL</productname>
is the most advanced open-source database available anywhere,
offering multi-version concurrency control, supporting almost
all SQL constructs (including subselects, transactions, and
user-defined types and functions), and having a wide range of
language bindings available (including C, C++, Java, perl, tcl, and python).
language bindings available (including C, C++, Java, Perl, Tcl, and Python).
</para>
<sect2>

296
doc/src/sgml/info.sgml
View File

@ -1,165 +1,163 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.10 2000/12/22 21:51:57 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.11 2001/02/03 19:03:26 petere Exp $
-->
<sect1 id="resources">
<title>Resources</title>
<title>Documentation Resources</title>
<para>
This manual set is organized into several parts:
<variablelist>
<varlistentry>
<term>Tutorial</term>
<listitem>
<para>
An introduction for new users. Does not cover advanced features.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>User's Guide</term>
<listitem>
<para>
Documents the SQL query language environment, including data types
and functions.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Programmer's Guide</term>
<listitem>
<para>
Advanced information for application programmers. Topics include
type and function extensibility, library interfaces,
and application design issues.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Administrator's Guide</term>
<listitem>
<para>
Installation and server management information
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Reference Manual</term>
<listitem>
<para>
Reference pages for SQL command syntax and client and server programs
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Developer's Guide</term>
<listitem>
<para>
Information for <productname>Postgres</productname> developers.
This is intended for those who are contributing to the
<productname>Postgres</productname> project;
application development information should appear in the
<citetitle>Programmer's Guide</citetitle>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<variablelist>
<varlistentry>
<term>Tutorial</term>
<listitem>
<para>
An introduction for new users. Does not cover advanced features.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>User's Guide</term>
<listitem>
<para>
General information for users, including available commands and data types.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Programmer's Guide</term>
<listitem>
<para>
Advanced information for application programmers. Topics include
type and function extensibility, library interfaces,
and application design issues.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Administrator's Guide</term>
<listitem>
<para>
Installation and management information. List of supported machines.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Developer's Guide</term>
<listitem>
<para>
Information for <productname>Postgres</productname> developers.
This is intended for those who are contributing to the
<productname>Postgres</productname> project;
application development information should appear in the
<citetitle>Programmer's Guide</citetitle>.
Currently included in the <citetitle>Programmer's Guide</citetitle>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Reference Manual</term>
<listitem>
<para>
Detailed reference information on command syntax.
Currently included in the <citetitle>User's Guide</citetitle>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
In addition to this manual set, there are other resources to help you with
<productname>Postgres</productname> installation and use:
<variablelist>
<varlistentry>
<term>man pages</term>
<listitem>
<para>
The <citetitle>Reference Manual</citetitle>'s pages in the traditional
Unix man format.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FAQs</term>
<listitem>
<para>
Frequently Asked Questions (FAQ) lists document both general issues
and some platform-specific issues.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>READMEs</term>
<listitem>
<para>
README files are available for some contributed packages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Web Site</term>
<listitem>
<para>
The <ulink
url="http://www.postgresql.org"><productname>PostgreSQL</productname>
web site</ulink> carries details on the latest release, upcoming
features, and other information to make your work or play with
<productname>PostgreSQL</productname> more productive.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Mailing Lists</term>
<listitem>
<para>
The <email>pgsql-general@postgresql.org</email> (<ulink
url="http://www.postgresql.org/mhonarc/pgsql-general/">archive</ulink>)
mailing list is a good place to have user questions answered.
Other mailing lists are available; consult the <ulink
url="http://www.postgresql.org/users-lounge/">User's
Lounge</ulink> section of the PostgreSQL web site for details.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Yourself!</term>
<listitem>
<para>
<productname>PostgreSQL</productname> is an open source effort.
As such, it depends on the user community for ongoing support.
As you begin to use <productname>PostgreSQL</productname>, you
will rely on others for help, either through the documentation
or through the mailing lists. Consider contributing your
knowledge back. If you learn something which is not in the
documentation, write it up and contribute it. If you add
features to the code, contribute it.
</para>
<para>
Even those without a lot of experience can provide corrections
and minor changes in the documentation, and that is a good way
to start. The <email>pgsql-docs@postgresql.org</email> (<ulink
url="http://www.postgresql.org/mhonarc/pgsql-docs/">archive</ulink>)
mailing list is the place to get going.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<variablelist>
<varlistentry>
<term>man pages</term>
<listitem>
<para>
The man pages have general information on command syntax.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FAQs</term>
<listitem>
<para>
The Frequently Asked Questions (FAQ) documents address both general issues
and some platform-specific issues.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>READMEs</term>
<listitem>
<para>
README files are available for some contributed packages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Web Site</term>
<listitem>
<para>
The
<ulink url="http://www.postgresql.org"><productname>Postgres</productname></ulink>
web site might have some information not appearing in the distribution.
There is a <productname>mhonarc</productname> catalog of mailing list traffic
which is a rich resource for many topics.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Mailing Lists</term>
<listitem>
<para>
The
<email>pgsql-general@postgresql.org</email>
(<ulink url="http://www.postgresql.org/mhonarc/pgsql-general/">archive</ulink>)
mailing list is a good place to have user questions answered.
Other mailing lists are available; consult the Info Central section of the
PostgreSQL web site for details.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Yourself!</term>
<listitem>
<para>
<productname>Postgres</productname> is an open source product.
As such, it depends on the user community for ongoing support.
As you begin to use <productname>Postgres</productname>,
you will rely on others for help, either through the
documentation or through the mailing lists.
Consider contributing your knowledge back. If you learn something
which is not in the documentation, write it up and contribute it.
If you add features to the code, contribute it.
</para>
<para>
Even those without a lot of experience can provide corrections and
minor changes in the documentation, and that is a good way to start.
The
<email>pgsql-docs@postgresql.org</email>
(<ulink url="http://www.postgresql.org/mhonarc/pgsql-docs/">archive</ulink>)
mailing list is the place to get going.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<!-- Keep this comment at the end of the file

47
doc/src/sgml/intro-ag.sgml
View File

@ -1,47 +0,0 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/intro-ag.sgml,v 1.5 2000/03/31 03:27:40 thomas Exp $
-->
<chapter id="intro-ag">
<title>Introduction</title>
<para>
This document is the Administrator's Manual for the
<ulink url="http://postgresql.org/"><productname>PostgreSQL</productname></ulink>
database management system, originally developed at the University
of California at Berkeley.
<productname>PostgreSQL</productname> is based on
<ulink url="http://s2k-ftp.CS.Berkeley.EDU:8000/postgres/postgres.html">
<productname>Postgres release 4.2</productname></ulink>.
The <productname>Postgres</productname> project,
led by Professor Michael Stonebraker, was sponsored by the
Defense Advanced Research Projects Agency (<acronym>DARPA</acronym>), the
Army Research Office (<acronym>ARO</acronym>), the National Science
Foundation (<acronym>NSF</acronym>), and ESL, Inc.
</para>
&info;
&notation;
&problems;
&y2k;
&legal;
</chapter>
<!-- 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:
-->

67
doc/src/sgml/intro-pg.sgml
View File

@ -1,67 +0,0 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/intro-pg.sgml,v 1.8 2000/03/31 03:27:40 thomas Exp $
-->
<chapter id="intro-pg">
<title>Introduction</title>
<para>
This document is the programmer's manual for the
<ulink url="http://postgresql.org/"><productname>PostgreSQL</productname></ulink>
database management system, originally developed at the University
of California at Berkeley.
<productname>PostgreSQL</productname> is based on
<ulink url="http://s2k-ftp.CS.Berkeley.EDU:8000/postgres/postgres.html">
<productname>Postgres release 4.2</productname></ulink>.
The <productname>Postgres</productname> project,
led by Professor Michael Stonebraker, has been sponsored by the
Defense Advanced Research Projects Agency (<acronym>DARPA</acronym>), the
Army Research Office (<acronym>ARO</acronym>), the National Science
Foundation (<acronym>NSF</acronym>), and ESL, Inc.
</para>
<para>
The first part of this manual
explains the <productname>Postgres</productname>
approach to extensibility and describe how
users can extend <productname>Postgres</productname>
by adding user-defined types,
operators, aggregates, and both query language and programming
language functions.
After a discussion of the <productname>Postgres</productname>
rule system, we discuss
the trigger and SPI interfaces.
The manual concludes with a detailed description of
the programming interfaces and
support libraries for various languages.
</para>
<para>
We assume proficiency with Unix and C programming.
</para>
&info;
&notation;
&problems;
&y2k;
&legal;
</chapter>
<!-- 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:
-->

63
doc/src/sgml/intro.sgml
View File

@ -1,33 +1,39 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.13 2001/01/13 23:58:55 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.14 2001/02/03 19:03:27 petere Exp $
-->
<chapter id="intro">
<title>Introduction</title>
<para>
This document is the user manual for the
<ulink url="http://postgresql.org/"><productname>PostgreSQL</productname></ulink>
database management system, originally developed at the University
of California at Berkeley.
<productname>PostgreSQL</productname> is based on
<ulink url="http://s2k-ftp.CS.Berkeley.EDU:8000/postgres/postgres.html">
<productname>Postgres release 4.2</productname></ulink>.
The <productname>Postgres</productname> project,
led by Professor Michael Stonebraker, was sponsored by the
Defense Advanced Research Projects Agency
(<acronym>DARPA</acronym>), the
Army Research Office (<acronym>ARO</acronym>), the National Science
Foundation (<acronym>NSF</acronym>), and ESL, Inc.
</para>
<preface id="preface">
<title>Preface</title>
<sect1 id="intro-whatis">
<title> What is <productname>Postgres</productname>?</title>
<title> What is <productname>PostgreSQL</productname>?</title>
<para>
<productname>PostgreSQL</productname> is an object-relational
database management system (<acronym>ORDBMS</acronym>) based on
<ulink url="http://s2k-ftp.CS.Berkeley.EDU:8000/postgres/postgres.html">
<productname>POSTGRES, Version 4.2</productname></ulink>,
developed at the University of California at Berkeley Computer
Science Department. The <productname>POSTGRES</productname>
project, led by Professor Michael Stonebraker, was sponsored by
the Defense Advanced Research Projects Agency
(<acronym>DARPA</acronym>), the Army Research Office
(<acronym>ARO</acronym>), the National Science Foundation
(<acronym>NSF</acronym>), and ESL, Inc.
</para>
<para>
<productname>PostgreSQL</productname> is an open-source descendant of
this original Berkeley code. It provides SQL92/SQL99 language support
and other modern features.
</para>
<para>
<productname>POSTGRES</productname> pioneered many of the
object-relational concepts now becoming available in some commercial
databases.
Traditional relational database management systems
(DBMSs) support a data model consisting of a collection
(<acronym>RDBMS</acronym>) support a data model consisting of a collection
of named relations, containing attributes of a specific
type. In current commercial systems, possible types
include floating point numbers, integers, character
@ -35,18 +41,17 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.13 2001/01/13 23:58:55 peter
that this model is inadequate for future data
processing applications.
The relational model successfully replaced previous
models in part because of its "Spartan simplicity".
models in part because of its <quote>Spartan simplicity</quote>.
However, as mentioned, this simplicity often makes the
implementation of certain applications very difficult.
<productname>Postgres</productname> offers substantial additional
power by incorporating the following four additional
basic concepts in such a way that users can easily
power by incorporating the following additional
concepts in such a way that users can easily
extend the system:
<simplelist>
<member>tables</member>
<member>inheritance</member>
<member>types</member>
<member>data types</member>
<member>functions</member>
</simplelist>
</para>
@ -78,14 +83,12 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.13 2001/01/13 23:58:55 peter
</sect1>
&history;
&about;
&info;
&notation;
&problems;
&y2k;
&legal;
</chapter>
</preface>
<!-- Keep this comment at the end of the file
Local variables:

75
doc/src/sgml/legal.sgml
View File

@ -1,43 +1,74 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/legal.sgml,v 1.9 2001/01/24 19:42:46 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/legal.sgml,v 1.10 2001/02/03 19:03:27 petere Exp $
-->
<sect1 id="copyright">
<title>Copyrights and Trademarks</title>
<copyright>
<year>1996-2001</year>
<holder>PostgreSQL Global Development Group</holder>
</copyright>
<legalnotice>
<title>Legal Notice</title>
<para>
<productname>PostgreSQL</productname> is Copyright &copy; 1996-2001
by PostgreSQL Global Development Group
and is distributed under the terms of the Berkeley license.
by the PostgreSQL Global Development Group and is distributed under
the terms of the license of the University of California below.
</para>
<para>
<productname>Postgres95</productname> is Copyright &copy; 1994-5
by the Regents of the University of California.
Permission to use, copy, modify, and distribute this software and its documentation
for any purpose, without fee, and without a written agreement is hereby granted,
provided that the above copyright notice and this paragraph and the following two
paragraphs appear in all copies.
</para>
<para>
In no event shall the University of California be liable to
any party for direct, indirect, special, incidental, or consequential
damages, including lost profits, arising out of the use of this
software and its documentation, even if the University of California
has been advised of the possibility of such damage.
Permission to use, copy, modify, and distribute this software and
its documentation for any purpose, without fee, and without a
written agreement is hereby granted, provided that the above
copyright notice and this paragraph and the following two paragraphs
appear in all copies.
</para>
<para>
The University of California specifically disclaims any
warranties, including, but not limited to, the implied warranties
of merchantability and fitness for a particular purpose.
The software provided hereunder is on an "as-is" basis, and
the University of California has no obligations to provide
maintainance, support, updates, enhancements, or modifications.
IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY
PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS
SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA
HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</para>
<para>
THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
PROVIDED HEREUNDER IS ON AN "AS-IS" BASIS, AND THE UNIVERSITY OF
CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTAINANCE, SUPPORT,
UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
</para>
<!--
How to keep track of all the trademarks? I'll try the strategy used at
www.qnx.com - thomas
--
--
There is no legal requirement to make trademark acknowledgements in
references to third party products that happen to have trademarked
names.
The exception would be if PostgreSQL were to license a particular
trademark and the trademark holder makes this requirement (as in the
case of UNIX and Java).
What is not allowed, however, is to use a trademark name in a way that
could lead people to believe that they label PostgreSQL products.
E.g., "the PostgreSQL UNIX database system" would probably be illegal,
whereas "PostgreSQL, which runs on many UNIX computer systems" is
fine. This is independent of whether a trademark acknowledgement is
made.
- petere
<para>
<acronym>Unix</acronym> is a trademark of X/Open, Ltd. Sun4, SPARC, SunOS
and Solaris are trademarks of Sun Microsystems, Inc. DEC,
@ -48,10 +79,12 @@ www.qnx.com - thomas
</para>
-->
<!--
<para>
All trademarks are the property of their respective owners.
</para>
</sect1>
-->
</legalnotice>
<!-- Keep this comment at the end of the file
Local variables:

104
doc/src/sgml/notation.sgml
View File

@ -1,71 +1,30 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.13 2000/12/22 21:51:58 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.14 2001/02/03 19:03:27 petere Exp $
-->
<sect1 id="terminology">
<title>Terminology</title>
<para>
The
<Productname>Postgres</Productname> <firstterm>superuser</firstterm>
is the user named <replaceable>postgres</replaceable>
who owns the <Productname>Postgres</Productname>
binaries and database files. As the database superuser, all
protection mechanisms may be bypassed and any data accessed
arbitrarily.
In addition, the <Productname>Postgres</Productname> superuser is
allowed to execute
some support programs which are generally not available to all users.
Note that the <Productname>Postgres</Productname> superuser is
<emphasis>not</emphasis>
the same as the Unix superuser (which will be referred to as
<firstterm>root</firstterm>).
The superuser should have a non-zero user identifier
(<firstterm>UID</firstterm>) for security reasons.
</para>
<para>
The
<firstterm>database administrator</firstterm>
or <acronym>DBA</acronym>, is the person who is responsible for installing
<Productname>Postgres</Productname> with mechanisms to
enforce a security policy for a site. The DBA can add new users by
the method described below
and maintain a set of template databases for use by
<application>createdb</application>.
</para>
<para>
The <application>postmaster</application>
is the process that acts as a clearing-house for requests
to the <Productname>Postgres</Productname> system.
Frontend applications connect to the <application>postmaster</application>,
which keeps tracks of any system errors and communication between the
backend processes. The <application>postmaster</application>
can take several command-line arguments to tune its behavior.
However, supplying arguments is necessary only if you intend to run multiple
sites or a non-default site.
</para>
<para>
The <Productname>Postgres</Productname> backend
(the actual executable program <application>postgres</application>) may be executed
directly from the user shell by the
<Productname>Postgres</Productname> super-user
(with the database name as an argument). However,
doing this bypasses the shared buffer pool and lock table associated
with a postmaster/site, therefore this is not recommended in a multiuser
site.
</para>
</sect1>
<sect1 id="notation">
<title>Notation</title>
<title>Terminology and Notation</title>
<para>
"<literal>...</literal>" or <filename>/usr/local/pgsql/</filename>
at the front of a file name is used to represent the
path to the <Productname>Postgres</Productname> superuser's home directory.
The terms <quote>Postgres</quote> and <quote>PostgreSQL</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
<productname>PostgreSQL</productname> system. These terms should not
be interpreted too narrowly; this documentation set does not have fixed
presumptions about system administration procedures.
</para>
<para>
<filename>/usr/local/pgsql/</filename> is generally used as the root
directory of the installation and <filename>/usr/local/pgsql/data</filename>
as the directory with the database files. These directories may vary
on your site, details can be derived in the <citetitle>Administrator's Guide</citetitle>.
</para>
<para>
@ -77,28 +36,19 @@ $Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.13 2000/12/22 21:51:58 pe
indicates that you must choose one.
</para>
<para>
In examples, parentheses ("<literal>(</literal>" and "<literal>)</literal>") are
used to group boolean
expressions. "<literal>|</literal>" is the boolean operator OR.
</para>
<para>
Examples will show commands executed from various accounts and programs.
Commands executed from the root account will be preceeded with
"<literal>&gt;</literal>".
Commands executed from the <Productname>Postgres</Productname>
superuser account will be preceeded with "<literal>%</literal>", while commands
executed from an unprivileged user's account will be preceeded with
"<literal>$</literal>".
<acronym>SQL</acronym> commands will be preceeded with "<literal>=&gt;</literal>"
Commands executed from a Unix shell may be preceeded with a dollar sign
(<quote><literal>$</literal></quote>). Commands executed from particular user
accounts such as root or postgres are specially flagged and explained.
<acronym>SQL</acronym> commands may be preceeded with
<quote><literal>=&gt;</literal></quote>
or will have no leading prompt, depending on the context.
</para>
<note>
<para>
At the time of writing (<Productname>Postgres</Productname> 7.0)
the notation for
The notation for
flagging commands is not universally consistant throughout the
documentation set.
Please report problems to the documentation mailing list

3
doc/src/sgml/postgres.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.44 2000/11/24 17:44:21 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.45 2001/02/03 19:03:27 petere Exp $
-->
<!doctype set PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
@ -26,6 +26,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.44 2000/11/24 17:44:21 pe
<setinfo>
<corpauthor>The PostgreSQL Global Development Group</corpauthor>
&legal;
</setinfo>
&tutorial;

77
doc/src/sgml/problems.sgml
View File

@ -1,9 +1,9 @@
<sect1 id="problem-reporting">
<title>Problem Reporting Guidelines</title>
<sect1 id="bug-reporting">
<title>Bug Reporting Guidelines</title>
<para>
When you encounter a problem in <productname>PostgreSQL</productname> we want to
hear about it. Your bug reports are an important part in making
When you find a bug in <productname>PostgreSQL</productname> we want to
hear about it. Your bug reports play an important part in making
<productname>PostgreSQL</productname> more reliable because even the utmost
care cannot guarantee that every part of PostgreSQL will work on every
platform under every circumstance.
@ -21,7 +21,7 @@
could also happen that we tell you to update to a newer version to see if the
bug happens there. Or we might decide that the bug
cannot be fixed before some major rewrite we might be planning is done. Or
perhaps it's simply too hard and there are more important things on the agenda.
perhaps it is simply too hard and there are more important things on the agenda.
If you need help immediately, consider obtaining a commercial support contract.
</para>
@ -29,21 +29,21 @@
<title>Identifying Bugs</title>
<para>
Before you ask "Is this a bug?", please read and re-read the
Before you report a bug, please read and re-read the
documentation to verify that you can really do whatever it is you are
trying. If it is not clear from the documentation whether you can do
something or not, please report that too; it's a bug in the documentation.
something or not, please report that too; it is a bug in the documentation.
If it turns out that the program does something different from what the
documentation says, that's a bug. That might include, but is not limited to,
documentation says, that is a bug. That might include, but is not limited to,
the following circumstances:
<itemizedlist>
<listitem>
<para>
A program terminates with a fatal signal or an operating system
error message that would point to a problem in the program (a
counterexample might be a "disk full" message,
since that must be fixed outside of <productname>Postgres</productname>).
error message that would point to a problem in the program. (A
counterexample might be a <quote>disk full</quote> message,
since you have to fix that yourself.)
</para>
</listitem>
@ -55,13 +55,15 @@
<listitem>
<para>
A program refuses to accept valid input.
A program refuses to accept valid input (as defined in the documentation).
</para>
</listitem>
<listitem>
<para>
A program accepts invalid input without a notice or error message.
Keep in mind that your idea of invalid input might be our idea of
an extension or compatibility with traditional practice.
</para>
</listitem>
@ -73,7 +75,7 @@
</listitem>
</itemizedlist>
Here "<literal>program</literal>" refers to any executable, not only the backend server.
Here <quote>program</quote> refers to any executable, not only the backend server.
</para>
<para>
@ -85,7 +87,7 @@
<para>
Before you continue, check on the TODO list and in the FAQ to see if your bug is
already known. If you can't decode the information on the TODO list, report your
already known. If you cannot decode the information on the TODO list, report your
problem. The least we can do is make the TODO list clearer.
</para>
</sect2>
@ -104,7 +106,7 @@
Reporting the bare facts
is relatively straightforward (you can probably copy and paste them from the
screen) but all too often important details are left out because someone
thought it doesn't matter or the report would be understood
thought it does not matter or the report would be understood
anyway.
</para>
@ -127,11 +129,11 @@
that shows the problem. (Be sure to not have anything in your
<filename>~/.psqlrc</filename> start-up file.) You are encouraged to
minimize the size of your example, but this is not absolutely necessary.
If the bug is reproduceable, we'll find it either way.
If the bug is reproduceable, we will find it either way.
</para>
<para>
If your application uses some other client interface, such as PHP, then
please try to isolate the offending queries. We probably won't set up a
please try to isolate the offending queries. We will probably not set up a
web server to reproduce your problem. In any case remember to provide
the exact input files, do not guess that the problem happens for
"large files" or "mid-size databases", etc. since this
@ -141,9 +143,9 @@
<listitem>
<para>
The output you got. Please do not say that it "didn't work" or
"failed". If there is an error message,
show it, even if you don't understand it. If the program terminates with
The output you got. Please do not say that it <quote>didn't work</quote> or
<quote>crashed</quote>. If there is an error message,
show it, even if you do not understand it. If the program terminates with
an operating system error, say which. If nothing at all happens, say so.
Even if the result of your test case is a program crash or otherwise obvious
it might not happen on our platform. The easiest thing is to copy the output
@ -164,7 +166,7 @@
The output you expected is very important to state. If you just write
"This command gives me that output." or "This is not
what I expected.", we might run it ourselves, scan the output, and
think it looks okay and is exactly what we expected. We shouldn't have to
think it looks okay and is exactly what we expected. We should not have to
spend the time to decode the exact semantics behind your commands.
Especially refrain from merely saying that "This is not what SQL says/Oracle
does." Digging out the correct behavior from <acronym>SQL</acronym>
@ -194,19 +196,26 @@
<para>
The <productname>PostgreSQL</productname> version. You can run the command
<literal>SELECT version();</literal> to
find out what version you are currently running.
If this function does not exist, say so, then we know that
your version is old enough. If you can't start up the server or a
client, look into the README file in the source directory or at the
name of your distribution file or package name. If your version is older
than 7.0 we will almost certainly tell you to upgrade. There are tons
of bug fixes in each new version, that's why we write them.
</para>
<para>
find out the version of the server you are connected to. Most executable
programs also support a <option>--version</option> option; at least
<literal>postmaster --version</literal> and <literal>psql --version</literal>
should work.
If the function or the options do not exist then your version is probably
old enough. You can also look into the <filename>README</filename> file
in the source directory or at the
name of your distribution file or package name.
If you run a pre-packaged version, such as RPMs, say so, including any
subversion the package may have. If you are talking about a CVS
snapshot, mention that, including its date and time.
</para>
<para>
If your version is older than &version; we will almost certainly tell
you to upgrade. There are tons
of bug fixes in each new release, that is why we make new releases.
</para>
<para>
</para>
</listitem>
<listitem>
@ -222,7 +231,7 @@
</itemizedlist>
Do not be afraid if your bug report becomes rather lengthy. That is a fact of life.
It's better to report everything the first time than us having to squeeze the
It is better to report everything the first time than us having to squeeze the
facts out of you. On the other hand, if your input files are huge, it is
fair to ask first whether somebody is interested in looking into it.
</para>
@ -230,9 +239,9 @@
<para>
Do not spend all your time to figure out which changes in the input make
the problem go away. This will probably not help solving it. If it turns
out that the bug can't be fixed right away, you will still have time to
out that the bug cannot be fixed right away, you will still have time to
find and share your work around. Also, once again, do not waste your time
guessing why the bug exists. We'll find that out soon enough.
guessing why the bug exists. We will find that out soon enough.
</para>
<para>
@ -240,7 +249,7 @@
The software package as such is called "PostgreSQL",
sometimes "Postgres" for short. (Sometimes
the abbreviation "Pgsql" is used but don't do that.) When you
are specifically talking about the backend server, mention that, don't
are specifically talking about the backend server, mention that, do not
just say "Postgres crashes". The interactive frontend is called
"psql" and is for all intends and purposes completely separate
from the backend.

54
doc/src/sgml/programmer.sgml
View File

@ -1,51 +1,41 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.32 2001/01/24 19:42:46 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.33 2001/02/03 19:03:27 petere Exp $
PostgreSQL Programmer's Guide.
-->
<book id="programmer">
<title><![%single-book;[PostgreSQL &version;]]> Programmer's Guide</title>
<title>PostgreSQL &version; Programmer's Guide</title>
<bookinfo>
<corpauthor>The PostgreSQL Global Development Group</corpauthor>
<editor>
<firstname>Thomas</firstname>
<surname>Lockhart</surname>
<affiliation>
<orgname>Caltech/JPL</orgname>
</affiliation>
</editor>
<legalnotice>
<para>
<productname>PostgreSQL</productname> is Copyright &copy; 1996-2001
by PostgreSQL Global Development Group
</para>
</legalnotice>
&legal;
</bookinfo>
<preface id="pg-preface">
<title>Summary</title>
<![%single-book[
&intro;
]]>
<preface id="organization">
<title>Organization</title>
<para>
<productname>Postgres</productname>,
developed originally in the UC Berkeley Computer Science Department,
pioneered many of the object-relational concepts
now becoming available in some commercial databases.
It provides SQL92/SQL99 language support,
transaction integrity, and type extensibility.
<productname>PostgreSQL</productname> is an
open-source descendant of this original Berkeley code.
The first part of this manual is the description of the client-side
programming interfaces and support libraries for various languages.
The second part explains the <productname>PostgreSQL</productname>
approach to extensibility and describe how users can extend
<productname>PostgreSQL</productname> by adding user-defined types,
operators, aggregates, and both query language and programming
language functions. After a discussion of the
<productname>PostgreSQL</productname> rule system, we discuss the
trigger and SPI interfaces.
</para>
<para>
Proficiency with Unix and C programming is assumed.
</para>
</preface>
<![%single-book[
&intro-pg;
]]>
<part id="programmer-client">
<title>Client Interfaces</title>
&libpq;

12
doc/src/sgml/reference.sgml
View File

@ -1,21 +1,15 @@
<!-- reference.sgml
$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.13 2001/01/24 19:42:46 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.14 2001/02/03 19:03:27 petere Exp $
PostgreSQL Reference Manual
-->
<book id="reference">
<title><![%single-book;[PostgreSQL &version;]]> Reference Manual</title>
<title>PostgreSQL &version; Reference Manual</title>
<bookinfo>
<corpauthor>The PostgreSQL Global Development Group</corpauthor>
<legalnotice>
<para>
<productname>PostgreSQL</productname> is &copy; 1998-2000
by PostgreSQL Global Development Group
</para>
</legalnotice>
&legal;
</bookinfo>
<reference id="sql-commands">

36
doc/src/sgml/tutorial.sgml
View File

@ -1,45 +1,15 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/tutorial.sgml,v 1.13 2001/01/24 19:42:46 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/tutorial.sgml,v 1.14 2001/02/03 19:03:27 petere Exp $
-->
<book id="tutorial">
<title><![%single-book;[PostgreSQL &version;]]> Tutorial</title>
<title>PostgreSQL &version; Tutorial</title>
<bookinfo>
<corpauthor>The PostgreSQL Global Development Group</corpauthor>
<editor>
<firstname>Thomas</firstname>
<surname>Lockhart</surname>
<affiliation>
<orgname>Caltech/JPL</orgname>
</affiliation>
</editor>
<legalnotice>
<para>
<productname>PostgreSQL</productname> is Copyright &copy; 1996-2001
by PostgreSQL Global Development Group
</para>
</legalnotice>
&legal;
</bookinfo>
<preface id="tutorial-preface">
<title>Summary</title>
<para>
<productname>Postgres</productname>,
developed originally in the UC Berkeley Computer Science Department,
pioneered many of the object-relational concepts
now becoming available in some commercial databases.
It provides SQL92/SQL99 language support,
transaction integrity, and type extensibility.
<productname>PostgreSQL</productname> is an open-source descendant
of this original Berkeley code.
</para>
</preface>
<![%single-book;[
&intro;
]]>

40
doc/src/sgml/user.sgml
View File

@ -1,48 +1,20 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.26 2001/01/24 19:42:46 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.27 2001/02/03 19:03:27 petere Exp $
-->
<book id="user">
<!-- Title information -->
<title><![%single-book;[PostgreSQL &version;]]> User's Guide</title>
<title>PostgreSQL &version; User's Guide</title>
<bookinfo>
<corpauthor>The PostgreSQL Development Team</corpauthor>
<editor>
<firstname>Thomas</firstname>
<surname>Lockhart</surname>
<affiliation>
<orgname>Caltech/JPL</orgname>
</affiliation>
</editor>
<legalnotice>
<para>
<productname>PostgreSQL</productname> is Copyright &copy; 1996-2001
by PostgreSQL Global Development Group
</para>
</legalnotice>
<corpauthor>The PostgreSQL Global Development Group</corpauthor>
&legal;
</bookinfo>
<preface id="ug-preface">
<title>Summary</title>
<para>
<productname>Postgres</productname>,
developed originally in the UC Berkeley Computer Science Department,
pioneered many of the object-relational concepts
now becoming available in some commercial databases.
It provides SQL92/SQL99 language support,
transaction integrity, and type extensibility.
<productname>PostgreSQL</productname> is an open-source descendant
of this original Berkeley code.
</para>
</preface>
&intro;
&syntax;
&queries;
&datatype;

9
doc/src/sgml/y2k.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/y2k.sgml,v 1.8 2000/12/22 21:51:58 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/y2k.sgml,v 1.9 2001/02/03 19:03:27 petere Exp $
-->
<sect1 id="y2k">
@ -16,8 +16,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/y2k.sgml,v 1.8 2000/12/22 21:51:58 pe
</note>
<para>
The <productname>PostgreSQL</productname> Global Development Team provides
the <productname>Postgres</productname> software code tree as a public service,
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 it's behavior or performance.
However, at the time of writing:
</para>
@ -48,8 +48,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/y2k.sgml,v 1.8 2000/12/22 21:51:58 pe
<para>
To the best of the author's knowledge, the
assumptions Postgres makes about dates specified with a two-digit year
are documented in the current
<ulink url="http://www.postgresql.org/docs/user/datatype.htm">User's Guide</ulink>
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,