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 <comment>s show up in the output while the version number ends in
"devel".

Allow cross-book references with entities &cite-user; etc.

diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 76e15524108c3a876ad97ee27cedaa6cab6d8100..e20cdfc177e563c87707ed5bae2a2dd8e582855e 100644 (file)
--- 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 4dbca08002226f04f240f5f9abd54bab7d5aa573..aeb238d63ba1760e067183ba6945cda0e8fa6125 100644 (file)
--- a/doc/src/sgml/array.sgml
+++ b/doc/src/sgml/array.sgml
@@ -1,6 +1,6 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.20 2002/03/17 19:59:57 tgl Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.21 2002/08/05 19:43:30 petere Exp $ -->
 
-<chapter id="arrays">
+<sect1 id="arrays">
  <title>Arrays</title>
 
  <indexterm>
@@ -325,4 +325,4 @@ INSERT ... VALUES ('{"\\\\","\\""}');
   </para>
  </tip>
 
-</chapter>
+</sect1>

diff --git a/doc/src/sgml/book-decl.sgml b/doc/src/sgml/book-decl.sgml
index 4992fb202ef686309b38db2271771e158ce2684a..61043a1b4121ad1052de0c48e588736a981fc545 100644 (file)
--- a/doc/src/sgml/book-decl.sgml
+++ b/doc/src/sgml/book-decl.sgml
@@ -8,4 +8,6 @@
 <!entity % set-of-books "IGNORE">
 <!entity % single-book "INCLUDE">
 
+<!entity % entities SYSTEM "entities.sgml">
+%entities;
 ]>

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index cc50815059a97aa7d44be82c651bfe655d313da5..ce735827b4047711e2b1ce491dd1cf03b76131b9 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.96 2002/07/16 17:05:46 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.97 2002/08/05 19:43:30 petere Exp $
 -->
 
  <chapter id="datatype">
@@ -3093,6 +3093,8 @@ SELECT SUBSTRING(b FROM 1 FOR 2) FROM test;
 
   </sect1>
 
+  &array;
+
  </chapter>
 
 <!-- Keep this comment at the end of the file

diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index d6fdd71561b6fa7a901a9a4d8c4f24ccb1924b71..e767bd173f99d69625941c11c6b04dafd95ee31b 100644 (file)
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.20 2002/07/30 19:36:10 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.21 2002/08/05 19:43:31 petere Exp $ -->
 
 <!entity history    SYSTEM "history.sgml">
 <!entity info       SYSTEM "info.sgml">
@@ -23,10 +23,11 @@
 <!entity array      SYSTEM "array.sgml">
 <!entity datatype   SYSTEM "datatype.sgml">
 <!entity datetime   SYSTEM "datetime.sgml">
+<!entity ddl        SYSTEM "ddl.sgml">
+<!entity dml        SYSTEM "dml.sgml">
 <!entity features   SYSTEM "features.sgml">
 <!entity func       SYSTEM "func.sgml">
 <!entity indices    SYSTEM "indices.sgml">
-<!entity inherit    SYSTEM "inherit.sgml">
 <!entity keywords   SYSTEM "keywords.sgml">
 <!entity manage     SYSTEM "manage.sgml">
 <!entity mvcc       SYSTEM "mvcc.sgml">

diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index 7c65bb353052b7bb6376808773e742be79253abe..d6c59fd665b2d50e7fbb265345caf03363d07e75 100644 (file)
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -1,9 +1,9 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.25 2002/05/30 20:45:18 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.26 2002/08/05 19:43:31 petere Exp $
 -->
 
  <chapter id="mvcc">
-  <title>Multiversion Concurrency Control</title>
+  <title>Concurrency Control</title>
 
   <indexterm>
    <primary>concurrency</primary>

diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 37d2f052d66d7317d47cfacb860b95ac87593dcf..9d2f14dbbbd2ce1290578c0ab1f7139a6e84b3fc 100644 (file)
--- 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.47 2001/11/21 05:53:41 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.48 2002/08/05 19:43:31 petere Exp $
 -->
 
 <!doctype set PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
@@ -12,6 +12,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.47 2001/11/21 05:53:41 th
 <!entity % set-of-books "INCLUDE">
 <!entity % single-book "IGNORE">
 
+<!entity % entities SYSTEM "entities.sgml">
+%entities;
+
 <!entity admin      SYSTEM "admin.sgml">
 <!entity developer  SYSTEM "developer.sgml">
 <!entity programmer SYSTEM "programmer.sgml">

diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index 66bb25a3af1ef9622d25cb547093a502b9758cf6..da321eadaf50fc14bf5ed4cc8b869de80d552236 100644 (file)
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -1,16 +1,22 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/queries.sgml,v 1.15 2002/04/25 20:14:43 tgl Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/queries.sgml,v 1.16 2002/08/05 19:43:31 petere Exp $ -->
 
 <chapter id="queries">
  <title>Queries</title>
 
+ <para>
+  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.
+ </para>
+
  <sect1 id="queries-overview">
   <title>Overview</title>
 
  <para>
-  A <firstterm>query</firstterm> is the process of retrieving or the command
-  to retrieve data from a database.  In SQL the <command>SELECT</command>
-  command is used to specify queries.  The general syntax of the
-  <command>SELECT</command> command is
+  The process of retrieving or the command to retrieve data from a
+  database is called a <firstterm>query</firstterm>.  In SQL the
+  <command>SELECT</command> command is used to specify queries.  The
+  general syntax of the <command>SELECT</command> command is
 <synopsis>
 SELECT <replaceable>select_list</replaceable> FROM <replaceable>table_expression</replaceable> <optional><replaceable>sort_specification</replaceable></optional>
 </synopsis>
@@ -114,14 +120,14 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
     <para>
      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.
     </para>
 
     <variablelist>
      <title>Join Types</title>
 
      <varlistentry>
-      <term>CROSS JOIN</term>
+      <term>Cross-join</term>
 
       <indexterm>
        <primary>joins</primary>
@@ -244,7 +250,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
           <para>
            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.
           </para>
@@ -258,7 +264,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
           <para>
            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.
           </para>
@@ -460,7 +466,7 @@ WHERE <replaceable>search_condition</replaceable>
     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 <replaceable>select_list</replaceable> ...
 
    <para>
     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.
    </para>
 

diff --git a/doc/src/sgml/stylesheet.dsl b/doc/src/sgml/stylesheet.dsl
index 44b6c0399d682898b3db3068661ab90ecf7eaf23..6da17b003aa02b7977f7594d32fee38d275fd65d 100644 (file)
--- 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.20 2002/06/01 20:56:00 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/stylesheet.dsl,v 1.21 2002/08/05 19:43:31 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 -->
@@ -28,6 +28,8 @@
 
 <!-- (applicable to all output formats) -->
 
+(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 fb727a8433c7887b31b2aeb89bb243f29c9a524f..90f33bfd0ff7dceec512dc36dc6876191693699b 100644 (file)
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.63 2002/06/15 22:15:03 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.64 2002/08/05 19:43:31 petere Exp $
 -->
 
 <chapter id="sql-syntax">
@@ -10,11 +10,18 @@ $Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.63 2002/06/15 22:15:03 tgl
   <secondary>SQL</secondary>
  </indexterm>
 
-  <abstract>
-   <para>
-    This chapter describes the syntax of SQL.
-   </para>
-  </abstract>
+ <para>
+  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.
+ </para>
+
+ <para>
+  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 <productname>PostgreSQL</productname>.
+ </para>
 
  <sect1 id="sql-syntax-lexical">
   <title>Lexical Structure</title>
@@ -798,7 +805,7 @@ SELECT (5 !) - 6;
  </sect1>
 
  <sect1 id="sql-naming">
-  <title>Schemas and naming conventions</title>
+  <title>Schemas and Naming Conventions</title>
 
      <indexterm>
       <primary>schemas</primary>
@@ -831,6 +838,9 @@ SELECT (5 !) - 6;
     </para>
    </note>
 
+  <sect2>
+   <title>Schema Object Names</title>
+
    <para>
     A database contains one or more named <firstterm>schemas</>, which
     in turn contain tables.  Schemas also contain other kinds of named
@@ -944,6 +954,7 @@ SELECT 3 OPERATOR(pg_catalog.+) 4;
     place <literal>pg_catalog</> at the end of your search path if you
     prefer to have user-defined names override built-in names.
    </para>
+  </sect2>
 
   <sect2 id="sql-reserved-names">
    <title>Reserved names</title>

diff --git a/doc/src/sgml/user.sgml b/doc/src/sgml/user.sgml
index 79ed594ff7eff9223c9a1c074afdb00be322e0a5..22127be7556da5083fa9ccd23d6f1f8f7e8a8b23 100644 (file)
--- a/doc/src/sgml/user.sgml
+++ b/doc/src/sgml/user.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.30 2002/06/15 02:59:55 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.31 2002/08/05 19:43:31 petere Exp $
 -->
 
 <book id="user">
@@ -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;