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.

Add User's Guide chapters on Data Definition and Data Manipulation.
6f4a9fb1 · Peter Eisentraut · 15fe086f · 6f4a9fb1 · 6f4a9fb1 · 6f4a9fb1
Commit 6f4a9fb1 authored 22 years ago by Peter Eisentraut
--- 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

--- a/doc/src/sgml/array.sgml
+++ b/doc/src/sgml/array.sgml
-<!-- $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>
--- 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;
 ]>
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
 <!--
-$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

--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
-<!-- $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">

--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
 <!--
-$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>

--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
 <!--
-$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">

--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
-<!-- $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>


--- a/doc/src/sgml/stylesheet.dsl
+++ b/doc/src/sgml/stylesheet.dsl
-<!-- $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% "    ")

--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
 <!--
-$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>

--- a/doc/src/sgml/user.sgml
+++ b/doc/src/sgml/user.sgml
 <!--
-$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;