diff options
| -rw-r--r-- | doc/src/sgml/history.sgml | 306 | ||||
| -rw-r--r-- | doc/src/sgml/info.sgml | 141 | ||||
| -rw-r--r-- | doc/src/sgml/intro.sgml | 255 | ||||
| -rw-r--r-- | doc/src/sgml/libpgtcl.sgml | 10 | ||||
| -rw-r--r-- | doc/src/sgml/notation.sgml | 83 | ||||
| -rw-r--r-- | doc/src/sgml/pltcl.sgml | 6 | ||||
| -rw-r--r-- | doc/src/sgml/postgres.sgml | 12 | ||||
| -rw-r--r-- | 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) |