From 6de93c0529cd0b15824eb4ebbd273d69af926357 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut 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 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 | 237 ++++++++++++++++------------ doc/src/sgml/libpgtcl.sgml | 10 +- doc/src/sgml/notation.sgml | 89 ++++------- doc/src/sgml/pltcl.sgml | 6 +- doc/src/sgml/postgres.sgml | 12 +- doc/src/sgml/stylesheet.dsl | 42 ++++- 8 files changed, 360 insertions(+), 483 deletions(-) diff --git a/doc/src/sgml/history.sgml b/doc/src/sgml/history.sgml index 6e64f7e602..07b96ce6f4 100644 --- a/doc/src/sgml/history.sgml +++ b/doc/src/sgml/history.sgml @@ -1,182 +1,181 @@ A Brief History of <productname>PostgreSQL</productname> + + history + of PostgreSQL + + - The object-relational database management system now known as - PostgreSQL (and briefly called - Postgres95) is derived from the - POSTGRES package written at the University of - California at Berkeley. With over a decade of - development behind it, PostgreSQL - 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 + PostgreSQL is derived from the + POSTGRES package written at the + University of California at Berkeley. With over a decade of + development behind it, PostgreSQL is now + the most advanced open-source database available anywhere. - + The Berkeley <productname>POSTGRES</productname> Project + + POSTGRES + + - Implementation of the POSTGRES - DBMS began in 1986. The - initial concepts for the system were presented in - - and the definition of the initial data model - appeared in - . - The design of the rule system at - that time was described in - . - The rationale - and architecture of the storage manager were detailed in - . + The POSTGRES project, led by Professor + Michael Stonebraker, was sponsored by the Defense Advanced Research + Projects Agency (DARPA), the Army Research + Office (ARO), the National Science Foundation + (NSF), and ESL, Inc. The implementation of + POSTGRES began in 1986. The initial + concepts for the system were presented in + and the definition of the initial data model appeared in . The design of the rule system at that time was + described in . The rationale and + architecture of the storage manager were detailed in . - Postgres has undergone several major releases since - then. The first demoware system became operational - in 1987 and was shown at the 1988 ACM-SIGMOD - Conference. Version 1, described in - , was released - to a few external users in June 1989. In response to a - critique of the first rule system - (), - the rule - system was redesigned - () - 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 Postgres95 (see below) - focused on portability and reliability. + POSTGRES has undergone several major + releases since then. The first demoware system + became operational in 1987 and was shown at the 1988 + ACM-SIGMOD Conference. Version 1, described in + , was released to a few external users in + June 1989. In response to a critique of the first rule system + (), the rule system was redesigned () 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 Postgres95 (see below) focused on + portability and reliability. - POSTGRES 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. - POSTGRES has also been - used as an educational tool at several universities. - Finally, - Illustra Information Technologies (later merged into - Informix, - which is now owned by IBM.) - picked up - the code and commercialized it. - POSTGRES became the primary data manager - for the - Sequoia 2000 - scientific computing project in late 1992. + POSTGRES 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. + POSTGRES has also been used as an + educational tool at several universities. Finally, Illustra + Information Technologies (later merged into Informix, + which is now owned by IBM.) picked up the code and + commercialized it. In late 1992, + POSTGRES became the primary data manager + for the Sequoia + 2000 scientific computing project. - 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 - POSTGRES 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 + POSTGRES project officially ended with + Version 4.2. - + <productname>Postgres95</productname> + + Postgres95 + + - In 1994, Andrew Yu and Jolly Chen - added a SQL language interpreter to POSTGRES. + In 1994, Andrew Yu and Jolly Chen added a SQL language interpreter + to POSTGRES. Under a new name, Postgres95 was subsequently released to - the Web to find its own way in the world as an - open-source descendant of the original POSTGRES + the web to find its own way in the world as an open-source + descendant of the original POSTGRES Berkeley code. - Postgres95 code was completely - ANSI C and trimmed in size by 25%. Many - internal changes improved performance and maintainability. - Postgres95 release 1.0.x ran about 30-50% - faster on the Wisconsin Benchmark compared to - POSTGRES, Version 4.2. - Apart from bug fixes, the following were the major enhancements: + Postgres95 code was completely ANSI C + and trimmed in size by 25%. Many internal changes improved + performance and + maintainability. Postgres95 release + 1.0.x ran about 30-50% faster on the Wisconsin Benchmark compared + to POSTGRES, Version 4.2. Apart from + bug fixes, the following were the major enhancements: The query language PostQUEL was replaced with - SQL (implemented in the server). - Subqueries were not supported until - PostgreSQL (see below), but they - could be imitated in Postgres95 with user-defined - SQL functions. Aggregates were - re-implemented. Support for the GROUP BY query clause was also added. - The libpq interface remained - available for C - programs. + SQL (implemented in the server). Subqueries + were not supported until PostgreSQL + (see below), but they could be imitated in + Postgres95 with user-defined + SQL functions. Aggregate functions were + re-implemented. Support for the GROUP BY + query clause was also added. In addition to the monitor program, a new program - (psql) was provided for interactive SQL queries - using GNU Readline. + (psql) was provided for interactive + SQL queries, which used GNU + Readline. - A new front-end library, libpgtcl, - supported Tcl-based clients. A sample shell, - pgtclsh, provided new Tcl commands to interface - Tcl - programs with the Postgres95 backend. + A new front-end library, libpgtcl, + supported Tcl-based clients. A sample shell, + pgtclsh, provided new Tcl commands to + interface Tcl programs with the + Postgres95 server. - 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.) - 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. - A short tutorial introducing regular SQL features as - well as those of Postgres95 was - distributed with the source code + A short tutorial introducing regular SQL + features as well as those of + Postgres95 was distributed with the + source code - GNU make (instead of BSD make) was used - for the build. Also, Postgres95 could be - compiled with an unpatched GCC - (data alignment of doubles was fixed). + GNU make (instead of BSD + make) was used for the build. Also, + Postgres95 could be compiled with an + unpatched GCC (data alignment of + doubles was fixed). @@ -187,83 +186,28 @@ $Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.20 2003/01/19 00:13:28 mom <productname>PostgreSQL</productname> - By 1996, it became clear that the name Postgres95 would - not stand the test of time. We chose a new name, + By 1996, it became clear that the name Postgres95 + would not stand the test of time. We chose a new name, PostgreSQL, to reflect the relationship - between the original POSTGRES and the more - recent versions with SQL 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 - POSTGRES project. + between the original POSTGRES and the + more recent versions with SQL 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 POSTGRES project. - The emphasis during development of Postgres95 - was on identifying and understanding existing problems in the backend code. - With PostgreSQL, - the emphasis has shifted to augmenting features and capabilities, although - work continues in all areas. + The emphasis during development of + Postgres95 was on identifying and + understanding existing problems in the server code. With + PostgreSQL, the emphasis has shifted to + augmenting features and capabilities, although work continues in + all areas. - Major enhancements in PostgreSQL include: + Details about what has happened in PostgreSQL since then can be + found in . - - - - - 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 pg_dump while the database stays available for - queries. - - - - - - Important backend features, including subselects, defaults, - constraints, and triggers, have been implemented. - - - - - - Additional SQL92-compliant language features have been added, - including primary keys, quoted identifiers, literal string type coercion, - type casting, and binary and hexadecimal integer input. - - - - - - Built-in types have been improved, including new wide-range date/time types - and additional geometric type support. - - - - - - 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. - - - - - diff --git a/doc/src/sgml/info.sgml b/doc/src/sgml/info.sgml index 62d754d133..73e1d854d8 100644 --- a/doc/src/sgml/info.sgml +++ b/doc/src/sgml/info.sgml @@ -1,104 +1,21 @@ - Overview of Documentation Resources + Further Information - The PostgreSQL documentation is organized into - several books: + Besides the documentation, that is, this book, there are other + resources about PostgreSQL: - - &cite-tutorial; - - - An informal introduction for new users. - - - - - - &cite-user; - - - Documents the SQL query language environment, - including data types and functions, as well as user-level - performance tuning. Every PostgreSQL user - should read this. - - - - - - &cite-admin; - - - Installation and server management information. Everyone who - runs a PostgreSQL server, either for personal - use or for other users, needs to read this. - - - - - - &cite-programmer; - - - Advanced information for application programmers. Topics include - type and function extensibility, library interfaces, and - application design issues. - - - - - - &cite-reference; - - - Reference pages for SQL command syntax, and - client and server programs. This book is auxiliary to the - User's, Administrator's, and Programmer's Guides. - - - - - - &cite-developer; - - - Information for PostgreSQL - developers. This is intended for those who are contributing to - the PostgreSQL project; application - development information appears in the &cite-programmer;. - - - - - - - - In addition to this manual set, there are other resources to help you with - PostgreSQL installation and use: - - - - man pages - - - The &cite-reference;'s pages in the traditional Unix man - format. There is no difference in content. - - - - FAQs - Frequently Asked Questions (FAQ) lists document both general issues - and some platform-specific issues. + The FAQ list FAQ-Liste contains + continuously updated answers to frequently asked questions. @@ -107,7 +24,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.18 2003/01/19 00:13:28 momjia READMEs - README files are available for some contributed packages. + README files are available for some + contributed packages. @@ -118,8 +36,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.18 2003/01/19 00:13:28 momjia The PostgreSQL - web site carries details on the latest release, upcoming - features, and other information to make your work or play with + web site carries details on the latest release and other + information to make your work or play with PostgreSQL more productive. @@ -131,10 +49,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.18 2003/01/19 00:13:28 momjia 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 User's - Lounge section of the PostgreSQL - web site for details. + the developers. Consult the PostgreSQL web site + for details. @@ -143,41 +59,18 @@ $Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.18 2003/01/19 00:13:28 momjia Yourself! - PostgreSQL is an open-source effort. + PostgreSQL is an open-source project. As such, it depends on the user community for ongoing support. As you begin to use PostgreSQL, 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. - - - - 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 pgsql-docs@postgresql.org 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. - - diff --git a/doc/src/sgml/intro.sgml b/doc/src/sgml/intro.sgml index ba5653f155..c547c7a880 100644 --- a/doc/src/sgml/intro.sgml +++ b/doc/src/sgml/intro.sgml @@ -1,110 +1,151 @@ - - What is <productname>PostgreSQL</productname>? + + Preface - - PostgreSQL is an object-relational - database management system (ORDBMS) based on - - POSTGRES, Version 4.2, - developed at the University of California at Berkeley Computer - Science Department. The POSTGRES - project, led by Professor Michael Stonebraker, was sponsored by - the Defense Advanced Research Projects Agency - (DARPA), the Army Research Office - (ARO), the National Science Foundation - (NSF), and ESL, Inc. - + + 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. + - - PostgreSQL is an open-source descendant of - this original Berkeley code. It provides SQL92/SQL99 language support - and other modern features. - + + 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: - - POSTGRES pioneered many of the - object-relational concepts now becoming available in some commercial - databases. - Traditional relational database management systems - (RDBMS) 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 Spartan simplicity. - However, this simplicity makes the - implementation of certain applications very difficult. - PostgreSQL offers substantial additional - power by incorporating the following additional - concepts in such a way that users can easily - extend the system: + + + + is an informal introduction for new users. + + - - - inheritance - - - data types - - - functions - - - + + + documents the SQL query + language environment, including data types and functions, as well + as user-level performance tuning. Every + PostgreSQL user should read this. + + - - Other features provide additional power and flexibility: + + + 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. + + - - - constraints - - - triggers - - - rules - - - transactional integrity - - - + + + describes the programming + interfaces for PostgreSQL client programs. + + - - These features put PostgreSQL into the - category of databases referred to as - object-relational. Note that this is distinct - from those referred to as object-oriented, - which in general are not as well suited to supporting - traditional relational database languages. - So, although PostgreSQL has some - object-oriented features, it is firmly in the relational database - world. In fact, some commercial databases have recently - incorporated features pioneered by PostgreSQL. - - + + + contains information for + advanced users about the extensibility capabilities of the + server. Topics are, for instance, user-defined data types and + functions. + + - + + + 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. + + + + + + + What is <productname>PostgreSQL</productname>? + + + PostgreSQL is an object-relational + database management system (ORDBMS) based on + + POSTGRES, Version 4.2, 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. + + + + PostgreSQL is an open-source descendant + of this original Berkeley code. It supports SQL92 and SQL99 and + offers many modern features: + + + + complex queries + + + foreign keys + + + triggers + + + views + + + transactional integrity + + + multiversion concurrency control + + + + Also, PostgreSQL can be extended by the user in many ways, for + example by adding new + + + + data types + + + functions + + + operators + + + aggregate functions + + + index methods + + + procedural languages + + + + + + 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. + + + + &history; + ¬ation; + &info; + &problems; + + diff --git a/doc/src/sgml/libpgtcl.sgml b/doc/src/sgml/libpgtcl.sgml index afcc7061ed..70bf66806e 100644 --- a/doc/src/sgml/libpgtcl.sgml +++ b/doc/src/sgml/libpgtcl.sgml @@ -201,7 +201,7 @@ load libpgtcl[info sharedlibextension] pg_connect -conninfo connectOptions -pg_connect dbName -host hostName -port portNumber -tty tty -options serverOptions +pg_connect dbName -host hostName -port portNumber -tty tty -options serverOptions @@ -612,7 +612,7 @@ pg_result resultHandle resultOption - + Assign the results to an array using the values of the @@ -839,7 +839,7 @@ pg_select $pgconn "SELECT * FROM table1;" array { -pg_execute -array arrayVar -oid oidVar conn commandString procedure +pg_execute -array arrayVar -oid oidVar conn commandString procedure @@ -1020,7 +1020,7 @@ pg_execute $pgconn "SELECT max(value) AS max, min(value) AS min FROM mytable;" -pg_listen conn notifyName callbackCommand +pg_listen conn notifyName callbackCommand @@ -1120,7 +1120,7 @@ pg_listen conn notifyName -pg_on_connection_loss conn callbackCommand +pg_on_connection_loss conn callbackCommand diff --git a/doc/src/sgml/notation.sgml b/doc/src/sgml/notation.sgml index 263a2c27d4..0f9c27862b 100644 --- a/doc/src/sgml/notation.sgml +++ b/doc/src/sgml/notation.sgml @@ -1,9 +1,40 @@ - Terminology and Notation + Conventions + + + This book uses the following typographical conventions to mark + certain portions of test: new terms, foreign phrases, and other + important passages are emphasized in italics. + Everything that represents input or output of the computer, in + particular commands, program code, and screen output, is shown in a + monospaced front (example). Within such + passages, italics (example) indicate, + that you must insert an actual value instead of the placeholder. On + occasion, parts of program code are emphasized in bold face + (example), if they have been + added or changed since the preceding example. + + + + The following conventions are used in the synopsis of a command: + brackets ([ and ]) indicate + optional parts. (In the synopsis of a Tcl command, question marks + (?) are used instead, as is usual in Tcl.) Braces + ({ and }) and vertical lines + (|) indicate that you must choose one + alternative. Dots (...) mean that the preceding element + can be repeated. + + + + Where it enhances the clarity, SQL commands are preceded by the + prompt =>, and shell commands are preceded by the + prompt $. Normally, prompts are not shown, though. + An administrator is generally a person who is @@ -13,58 +44,4 @@ $Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.22 2003/03/25 16:15:37 pe be interpreted too narrowly; this documentation set does not have fixed presumptions about system administration procedures. - - - We use /usr/local/pgsql/ as the root - directory of the installation and /usr/local/pgsql/data - as the directory with the database files. These directories may vary - on your site, details can be derived in . - - - - In a command synopsis, brackets - ([ and ]) indicate an optional phrase or keyword. - Anything in braces - ({ and }) and containing vertical bars - (|) - indicates that you must choose one alternative. - - - - Examples will show commands executed from various accounts and programs. - Commands executed from a Unix shell may be preceded with a dollar sign - ($). Commands executed from particular user - accounts such as root or postgres are specially flagged and explained. - SQL commands may be preceded with - => - or will have no leading prompt, depending on the context. - - - - - The notation for - flagging commands is not universally consistent throughout the - documentation set. - Please report problems to the documentation mailing list - pgsql-docs@postgresql.org. - - - - - diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml index 76b4e96208..c8b55ac4e7 100644 --- a/doc/src/sgml/pltcl.sgml +++ b/doc/src/sgml/pltcl.sgml @@ -1,5 +1,5 @@ @@ -235,7 +235,7 @@ CREATE FUNCTION overpaid(employee) RETURNS boolean AS ' - spi_exec ?-count n? ?-array name? command ?loop-body? + spi_exec -count n -array name command loop-body 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" { - spi_execp ?-count n? ?-array name? ?-nulls string? queryid ?value-list? ?loop-body? + spi_execp -count n -array name -nulls string queryid value-list loop-body Executes a query previously prepared with spi_prepare. diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 4c1188c500..9f9fa36ecd 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -1,5 +1,5 @@ - - Preface - - &intro; - &history; - ¬ation; - &problems; - - + &intro; Tutorial diff --git a/doc/src/sgml/stylesheet.dsl b/doc/src/sgml/stylesheet.dsl index 52e43edc78..b364075dcb 100644 --- a/doc/src/sgml/stylesheet.dsl +++ b/doc/src/sgml/stylesheet.dsl @@ -1,4 +1,4 @@ - + @@ -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 @@