From 6de93c0529cd0b15824eb4ebbd273d69af926357 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Mon, 8 Sep 2003 23:02:28 +0000
Subject: [PATCH] Update preface.
Use question marks rather than brackets to delimit optional elements in
Tcl synopses.
Fix stylesheet misfeature leading to excessively long cross-reference text
when linking to a different "part".
Remove <body> attributes -- CSS stylesheets should handle that.
Improve bibliography formatting.
Add fast-forward links for more convenient navigation.
---
doc/src/sgml/history.sgml | 306 +++++++++++++++---------------------
doc/src/sgml/info.sgml | 141 ++---------------
doc/src/sgml/intro.sgml | 255 +++++++++++++++++-------------
doc/src/sgml/libpgtcl.sgml | 10 +-
doc/src/sgml/notation.sgml | 83 ++++------
doc/src/sgml/pltcl.sgml | 6 +-
doc/src/sgml/postgres.sgml | 12 +-
doc/src/sgml/stylesheet.dsl | 42 ++++-
8 files changed, 366 insertions(+), 489 deletions(-)
diff --git a/doc/src/sgml/history.sgml b/doc/src/sgml/history.sgml
index 6e64f7e6026..07b96ce6f46 100644
--- a/doc/src/sgml/history.sgml
+++ b/doc/src/sgml/history.sgml
@@ -1,182 +1,181 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.20 2003/01/19 00:13:28 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.21 2003/09/08 23:02:28 petere Exp $
-->
<sect1 id="history">
<title>A Brief History of <productname>PostgreSQL</productname></title>
+ <indexterm zone="history">
+ <primary>history</primary>
+ <secondary>of PostgreSQL</secondary>
+ </indexterm>
+
<para>
- 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 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 multiversion 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).
+ The object-relational database management system now known as
+ <productname>PostgreSQL</productname> is derived from the
+ <productname>POSTGRES</productname> package written at the
+ University of California at Berkeley. With over a decade of
+ development behind it, <productname>PostgreSQL</productname> is now
+ the most advanced open-source database available anywhere.
</para>
- <sect2>
+ <sect2 id="history-berkeley">
<title>The Berkeley <productname>POSTGRES</productname> Project</title>
+ <indexterm zone="history-berkeley">
+ <primary>POSTGRES</primary>
+ </indexterm>
+
<para>
- Implementation of the <productname>POSTGRES</productname>
- <acronym>DBMS</acronym> began in 1986. The
- initial concepts for the system were presented in
- <xref linkend="STON86">
- and the definition of the initial data model
- appeared in
- <xref linkend="ROWE87">.
- The design of the rule system at
- that time was described in
- <xref linkend="STON87a">.
- The rationale
- and architecture of the storage manager were detailed in
- <xref linkend="STON87b">.
+ 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. The implementation of
+ <productname>POSTGRES</productname> began in 1986. The initial
+ concepts for the system were presented in <xref linkend="STON86">
+ and the definition of the initial data model appeared in <xref
+ linkend="ROWE87">. The design of the rule system at that time was
+ described in <xref linkend="STON87a">. The rationale and
+ architecture of the storage manager were detailed in <xref
+ linkend="STON87b">.
</para>
<para>
- <productname>Postgres</productname> has undergone several major releases since
- then. The first <quote>demoware</quote> system became operational
- in 1987 and was shown at the 1988 <acronym>ACM-SIGMOD</acronym>
- Conference. Version 1, described in
- <xref linkend="STON90a">, was released
- to a few external users in June 1989. In response to a
- critique of the first rule system
- (<xref linkend="STON89">),
- the rule
- system was redesigned
- (<xref linkend="STON90b">)
- and Version 2 was
- released in June 1990 with the new rule system.
- Version 3 appeared in 1991 and added support for multiple
- storage managers, an improved query executor, and a
- rewritten rule system. For the most part, subsequent
- releases until <productname>Postgres95</productname> (see below)
- focused on portability and reliability.
+ <productname>POSTGRES</productname> has undergone several major
+ releases since then. The first <quote>demoware</quote> system
+ became operational in 1987 and was shown at the 1988
+ <acronym>ACM-SIGMOD</acronym> Conference. Version 1, described in
+ <xref linkend="STON90a">, was released to a few external users in
+ June 1989. In response to a critique of the first rule system
+ (<xref linkend="STON89">), the rule system was redesigned (<xref
+ linkend="STON90b">) and Version 2 was released in June 1990 with
+ the new rule system. Version 3 appeared in 1991 and added support
+ for multiple storage managers, an improved query executor, and a
+ rewritten rule system. For the most part, subsequent releases
+ until <productname>Postgres95</productname> (see below) focused on
+ portability and reliability.
</para>
<para>
- <productname>POSTGRES</productname> has been used
- to implement many different
- research and production applications. These include: a
- financial data analysis system, a jet engine
- performance monitoring package, an asteroid tracking
- database, a medical information database, and several
- geographic information systems.
- <productname>POSTGRES</productname> has also been
- used as an educational tool at several universities.
- Finally,
- Illustra Information Technologies (later merged into
- <ulink url="http://www.informix.com/"><productname>Informix</productname></ulink>,
- which is now owned by <ulink url="http://www.ibm.com/">IBM</ulink>.)
- picked up
- the code and commercialized it.
- <productname>POSTGRES</productname> became the primary data manager
- for the
- <ulink url="http://meteora.ucsd.edu/s2k/s2k_home.html">Sequoia 2000</ulink>
- scientific computing project in late 1992.
+ <productname>POSTGRES</productname> has been used to implement many
+ different research and production applications. These include: a
+ financial data analysis system, a jet engine performance monitoring
+ package, an asteroid tracking database, a medical information
+ database, and several geographic information systems.
+ <productname>POSTGRES</productname> has also been used as an
+ educational tool at several universities. Finally, Illustra
+ Information Technologies (later merged into <ulink
+ url="http://www.informix.com/"><productname>Informix</productname></ulink>,
+ which is now owned by <ulink
+ url="http://www.ibm.com/">IBM</ulink>.) picked up the code and
+ commercialized it. In late 1992,
+ <productname>POSTGRES</productname> became the primary data manager
+ for the <ulink
+ url="http://meteora.ucsd.edu/s2k/s2k_home.html">Sequoia
+ 2000</ulink> scientific computing project.
</para>
<para>
- The size of the external user community
- nearly doubled during 1993. It became increasingly
- obvious that maintenance of the prototype code and
- support was taking up large amounts of time that should
- have been devoted to database research. In an effort
- to reduce this support burden, the Berkeley
- <productname>POSTGRES</productname> project officially
- ended with Version 4.2.
+ The size of the external user community nearly doubled during 1993.
+ It became increasingly obvious that maintenance of the prototype
+ code and support was taking up large amounts of time that should
+ have been devoted to database research. In an effort to reduce
+ this support burden, the Berkeley
+ <productname>POSTGRES</productname> project officially ended with
+ Version 4.2.
</para>
</sect2>
- <sect2>
+ <sect2 id="history-postgres95">
<title><productname>Postgres95</productname></title>
+ <indexterm zone="history-postgres95">
+ <primary>Postgres95</primary>
+ </indexterm>
+
<para>
- In 1994, Andrew Yu and Jolly Chen
- added a SQL language interpreter to <productname>POSTGRES</productname>.
+ In 1994, Andrew Yu and Jolly Chen added a SQL language interpreter
+ to <productname>POSTGRES</productname>. Under a new name,
<productname>Postgres95</productname> was subsequently released to
- the Web to find its own way in the world as an
- open-source descendant of the original <productname>POSTGRES</productname>
+ the web to find its own way in the world as an open-source
+ descendant of the original <productname>POSTGRES</productname>
Berkeley code.
</para>
<para>
- <productname>Postgres95</productname> code was completely
- ANSI C and trimmed in size by 25%. Many
- internal changes improved performance and maintainability.
- <productname>Postgres95</productname> release 1.0.x ran about 30-50%
- faster on the Wisconsin Benchmark compared to
- <productname>POSTGRES</productname>, Version 4.2.
- Apart from bug fixes, the following were the major enhancements:
+ <productname>Postgres95</productname> code was completely ANSI C
+ and trimmed in size by 25%. Many internal changes improved
+ performance and
+ maintainability. <productname>Postgres95</productname> release
+ 1.0.x ran about 30-50% faster on the Wisconsin Benchmark compared
+ to <productname>POSTGRES</productname>, Version 4.2. Apart from
+ bug fixes, the following were the major enhancements:
<itemizedlist>
<listitem>
<para>
The query language PostQUEL was replaced with
- <acronym>SQL</acronym> (implemented in the server).
- Subqueries were not supported until
- <productname>PostgreSQL</productname> (see below), but they
- could be imitated in <productname>Postgres95</productname> with user-defined
- <acronym>SQL</acronym> functions. Aggregates were
- re-implemented. Support for the GROUP BY query clause was also added.
- The <filename>libpq</filename> interface remained
- available for <acronym>C</acronym>
- programs.
+ <acronym>SQL</acronym> (implemented in the server). Subqueries
+ were not supported until <productname>PostgreSQL</productname>
+ (see below), but they could be imitated in
+ <productname>Postgres95</productname> with user-defined
+ <acronym>SQL</acronym> functions. Aggregate functions were
+ re-implemented. Support for the <literal>GROUP BY</literal>
+ query clause was also added.
</para>
</listitem>
<listitem>
<para>
In addition to the monitor program, a new program
- (<application>psql</application>) was provided for interactive SQL queries
- using <acronym>GNU</acronym> <application>Readline</application>.
+ (<application>psql</application>) was provided for interactive
+ SQL queries, which used <acronym>GNU</acronym>
+ <application>Readline</application>.
</para>
</listitem>
<listitem>
<para>
- A new front-end library, <filename>libpgtcl</filename>,
- supported <acronym>Tcl</acronym>-based clients. A sample shell,
- <command>pgtclsh</command>, provided new Tcl commands to interface
- <application>Tcl</application>
- programs with the <productname>Postgres95</productname> backend.
+ A new front-end library, <filename>libpgtcl</filename>,
+ supported <acronym>Tcl</acronym>-based clients. A sample shell,
+ <command>pgtclsh</command>, provided new Tcl commands to
+ interface <application>Tcl</application> programs with the
+ <productname>Postgres95</productname> server.
</para>
</listitem>
<listitem>
<para>
- The large-object interface was overhauled. The Inversion large objects were
- the only mechanism for storing large objects.
- (The Inversion file system was removed.)
+ The large-object interface was overhauled. The inversion large
+ objects were the only mechanism for storing large objects. (The
+ inversion file system was removed.)
</para>
</listitem>
<listitem>
<para>
- The instance-level rule system was removed.
- Rules were still available as rewrite rules.
+ The instance-level rule system was removed. Rules were still
+ available as rewrite rules.
</para>
</listitem>
<listitem>
<para>
- A short tutorial introducing regular <acronym>SQL</acronym> features as
- well as those of <productname>Postgres95</productname> was
- distributed with the source code
+ A short tutorial introducing regular <acronym>SQL</acronym>
+ features as well as those of
+ <productname>Postgres95</productname> was distributed with the
+ source code
</para>
</listitem>
<listitem>
<para>
- <acronym>GNU</acronym> make (instead of <acronym>BSD</acronym> make) was used
- for the build. Also, <productname>Postgres95</productname> could be
- compiled with an unpatched <productname>GCC</productname>
- (data alignment of doubles was fixed).
+ <acronym>GNU</acronym> make (instead of <acronym>BSD</acronym>
+ make) was used for the build. Also,
+ <productname>Postgres95</productname> could be compiled with an
+ unpatched <productname>GCC</productname> (data alignment of
+ doubles was fixed).
</para>
</listitem>
</itemizedlist>
@@ -187,83 +186,28 @@ $Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.20 2003/01/19 00:13:28 mom
<title><productname>PostgreSQL</productname></title>
<para>
- By 1996, it became clear that the name <quote>Postgres95</quote> would
- not stand the test of time. We chose a new name,
+ By 1996, it became clear that the name <quote>Postgres95</quote>
+ would not stand the test of time. We chose a new name,
<productname>PostgreSQL</productname>, to reflect the relationship
- between the original <productname>POSTGRES</productname> and the more
- recent versions with <acronym>SQL</acronym> capability. At the same
- time, we set the version numbering to start at 6.0, putting the
- numbers back into the sequence originally begun by the Berkeley
- <productname>POSTGRES</productname> project.
+ between the original <productname>POSTGRES</productname> and the
+ more recent versions with <acronym>SQL</acronym> capability. At
+ the same time, we set the version numbering to start at 6.0,
+ putting the numbers back into the sequence originally begun by the
+ Berkeley <productname>POSTGRES</productname> project.
</para>
<para>
- The emphasis during development of <productname>Postgres95</productname>
- was on identifying and understanding existing problems in the backend code.
- With <productname>PostgreSQL</productname>,
- the emphasis has shifted to augmenting features and capabilities, although
- work continues in all areas.
+ The emphasis during development of
+ <productname>Postgres95</productname> was on identifying and
+ understanding existing problems in the server code. With
+ <productname>PostgreSQL</productname>, the emphasis has shifted to
+ augmenting features and capabilities, although work continues in
+ all areas.
</para>
<para>
- Major enhancements in <productname>PostgreSQL</productname> include:
+ Details about what has happened in PostgreSQL since then can be
+ found in <xref linkend="release">.
</para>
-
- <itemizedlist>
- <listitem>
- <para>
- Table-level locking has been replaced by multiversion concurrency control,
- which allows readers to continue reading consistent data during writer activity
- and enables hot backups from <application>pg_dump</> while the database stays available for
- queries.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Important backend features, including subselects, defaults,
- constraints, and triggers, have been implemented.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Additional <acronym>SQL92</acronym>-compliant language features have been added,
- including primary keys, quoted identifiers, literal string type coercion,
- type casting, and binary and hexadecimal integer input.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Built-in types have been improved, including new wide-range date/time types
- and additional geometric type support.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Overall backend code speed has been increased by approximately 20-40%,
- and backend start-up time has decreased by 80% since version 6.0 was released.
- </para>
- </listitem>
- </itemizedlist>
</sect2>
</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:
--->
diff --git a/doc/src/sgml/info.sgml b/doc/src/sgml/info.sgml
index 62d754d1337..73e1d854d8e 100644
--- a/doc/src/sgml/info.sgml
+++ b/doc/src/sgml/info.sgml
@@ -1,104 +1,21 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.18 2003/01/19 00:13:28 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.19 2003/09/08 23:02:28 petere Exp $
-->
<sect1 id="resources">
- <title>Overview of Documentation Resources</title>
+ <title>Further Information</title>
<para>
- The <productname>PostgreSQL</> documentation is organized into
- several books:
+ Besides the documentation, that is, this book, there are other
+ resources about <productname>PostgreSQL</productname>:
<variablelist>
- <varlistentry>
- <term>&cite-tutorial;</term>
- <listitem>
- <para>
- An informal introduction for new users.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>&cite-user;</term>
- <listitem>
- <para>
- Documents the <acronym>SQL</acronym> query language environment,
- including data types and functions, as well as user-level
- performance tuning. Every <productname>PostgreSQL</> user
- should read this.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>&cite-admin;</term>
- <listitem>
- <para>
- Installation and server management information. Everyone who
- runs a <productname>PostgreSQL</> server, either for personal
- use or for other users, needs to read this.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>&cite-programmer;</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>&cite-reference;</term>
- <listitem>
- <para>
- Reference pages for <acronym>SQL</acronym> 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>&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 &cite-programmer;.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- In addition to this manual set, there are other resources to help you with
- <productname>PostgreSQL</productname> installation and use:
-
- <variablelist>
- <varlistentry>
- <term>man pages</term>
- <listitem>
- <para>
- The &cite-reference;'s pages in the traditional Unix man
- format. There is no difference in content.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term>FAQs</term>
<listitem>
<para>
- Frequently Asked Questions (FAQ) lists document both general issues
- and some platform-specific issues.
+ The FAQ list <indexterm><primary>FAQ-Liste</></> contains
+ continuously updated answers to frequently asked questions.
</para>
</listitem>
</varlistentry>
@@ -107,7 +24,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.18 2003/01/19 00:13:28 momjia
<term>READMEs</term>
<listitem>
<para>
- README files are available for some contributed packages.
+ <filename>README</filename> files are available for some
+ contributed packages.
</para>
</listitem>
</varlistentry>
@@ -118,8 +36,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.18 2003/01/19 00:13:28 momjia
<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
+ web site</ulink> carries details on the latest release and other
+ information to make your work or play with
<productname>PostgreSQL</productname> more productive.
</para>
</listitem>
@@ -131,10 +49,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.18 2003/01/19 00:13:28 momjia
<para>
The mailing lists are a good place to have your questions
answered, to share experiences with other users, and to contact
- the developers. Consult the <ulink
- url="http://www.postgresql.org/users-lounge/">User's
- Lounge</ulink> section of the <productname>PostgreSQL</>
- web site for details.
+ the developers. Consult the <productname>PostgreSQL</> web site
+ for details.
</para>
</listitem>
</varlistentry>
@@ -143,41 +59,18 @@ $Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.18 2003/01/19 00:13:28 momjia
<term>Yourself!</term>
<listitem>
<para>
- <productname>PostgreSQL</productname> is an open-source effort.
+ <productname>PostgreSQL</productname> is an open-source project.
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 them.
- </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> mailing
- list is the place to get going.
+ knowledge back. Read the mailing lists and answer questions. If
+ you learn something which is not in the documentation, write it
+ up and contribute it. If you add features to the code,
+ contribute them.
</para>
</listitem>
</varlistentry>
</variablelist>
</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:
--->
diff --git a/doc/src/sgml/intro.sgml b/doc/src/sgml/intro.sgml
index ba5653f155c..c547c7a8808 100644
--- a/doc/src/sgml/intro.sgml
+++ b/doc/src/sgml/intro.sgml
@@ -1,110 +1,151 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.20 2002/10/24 17:48:54 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.21 2003/09/08 23:02:28 petere Exp $
-->
- <sect1 id="intro-whatis">
- <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
- (<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
- strings, money, and dates. It is commonly recognized
- that this model is inadequate for future data-processing applications.
- The relational model successfully replaced previous
- models in part because of its <quote>Spartan simplicity</quote>.
- However, this simplicity makes the
- implementation of certain applications very difficult.
- <productname>PostgreSQL</productname> offers substantial additional
- power by incorporating the following additional
- concepts in such a way that users can easily
- extend the system:
-
- <itemizedlist spacing="compact">
- <listitem>
- <simpara>inheritance</>
- </listitem>
- <listitem>
- <simpara>data types</>
- </listitem>
- <listitem>
- <simpara>functions</simpara>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- Other features provide additional power and flexibility:
-
- <itemizedlist spacing="compact">
- <listitem>
- <simpara>constraints</simpara>
- </listitem>
- <listitem>
- <simpara>triggers</simpara>
- </listitem>
- <listitem>
- <simpara>rules</simpara>
- </listitem>
- <listitem>
- <simpara>transactional integrity</simpara>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- These features put <productname>PostgreSQL</productname> into the
- category of databases referred to as
- <firstterm>object-relational</firstterm>. Note that this is distinct
- from those referred to as <firstterm>object-oriented</firstterm>,
- which in general are not as well suited to supporting
- traditional relational database languages.
- So, although <productname>PostgreSQL</productname> has some
- object-oriented features, it is firmly in the relational database
- world. In fact, some commercial databases have recently
- incorporated features pioneered by <productname>PostgreSQL</productname>.
- </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:
--->
+<preface id="preface">
+ <title>Preface</title>
+
+ <para>
+ This book is the official documentation of PostgreSQL. It is being
+ written by the PostgreSQL developers and other volunteers in
+ parallel to the development of the PostgreSQL software. It
+ describes all the functionality that the current version of
+ PostgreSQL officially supports.
+ </para>
+
+ <para>
+ To make the large amount of information about PostgreSQL manageable,
+ this book has been organized in several parts. Each part is
+ targeted at a different class of users, or at users in different
+ stages of their PostgreSQL experience:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <xref linkend="tutorial"> is an informal introduction for new users.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <xref linkend="sql"> documents the <acronym>SQL</acronym> query
+ language environment, including data types and functions, as well
+ as user-level performance tuning. Every
+ <productname>PostgreSQL</> user should read this.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <xref linkend="admin"> describes the installation and
+ administration of the server. Everyone that runs a PostgreSQL
+ server, be it for private use or for others, should read this
+ part.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <xref linkend="client-interfaces"> describes the programming
+ interfaces for PostgreSQL client programs.
+ </para>
+ </listitem>
+
+
+ <listitem>
+ <para>
+ <xref linkend="server-programming"> contains information for
+ advanced users about the extensibility capabilities of the
+ server. Topics are, for instance, user-defined data types and
+ functions.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <xref linkend="reference"> contains information about the syntax
+ of SQL commands, client and server programs. This part supports
+ the other parts with structured information sorted by command or
+ program.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <sect1 id="intro-whatis">
+ <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. POSTGRES pioneered many concepts that only became
+ available in some commercial database systems much later.
+ </para>
+
+ <para>
+ <productname>PostgreSQL</productname> is an open-source descendant
+ of this original Berkeley code. It supports SQL92 and SQL99 and
+ offers many modern features:
+
+ <itemizedlist spacing="compact">
+ <listitem>
+ <simpara>complex queries</simpara>
+ </listitem>
+ <listitem>
+ <simpara>foreign keys</simpara>
+ </listitem>
+ <listitem>
+ <simpara>triggers</simpara>
+ </listitem>
+ <listitem>
+ <simpara>views</simpara>
+ </listitem>
+ <listitem>
+ <simpara>transactional integrity</simpara>
+ </listitem>
+ <listitem>
+ <simpara>multiversion concurrency control</simpara>
+ </listitem>
+ </itemizedlist>
+
+ Also, PostgreSQL can be extended by the user in many ways, for
+ example by adding new
+
+ <itemizedlist spacing="compact">
+ <listitem>
+ <simpara>data types</simpara>
+ </listitem>
+ <listitem>
+ <simpara>functions</simpara>
+ </listitem>
+ <listitem>
+ <simpara>operators</simpara>
+ </listitem>
+ <listitem>
+ <simpara>aggregate functions</simpara>
+ </listitem>
+ <listitem>
+ <simpara>index methods</simpara>
+ </listitem>
+ <listitem>
+ <simpara>procedural languages</simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ And because of the liberal license, PostgreSQL can be used,
+ modified, and distributed by everyone free of charge for any
+ purpose, be it private, commercial, or academic.
+ </para>
+ </sect1>
+
+ &history;
+ ¬ation;
+ &info;
+ &problems;
+
+</preface>
diff --git a/doc/src/sgml/libpgtcl.sgml b/doc/src/sgml/libpgtcl.sgml
index afcc7061ede..70bf66806ed 100644
--- a/doc/src/sgml/libpgtcl.sgml
+++ b/doc/src/sgml/libpgtcl.sgml
@@ -201,7 +201,7 @@ load libpgtcl[info sharedlibextension]
<refsynopsisdiv>
<synopsis>
pg_connect -conninfo <parameter>connectOptions</parameter>
-pg_connect <parameter>dbName</parameter> <optional>-host <parameter>hostName</parameter></optional> <optional>-port <parameter>portNumber</parameter></optional> <optional>-tty <parameter>tty</parameter</optional> <optional>-options <parameter>serverOptions</parameter></optional>
+pg_connect <parameter>dbName</parameter> <optional role="tcl">-host <parameter>hostName</parameter></optional> <optional role="tcl">-port <parameter>portNumber</parameter></optional> <optional role="tcl">-tty <parameter>tty</parameter</optional> <optional role="tcl">-options <parameter>serverOptions</parameter></optional>
</synopsis>
</refsynopsisdiv>
@@ -612,7 +612,7 @@ pg_result <parameter>resultHandle</parameter> <parameter>resultOption</parameter
</varlistentry>
<varlistentry>
- <term><option>-assignbyidx <parameter>arrayName</> <optional><parameter>appendstr</></optional></option></term>
+ <term><option>-assignbyidx <parameter>arrayName</> <optional role="tcl"><parameter>appendstr</></optional></option></term>
<listitem>
<para>
Assign the results to an array using the values of the
@@ -839,7 +839,7 @@ pg_select $pgconn "SELECT * FROM table1;" array {
<refsynopsisdiv>
<synopsis>
-pg_execute <optional>-array <parameter>arrayVar</parameter></optional> <optional>-oid <parameter>oidVar</parameter></optional> <parameter>conn</parameter> <parameter>commandString</parameter> <optional><parameter>procedure</parameter></optional>
+pg_execute <optional role="tcl">-array <parameter>arrayVar</parameter></optional> <optional role="tcl">-oid <parameter>oidVar</parameter></optional> <parameter>conn</parameter> <parameter>commandString</parameter> <optional role="tcl"><parameter>procedure</parameter></optional>
</synopsis>
</refsynopsisdiv>
@@ -1020,7 +1020,7 @@ pg_execute $pgconn "SELECT max(value) AS max, min(value) AS min FROM mytable;"
<refsynopsisdiv>
<synopsis>
-pg_listen <parameter>conn</parameter> <parameter>notifyName</parameter> <optional><parameter>callbackCommand</parameter></optional>
+pg_listen <parameter>conn</parameter> <parameter>notifyName</parameter> <optional role="tcl"><parameter>callbackCommand</parameter></optional>
</synopsis>
</refsynopsisdiv>
@@ -1120,7 +1120,7 @@ pg_listen <parameter>conn</parameter> <parameter>notifyName</parameter> <optiona
<refsynopsisdiv>
<synopsis>
-pg_on_connection_loss <parameter>conn</parameter> <optional><parameter>callbackCommand</parameter></optional>
+pg_on_connection_loss <parameter>conn</parameter> <optional role="tcl"><parameter>callbackCommand</parameter></optional>
</synopsis>
</refsynopsisdiv>
diff --git a/doc/src/sgml/notation.sgml b/doc/src/sgml/notation.sgml
index 263a2c27d4c..0f9c27862b8 100644
--- a/doc/src/sgml/notation.sgml
+++ b/doc/src/sgml/notation.sgml
@@ -1,70 +1,47 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.22 2003/03/25 16:15:37 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.23 2003/09/08 23:02:28 petere Exp $
-->
<sect1 id="notation">
- <title>Terminology and Notation</title>
+ <title>Conventions</title>
<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.
+ This book uses the following typographical conventions to mark
+ certain portions of test: new terms, foreign phrases, and other
+ important passages are emphasized in <emphasis>italics</>.
+ Everything that represents input or output of the computer, in
+ particular commands, program code, and screen output, is shown in a
+ monospaced front (<literal>example</literal>). Within such
+ passages, italics (<replaceable>example</replaceable>) indicate,
+ that you must insert an actual value instead of the placeholder. On
+ occasion, parts of program code are emphasized in bold face
+ (<emphasis role="bold"><literal>example</></>), if they have been
+ added or changed since the preceding example.
</para>
<para>
- We use <filename>/usr/local/pgsql/</filename> 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 <xref linkend="installation">.
+ The following conventions are used in the synopsis of a command:
+ brackets (<literal>[</literal> and <literal>]</literal>) indicate
+ optional parts. (In the synopsis of a Tcl command, question marks
+ (<literal>?</>) are used instead, as is usual in Tcl.) Braces
+ (<literal>{</literal> and <literal>}</literal>) and vertical lines
+ (<literal>|</literal>) indicate that you must choose one
+ alternative. Dots (<literal>...</>) mean that the preceding element
+ can be repeated.
</para>
<para>
- In a command synopsis, brackets
- (<literal>[</literal> and <literal>]</literal>) indicate an optional phrase or keyword.
- Anything in braces
- (<literal>{</literal> and <literal>}</literal>) and containing vertical bars
- (<literal>|</literal>)
- indicates that you must choose one alternative.
+ Where it enhances the clarity, SQL commands are preceded by the
+ prompt <literal>=></>, and shell commands are preceded by the
+ prompt <literal>$</>. Normally, prompts are not shown, though.
</para>
<para>
- Examples will show commands executed from various accounts and programs.
- Commands executed from a Unix shell may be preceded with a dollar sign
- (<quote><literal>$</literal></quote>). Commands executed from particular user
- accounts such as <systemitem>root</> or <systemitem>postgres</> are specially flagged and explained.
- <acronym>SQL</acronym> commands may be preceded with
- <quote><literal>=></literal></quote>
- or will have no leading prompt, depending on the context.
+ 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>
-
- <note>
- <para>
- The notation for
- flagging commands is not universally consistent throughout the
- documentation set.
- Please report problems to the documentation mailing list
- <email>pgsql-docs@postgresql.org</email>.
- </para>
- </note>
-
</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:
--->
diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml
index 76b4e962085..c8b55ac4e75 100644
--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.25 2003/08/31 17:32:19 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.26 2003/09/08 23:02:28 petere Exp $
-->
<chapter id="pltcl">
@@ -235,7 +235,7 @@ CREATE FUNCTION overpaid(employee) RETURNS boolean AS '
<variablelist>
<varlistentry>
- <term><function>spi_exec</function> <literal>?-count <replaceable>n</replaceable>? ?-array <replaceable>name</replaceable>? <replaceable>command</replaceable> ?<replaceable>loop-body</replaceable>?</literal></term>
+ <term><literal><function>spi_exec</function> <optional role="tcl">-count <replaceable>n</replaceable></optional> <optional role="tcl">-array <replaceable>name</replaceable></optional> <replaceable>command</replaceable> <optional role="tcl"><replaceable>loop-body</replaceable></optional></literal></term>
<listitem>
<para>
Executes an SQL command given as a string. An error in the command
@@ -329,7 +329,7 @@ spi_exec -array C "SELECT * FROM pg_class" {
</varlistentry>
<varlistentry>
- <term><function>spi_execp</> <literal>?-count <replaceable>n</replaceable>? ?-array <replaceable>name</replaceable>? ?-nulls <replaceable>string</replaceable>? <replaceable>queryid</replaceable> ?<replaceable>value-list</replaceable>? ?<replaceable>loop-body</replaceable>?</literal></term>
+ <term><literal><function>spi_execp</> <optional role="tcl">-count <replaceable>n</replaceable></optional> <optional role="tcl">-array <replaceable>name</replaceable></optional> <optional role="tcl">-nulls <replaceable>string</replaceable></optional> <replaceable>queryid</replaceable> <optional role="tcl"><replaceable>value-list</replaceable></optional> <optional role="tcl"><replaceable>loop-body</replaceable></optional></literal></term>
<listitem>
<para>
Executes a query previously prepared with <function>spi_prepare</>.
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 4c1188c5009..9f9fa36ecde 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.54 2003/09/01 23:01:49 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.55 2003/09/08 23:02:28 petere Exp $
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
@@ -21,15 +21,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.54 2003/09/01 23:01:49 pe
&legal;
</bookinfo>
- <preface id="preface">
- <title>Preface</title>
-
- &intro;
- &history;
- ¬ation;
- &problems;
-
- </preface>
+ &intro;
<part id="tutorial">
<title>Tutorial</title>
diff --git a/doc/src/sgml/stylesheet.dsl b/doc/src/sgml/stylesheet.dsl
index 52e43edc781..b364075dcb7 100644
--- a/doc/src/sgml/stylesheet.dsl
+++ b/doc/src/sgml/stylesheet.dsl
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/stylesheet.dsl,v 1.23 2003/03/25 16:15:38 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/stylesheet.dsl,v 1.24 2003/09/08 23:02:28 petere Exp $ -->
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!-- must turn on one of these with -i on the jade command line -->
@@ -62,6 +62,38 @@
(element type ($mono-seq$))
(element (programlisting emphasis) ($bold-seq$)) ;; to highlight sections of code
+;; Special support for Tcl synopses
+(element optional
+ (if (equal? (attribute-string (normalize "role")) "tcl")
+ (make sequence
+ (literal "?")
+ ($charseq$)
+ (literal "?"))
+ (make sequence
+ (literal %arg-choice-opt-open-str%)
+ ($charseq$)
+ (literal %arg-choice-opt-close-str%))))
+
+;; Avoid excessive cross-reference labels
+(define (auto-xref-indirect? target ancestor)
+ (cond
+; ;; Always add indirect references to another book
+; ((member (gi ancestor) (book-element-list))
+; #t)
+ ;; Add indirect references to the section or component a block
+ ;; is in iff chapters aren't autolabelled. (Otherwise "Figure 1-3"
+ ;; is sufficient)
+ ((and (member (gi target) (block-element-list))
+ (not %chapter-autolabel%))
+ #t)
+ ;; Add indirect references to the component a section is in if
+ ;; the sections are not autolabelled
+ ((and (member (gi target) (section-element-list))
+ (member (gi ancestor) (component-element-list))
+ (not %section-autolabel%))
+ #t)
+ (else #f)))
+
;; Bibliography things
@@ -110,11 +142,6 @@
(element issn
(make sequence
(literal "ISSN ")
- (process-children)))
-
- (element pagenums
- (make sequence
- (literal "p. ")
(process-children))))
@@ -137,6 +164,7 @@
<![ %output-html; [
(define %section-autolabel% #t)
+(define %label-preface-sections% #f)
(define %generate-legalnotice-link% #t)
(define %html-ext% ".html")
(define %root-filename% "index")
@@ -144,6 +172,8 @@
(define %use-id-as-filename% #t)
(define %stylesheet% "stylesheet.css")
(define %graphic-default-extension% "gif")
+(define %gentext-nav-use-ff% #t)
+(define %body-attr% '())
;; Returns the depth of auto TOC that should be made at the nd-level
(define (toc-depth nd)
--
GitLab