From 6f4a9fb1197b7e758c5da61b3b0077c55c2b6754 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Mon, 5 Aug 2002 19:43:31 +0000 Subject: [PATCH] Add User's Guide chapters on Data Definition and Data Manipulation. Still needs to be filled with more information, but it gives us a framework to have a User's Guide with complete coverage of the basic SQL operations. Move arrays into data type chapter, inheritance into DDL chapter (for now). Make s show up in the output while the version number ends in "devel". Allow cross-book references with entities &cite-user; etc. --- doc/src/sgml/Makefile | 7 ++++++- doc/src/sgml/array.sgml | 6 +++--- doc/src/sgml/book-decl.sgml | 2 ++ doc/src/sgml/datatype.sgml | 4 +++- doc/src/sgml/filelist.sgml | 5 +++-- doc/src/sgml/mvcc.sgml | 4 ++-- doc/src/sgml/postgres.sgml | 5 ++++- doc/src/sgml/queries.sgml | 28 +++++++++++++++++----------- doc/src/sgml/stylesheet.dsl | 10 ++++++---- doc/src/sgml/syntax.sgml | 25 ++++++++++++++++++------- doc/src/sgml/user.sgml | 6 +++--- 11 files changed, 67 insertions(+), 35 deletions(-) diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index 76e1552410..e20cdfc177 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -8,7 +8,7 @@ # # # IDENTIFICATION -# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.50 2002/04/14 17:23:20 petere Exp $ +# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.51 2002/08/05 19:43:30 petere Exp $ # #---------------------------------------------------------------------------- @@ -58,6 +58,11 @@ ifdef DOCBOOKSTYLE CATALOG = -c $(DOCBOOKSTYLE)/catalog endif +# Enable draft mode during development +ifneq (,$(findstring devel, $(VERSION))) +JADEFLAGS += -V draft-mode +endif + ## ## Man pages diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml index 4dbca08002..aeb238d63b 100644 --- a/doc/src/sgml/array.sgml +++ b/doc/src/sgml/array.sgml @@ -1,6 +1,6 @@ - + - + Arrays @@ -325,4 +325,4 @@ INSERT ... VALUES ('{"\\\\","\\""}'); - + diff --git a/doc/src/sgml/book-decl.sgml b/doc/src/sgml/book-decl.sgml index 4992fb202e..61043a1b41 100644 --- a/doc/src/sgml/book-decl.sgml +++ b/doc/src/sgml/book-decl.sgml @@ -8,4 +8,6 @@ + +%entities; ]> diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index cc50815059..ce735827b4 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -1,5 +1,5 @@ @@ -3093,6 +3093,8 @@ SELECT SUBSTRING(b FROM 1 FOR 2) FROM test; + &array; + + @@ -23,10 +23,11 @@ + + - diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml index 7c65bb3530..d6c59fd665 100644 --- a/doc/src/sgml/mvcc.sgml +++ b/doc/src/sgml/mvcc.sgml @@ -1,9 +1,9 @@ - Multiversion Concurrency Control + Concurrency Control concurrency diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 37d2f052d6..9d2f14dbbb 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -1,5 +1,5 @@ + +%entities; + diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index 66bb25a3af..da321eadaf 100644 --- a/doc/src/sgml/queries.sgml +++ b/doc/src/sgml/queries.sgml @@ -1,16 +1,22 @@ - + Queries + + The previous chapters explained how to create tables, how to fill + them with data, and how to manipulate that data. Now we finally + discuss how to retrieve the data out of the database. + + Overview - A query is the process of retrieving or the command - to retrieve data from a database. In SQL the SELECT - command is used to specify queries. The general syntax of the - SELECT command is + The process of retrieving or the command to retrieve data from a + database is called a query. In SQL the + SELECT command is used to specify queries. The + general syntax of the SELECT command is SELECT select_list FROM table_expression sort_specification @@ -114,14 +120,14 @@ FROM table_reference , table_r A joined table is a table derived from two other (real or derived) tables according to the rules of the particular join - type. INNER, OUTER, and CROSS JOIN are supported. + type. Inner, outer, and cross-joins are available. Join Types - CROSS JOIN + Cross-join joins @@ -244,7 +250,7 @@ FROM table_reference , table_r First, an INNER JOIN is performed. Then, for each row in T1 that does not satisfy the join condition with any row in - T2, a joined row is returned with NULL values in columns of + T2, a joined row is returned with null values in columns of T2. Thus, the joined table unconditionally has at least one row for each row in T1. @@ -258,7 +264,7 @@ FROM table_reference , table_r First, an INNER JOIN is performed. Then, for each row in T2 that does not satisfy the join condition with any row in - T1, a joined row is returned with NULL values in columns of + T1, a joined row is returned with null values in columns of T1. This is the converse of a left join: the result table will unconditionally have a row for each row in T2. @@ -460,7 +466,7 @@ WHERE search_condition After the processing of the FROM clause is done, each row of the derived table is checked against the search condition. If the result of the condition is true, the row is kept in the output - table, otherwise (that is, if the result is false or NULL) it is + table, otherwise (that is, if the result is false or null) it is discarded. The search condition typically references at least some column in the table generated in the FROM clause; this is not required, but otherwise the WHERE clause will be fairly useless. @@ -735,7 +741,7 @@ SELECT DISTINCT select_list ... Obviously, two rows are considered distinct if they differ in at - least one column value. NULLs are considered equal in this + least one column value. Null values are considered equal in this comparison. diff --git a/doc/src/sgml/stylesheet.dsl b/doc/src/sgml/stylesheet.dsl index 44b6c0399d..6da17b003a 100644 --- a/doc/src/sgml/stylesheet.dsl +++ b/doc/src/sgml/stylesheet.dsl @@ -1,4 +1,4 @@ - + @@ -28,6 +28,8 @@ +(define draft-mode #f) + (define pgsql-docs-list "pgsql-docs@postgresql.org") ;; Don't show manpage volume numbers @@ -37,9 +39,8 @@ ;; it needs extra work.) (define %callout-graphics% #f) -;; Don't show comments. (We ought to show them, at least during the -;; development stage.) -(define %show-comments% #f) +;; Show comments during the development stage. +(define %show-comments% draft-mode) ;; Don't append period if run-in title ends with any of these ;; characters. We had to add the colon here. This is fixed in @@ -57,6 +58,7 @@ (element structname ($mono-seq$)) (element symbol ($mono-seq$)) (element type ($mono-seq$)) +(element (programlisting emphasis) ($bold-seq$)) ;; to highlight sections of code ;; Indentation of verbatim environments (define %indent-programlisting-lines% " ") diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index fb727a8433..90f33bfd0f 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -1,5 +1,5 @@ @@ -10,11 +10,18 @@ $Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.63 2002/06/15 22:15:03 tgl SQL - - - This chapter describes the syntax of SQL. - - + + This chapter describes the syntax of SQL. It forms the foundation + for understanding the following chapters which will go into detail + about how the SQL commands are applied to define and modify data. + + + + We also advise users who are already familiar with SQL to read this + chapter carefully because there are several rules and concepts that + are implemented inconsistently among SQL databases or that are + specific to PostgreSQL. + Lexical Structure @@ -798,7 +805,7 @@ SELECT (5 !) - 6; - Schemas and naming conventions + Schemas and Naming Conventions schemas @@ -831,6 +838,9 @@ SELECT (5 !) - 6; + + Schema Object Names + A database contains one or more named schemas, which in turn contain tables. Schemas also contain other kinds of named @@ -944,6 +954,7 @@ SELECT 3 OPERATOR(pg_catalog.+) 4; place pg_catalog at the end of your search path if you prefer to have user-defined names override built-in names. + Reserved names diff --git a/doc/src/sgml/user.sgml b/doc/src/sgml/user.sgml index 79ed594ff7..22127be755 100644 --- a/doc/src/sgml/user.sgml +++ b/doc/src/sgml/user.sgml @@ -1,5 +1,5 @@ @@ -16,13 +16,13 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.30 2002/06/15 02:59:55 &intro; &syntax; + &ddl; + &dml; &queries; &datatype; &func; &typeconv; - &array; &indices; - &inherit; &mvcc; &manage; &perform; -- 2.40.0