More minor updates and copy-editing.

doc/src/sgml/arch-dev.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/arch-dev.sgml,v 2.24 2003/11/29 19:51:36 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/arch-dev.sgml,v 2.25 2005/01/05 23:42:02 tgl Exp $
 -->
 
  <chapter id="overview">
@@ -63,11 +63,11 @@ $PostgreSQL: pgsql/doc/src/sgml/arch-dev.sgml,v 2.24 2003/11/29 19:51:36 pgsql E
       <firstterm>system catalogs</firstterm>) to apply to 
       the query tree.  It performs the
       transformations given in the <firstterm>rule bodies</firstterm>.
-      One application of the rewrite system is in the realization of
-      <firstterm>views</firstterm>.
      </para>
 
      <para>
+      One application of the rewrite system is in the realization of
+      <firstterm>views</firstterm>.
       Whenever a query against a view
       (i.e. a <firstterm>virtual table</firstterm>) is made,
       the rewrite system rewrites the user's query to
@@ -90,8 +90,8 @@ $PostgreSQL: pgsql/doc/src/sgml/arch-dev.sgml,v 2.24 2003/11/29 19:51:36 pgsql E
       relation to be scanned, there are two paths for the
       scan. One possibility is a simple sequential scan and the other
       possibility is to use the index. Next the cost for the execution of
-      each plan is estimated and the
+      each path is estimated and the cheapest path is chosen.  The cheapest
-      cheapest plan is chosen and handed back.
+      path is expanded into a complete plan that the executor can use.
      </para>
     </step>
 
@@ -142,7 +142,8 @@ $PostgreSQL: pgsql/doc/src/sgml/arch-dev.sgml,v 2.24 2003/11/29 19:51:36 pgsql E
     <productname>PostgreSQL</productname> protocol described in
     <xref linkend="protocol">.  Many clients are based on the
     C-language library <application>libpq</>, but several independent
-    implementations exist, such as the Java <application>JDBC</> driver.
+    implementations of the protocol exist, such as the Java
+    <application>JDBC</> driver.
    </para>
 
    <para>
@@ -339,7 +340,7 @@ $PostgreSQL: pgsql/doc/src/sgml/arch-dev.sgml,v 2.24 2003/11/29 19:51:36 pgsql E
     different ways, each of which will produce the same set of
     results.  If it is computationally feasible, the query optimizer
     will examine each of these possible execution plans, ultimately
-    selecting the execution plan that will run the fastest.
+    selecting the execution plan that is expected to run the fastest.
    </para>
 
    <note>
@@ -355,20 +356,26 @@ $PostgreSQL: pgsql/doc/src/sgml/arch-dev.sgml,v 2.24 2003/11/29 19:51:36 pgsql E
    </note>
 
    <para>
-    After the cheapest path is determined, a <firstterm>plan tree</>
+    The planner's search procedure actually works with data structures
-    is built to pass to the executor.  This represents the desired
+    called <firstterm>paths</>, which are simply cut-down representations of
-    execution plan in sufficient detail for the executor to run it.
+    plans containing only as much information as the planner needs to make
+    its decisions. After the cheapest path is determined, a full-fledged
+    <firstterm>plan tree</> is built to pass to the executor.  This represents
+    the desired execution plan in sufficient detail for the executor to run it.
+    In the rest of this section we'll ignore the distinction between paths
+    and plans.
    </para>
 
    <sect2>
     <title>Generating Possible Plans</title>
 
     <para>
-     The planner/optimizer decides which plans should be generated
+     The planner/optimizer starts by generating plans for scanning each
-     based upon the types of indexes defined on the relations appearing in
+     individual relation (table) used in the query.  The possible plans
-     a query. There is always the possibility of performing a
+     are determined by the available indexes on each relation.
-     sequential scan on a relation, so a plan using only
+     There is always the possibility of performing a
-     sequential scans is always created. Assume an index is defined on a
+     sequential scan on a relation, so a sequential scan plan is always
+     created. Assume an index is defined on a
      relation (for example a B-tree index) and a query contains the
      restriction
      <literal>relation.attribute OPR constant</literal>. If
@@ -408,9 +415,12 @@ $PostgreSQL: pgsql/doc/src/sgml/arch-dev.sgml,v 2.24 2003/11/29 19:51:36 pgsql E
        <para>
         <firstterm>merge sort join</firstterm>: Each relation is sorted on the join
         attributes before the join starts. Then the two relations are
-	merged together taking into account that both relations are
+        scanned in parallel, and matching rows are combined to form
-	ordered on the join attributes. This kind of join is more
+        join rows. This kind of join is more
         attractive because each relation has to be scanned only once.
+        The required sorting may be achieved either by an explicit sort
+        step, or by scanning the relation in the proper order using an
+        index on the join key.
        </para>
       </listitem>
 
@@ -426,6 +436,13 @@ $PostgreSQL: pgsql/doc/src/sgml/arch-dev.sgml,v 2.24 2003/11/29 19:51:36 pgsql E
      </itemizedlist>
     </para>
 
+    <para>
+     When the query involves more than two relations, the final result
+     must be built up by a tree of join steps, each with two inputs.
+     The planner examines different possible join sequences to find the
+     cheapest one.
+    </para>
+
     <para>
      The finished plan tree consists of sequential or index scans of
      the base relations, plus nested-loop, merge, or hash join nodes as
@@ -512,7 +529,7 @@ $PostgreSQL: pgsql/doc/src/sgml/arch-dev.sgml,v 2.24 2003/11/29 19:51:36 pgsql E
     the executor top level uses this information to create a new updated row
     and mark the old row deleted.  For <command>DELETE</>, the only column
     that is actually returned by the plan is the TID, and the executor top
-    level simply uses the TID to visit the target rows and mark them deleted.
+    level simply uses the TID to visit each target row and mark it deleted.
    </para>
 
   </sect1>

doc/src/sgml/bki.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/bki.sgml,v 1.12 2003/11/29 19:51:36 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/bki.sgml,v 1.13 2005/01/05 23:42:03 tgl Exp $
  -->
 
 <chapter id="bki">
@@ -7,10 +7,11 @@ $PostgreSQL: pgsql/doc/src/sgml/bki.sgml,v 1.12 2003/11/29 19:51:36 pgsql Exp $
 
  <para>
   Backend Interface (<acronym>BKI</acronym>) files are scripts in a
-  special language that are input to the
+  special language that is understood by the
-  <productname>PostgreSQL</productname> backend running in the special
+  <productname>PostgreSQL</productname> backend when running in the
-  <quote>bootstrap</quote> mode that allows it to perform database
+  <quote>bootstrap</quote> mode.  The bootstrap mode allows system catalogs
-  functions without a database system already existing.
+  to be created and filled from scratch, whereas ordinary SQL commands
+  require the catalogs to exist already.
   <acronym>BKI</acronym> files can therefore be used to create the
   database system in the first place.  (And they are probably not
   useful for anything else.)
@@ -21,8 +22,9 @@ $PostgreSQL: pgsql/doc/src/sgml/bki.sgml,v 1.12 2003/11/29 19:51:36 pgsql Exp $
   to do part of its job when creating a new database cluster.  The
   input file used by <application>initdb</application> is created as
   part of building and installing <productname>PostgreSQL</productname>
-  by a program named <filename>genbki.sh</filename> from some
+  by a program named <filename>genbki.sh</filename>, which reads some
-  specially formatted C header files in the source tree.  The created
+  specially formatted C header files in the <filename>src/include/catalog/</>
+  directory of the source tree.  The created
   <acronym>BKI</acronym> file is called <filename>postgres.bki</filename> and is
   normally installed in the
   <filename>share</filename> subdirectory of the installation tree.
@@ -40,9 +42,7 @@ $PostgreSQL: pgsql/doc/src/sgml/bki.sgml,v 1.12 2003/11/29 19:51:36 pgsql Exp $
    This section describes how the <productname>PostgreSQL</productname>
    backend interprets <acronym>BKI</acronym> files.  This description
    will be easier to understand if the <filename>postgres.bki</filename>
-   file is at hand as an example.  You should also study the source
+   file is at hand as an example.
-   code of <application>initdb</application> to get an idea of how the
-   backend is invoked.
   </para>
 
   <para>
@@ -67,6 +67,61 @@ $PostgreSQL: pgsql/doc/src/sgml/bki.sgml,v 1.12 2003/11/29 19:51:36 pgsql Exp $
   <title><acronym>BKI</acronym> Commands</title>
 
   <variablelist>
+   <varlistentry>
+    <term>
+     create 
+     <optional>bootstrap</optional>
+     <optional>shared_relation</optional>
+     <optional>without_oids</optional>
+     <replaceable class="parameter">tablename</replaceable>
+     (<replaceable class="parameter">name1</replaceable> =
+     <replaceable class="parameter">type1</replaceable> <optional>,
+     <replaceable class="parameter">name2</replaceable> = <replaceable
+     class="parameter">type2</replaceable>, ...</optional>)
+    </term>
+
+    <listitem>
+     <para>
+      Create a table named <replaceable
+      class="parameter">tablename</replaceable> with the columns given
+      in parentheses.
+     </para>
+
+     <para>
+      The following column types are supported directly by
+      <filename>bootstrap.c</>: <type>bool</type>,
+      <type>bytea</type>, <type>char</type> (1 byte),
+      <type>name</type>, <type>int2</type>,
+      <type>int4</type>, <type>regproc</type>, <type>regclass</type>,
+      <type>regtype</type>, <type>text</type>,
+      <type>oid</type>, <type>tid</type>, <type>xid</type>,
+      <type>cid</type>, <type>int2vector</type>, <type>oidvector</type>,
+      <type>_int4</type> (array), <type>_text</type> (array),
+      <type>_aclitem</type> (array).  Although it is possible to create
+      tables containing columns of other types, this cannot be done until
+      after <structname>pg_type</> has been created and filled with
+      appropriate entries.
+     </para>
+
+     <para>
+      When <literal>bootstrap</> is specified,
+      the table will only be created on disk; nothing is entered into
+      <structname>pg_class</structname>,
+      <structname>pg_attribute</structname>, etc, for it.  Thus the
+      table will not be accessible by ordinary SQL operations until
+      such entries are made the hard way (with <literal>insert</>
+      commands).  This option is used for creating
+      <structname>pg_class</structname> etc themselves.
+     </para>
+
+     <para>
+      The table is created as shared if <literal>shared_relation</> is
+      specified.
+      It will have OIDs unless <literal>without_oids</> is specified.
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term>
      open <replaceable class="parameter">tablename</replaceable>
@@ -98,51 +153,6 @@ $PostgreSQL: pgsql/doc/src/sgml/bki.sgml,v 1.12 2003/11/29 19:51:36 pgsql Exp $
     </listitem>
    </varlistentry>
 
-   <varlistentry>
-    <term>
-     create <replaceable class="parameter">tablename</replaceable>
-     (<replaceable class="parameter">name1</replaceable> =
-     <replaceable class="parameter">type1</replaceable> <optional>,
-     <replaceable class="parameter">name2</replaceable> = <replaceable
-     class="parameter">type2</replaceable>, ...</optional>)
-    </term>
-
-    <listitem>
-     <para>
-      Create a table named <replaceable
-      class="parameter">tablename</replaceable> with the columns given
-      in parentheses.
-     </para>
-
-     <para>
-      The <replaceable>type</replaceable> is not necessarily the data
-      type that the column will have in the SQL environment; that is
-      determined by the <structname>pg_attribute</structname> system
-      catalog.  The type here is essentially only used to allocate
-      storage.  The following types are allowed: <type>bool</type>,
-      <type>bytea</type>, <type>char</type> (1 byte),
-      <type>name</type>, <type>int2</type>, <type>int2vector</type>,
-      <type>int4</type>, <type>regproc</type>, <type>regclass</type>,
-      <type>regtype</type>, <type>text</type>,
-      <type>oid</type>, <type>tid</type>, <type>xid</type>,
-      <type>cid</type>, <type>oidvector</type>, <type>smgr</type>,
-      <type>_int4</type> (array), <type>_aclitem</type> (array).
-      Array types can also be indicated by writing
-      <literal>[]</literal> after the name of the element type.
-     </para>
-
-     <note>
-      <para>
-       The table will only be created on disk, it will not
-       automatically be registered in the system catalogs and will
-       therefore not be accessible unless appropriate rows are
-       inserted in <structname>pg_class</structname>,
-       <structname>pg_attribute</structname>, etc.
-      </para>
-     </note>
-    </listitem>
-   </varlistentry>
-
    <varlistentry>
     <term>
      insert <optional>OID = <replaceable class="parameter">oid_value</replaceable></optional> (<replaceable class="parameter">value1</replaceable> <replaceable class="parameter">value2</replaceable> ...)
@@ -190,6 +200,8 @@ $PostgreSQL: pgsql/doc/src/sgml/bki.sgml,v 1.12 2003/11/29 19:51:36 pgsql Exp $
       classes to use are <replaceable
       class="parameter">opclass1</replaceable>, <replaceable
       class="parameter">opclass2</replaceable> etc., respectively.
+      The index file is created and appropriate catalog entries are
+      made for it, but the index contents are not initialized by this command.
      </para>
     </listitem>
    </varlistentry>
@@ -199,7 +211,7 @@ $PostgreSQL: pgsql/doc/src/sgml/bki.sgml,v 1.12 2003/11/29 19:51:36 pgsql Exp $
 
     <listitem>
      <para>
-      Build the indices that have previously been declared.
+      Fill in the indices that have previously been declared.
      </para>
     </listitem>
    </varlistentry>
@@ -212,7 +224,7 @@ $PostgreSQL: pgsql/doc/src/sgml/bki.sgml,v 1.12 2003/11/29 19:51:36 pgsql Exp $
 
   <para>
    The following sequence of commands will create the
-   <literal>test_table</literal> table with the two columns
+   table <literal>test_table</literal> with two columns
    <literal>cola</literal> and <literal>colb</literal> of type
    <type>int4</type> and <type>text</type>, respectively, and insert
    two rows into the table.

doc/src/sgml/catalogs.sgml

@@ -1,6 +1,6 @@
 <!--
  Documentation of the system catalogs, directed toward PostgreSQL developers
- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.94 2004/12/13 18:05:07 petere Exp $
+ $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.95 2005/01/05 23:42:03 tgl Exp $
  -->
 
 <chapter id="catalogs">
@@ -33,7 +33,7 @@
    Most system catalogs are copied from the template database during
    database creation and are thereafter database-specific. A few
    catalogs are physically shared across all databases in a cluster;
-   these are marked in the descriptions of the individual catalogs.
+   these are noted in the descriptions of the individual catalogs.
   </para>
 
   <table id="catalog-table">
@@ -85,7 +85,7 @@
 
      <row>
       <entry><link linkend="catalog-pg-class"><structname>pg_class</structname></link></entry>
-      <entry>tables, indexes, sequences (<quote>relations</quote>)</entry>
+      <entry>tables, indexes, sequences, views (<quote>relations</quote>)</entry>
      </row>
 
      <row>
@@ -663,6 +663,14 @@
    </tgroup>
   </table>
 
+   <para>
+    The <structfield>adsrc</structfield> field is historical, and is best
+    not used, because it does not track outside changes that might affect
+    the representation of the default value.  Reverse-compiling the
+    <structfield>adbin</structfield> field (with <function>pg_get_expr</> for
+    example) is a better way to display the default value.
+   </para>
+
  </sect1>
 
 
@@ -678,7 +686,8 @@
    table columns.  There will be exactly one
    <structname>pg_attribute</structname> row for every column in every
    table in the database.  (There will also be attribute entries for
-   indexes and other objects.  See <structname>pg_class</structname>.)
+   indexes, and indeed all objects that have <structname>pg_class</structname>
+   entries.)
   </para>
 
   <para>
@@ -728,7 +737,7 @@
       <entry>
        <structfield>attstattarget</structfield> controls the level of detail
        of statistics accumulated for this column by
-       <command>ANALYZE</command>.
+       <xref linkend="sql-analyze" endterm="sql-analyze-title">.
        A zero value indicates that no statistics should be collected.
        A negative value says to use the system default statistics target.
        The exact meaning of positive values is data type-dependent.
@@ -878,6 +887,17 @@
     </tbody>
    </tgroup>
   </table>
+
+  <para>
+   In a dropped column's <structname>pg_attribute</structname> entry,
+   <structfield>atttypid</structfield> is reset to zero, but 
+   <structfield>attlen</structfield> and the other fields copied from
+   <structname>pg_type</> are still valid.  This arrangement is needed
+   to cope with the situation where the dropped column's data type was
+   later dropped, and so there is no <structname>pg_type</> row anymore.
+   <structfield>attlen</structfield> and the other fields can be used
+   to interpret the contents of a row of the table.
+  </para>
  </sect1>
 
 
@@ -1230,8 +1250,8 @@
       <entry><structfield>relhasrules</structfield></entry>
       <entry><type>bool</type></entry>
       <entry></entry>
-      <entry>Table has rules; see
+      <entry>True if table has rules; see
-       <structname>pg_rewrite</structname> catalog
+       <structname>pg_rewrite</structname> catalog.
       </entry>
      </row>
 
@@ -1239,7 +1259,7 @@
       <entry><structfield>relhassubclass</structfield></entry>
       <entry><type>bool</type></entry>
       <entry></entry>
-      <entry>At least one table inherits from this one</entry>
+      <entry>True if table has (or once had) any inheritance children.</entry>
      </row>
 
      <row>
@@ -1247,9 +1267,10 @@
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
       <entry>
-       Access privileges; see the descriptions of
+       Access privileges; see
-       <command>GRANT</command> and <command>REVOKE</command> for
+       <xref linkend="sql-grant" endterm="sql-grant-title"> and
-       details.
+       <xref linkend="sql-revoke" endterm="sql-revoke-title">
+       for details.
       </entry>
      </row>
     </tbody>
@@ -1432,8 +1453,10 @@
   </indexterm>
 
   <para>
-   The catalog <structname>pg_conversion</structname> stores encoding conversion information. See
+   The catalog <structname>pg_conversion</structname> describes the
-   <command>CREATE CONVERSION</command> for more information.
+   available encoding conversion procedures.  See
+   <xref linkend="sql-createconversion" endterm="sql-createconversion-title">
+   for more information.
   </para>
 
   <table>
@@ -1643,7 +1666,12 @@
       <entry><structfield>datacl</structfield></entry>
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
-      <entry>Access privileges</entry>
+      <entry>
+       Access privileges; see
+       <xref linkend="sql-grant" endterm="sql-grant-title"> and
+       <xref linkend="sql-revoke" endterm="sql-revoke-title">
+       for details.
+      </entry>
      </row>
     </tbody>
    </tgroup>
@@ -1827,8 +1855,8 @@
   </indexterm>
 
   <para>
-   The catalog <structname>pg_description</> can store an optional description or
+   The catalog <structname>pg_description</> stores optional descriptions
-   comment for each database object.  Descriptions can be manipulated
+   (comments) for each database object.  Descriptions can be manipulated
    with the <command>COMMENT</command> command and viewed with
    <application>psql</application>'s <literal>\d</literal> commands.
    Descriptions of many built-in system objects are provided in the initial
@@ -2081,7 +2109,9 @@
 
   <para>
    The catalog <structname>pg_inherits</> records information about
-   table inheritance hierarchies.
+   table inheritance hierarchies.  There is one entry for each direct
+   child table in the database.  (Indirect inheritance can be determined
+   by following chains of entries.)
   </para>
 
   <table>
@@ -2121,7 +2151,7 @@
       <entry><type>int4</type></entry>
       <entry></entry>
       <entry>
-       If there is more than one parent for a child table (multiple
+       If there is more than one direct parent for a child table (multiple
        inheritance), this number tells the order in which the
        inherited columns are to be arranged.  The count starts at 1.
       </entry>
@@ -2141,10 +2171,10 @@
   </indexterm>
 
   <para>
-   The catalog <structname>pg_language</structname> registers call interfaces or
+   The catalog <structname>pg_language</structname> registers
    languages in which you can write functions or stored procedures.
-   See under <command>CREATE LANGUAGE</command> and in
+   See <xref linkend="sql-createlanguage" endterm="sql-createlanguage-title">
-   <xref linkend="xplang"> for more information about language handlers.
+   and <xref linkend="xplang"> for more information about language handlers.
   </para>
 
   <table>
@@ -2165,7 +2195,7 @@
       <entry><structfield>lanname</structfield></entry>
       <entry><type>name</type></entry>
       <entry></entry>
-      <entry>Name of the language (to be specified when creating a function)</entry>
+      <entry>Name of the language</entry>
      </row>
 
      <row>
@@ -2186,8 +2216,7 @@
       <entry><type>bool</type></entry>
       <entry></entry>
       <entry>
-       This is a trusted language.  See under <command>CREATE
+       This is a trusted language.  If this is an internal
-       LANGUAGE</command> what this means.  If this is an internal
        language (<structfield>lanispl</structfield> is false) then
        this column is meaningless.
       </entry>
@@ -2212,8 +2241,7 @@
       <entry>
        This references a language validator function that is responsible
        for checking the syntax and validity of new functions when they
-       are created. See under <command>CREATE LANGUAGE</command> for
+       are created.  Zero if no validator is provided.
-       further information about validators.
       </entry>
      </row>
 
@@ -2221,7 +2249,12 @@
       <entry><structfield>lanacl</structfield></entry>
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
-      <entry>Access privileges</entry>
+      <entry>
+       Access privileges; see
+       <xref linkend="sql-grant" endterm="sql-grant-title"> and
+       <xref linkend="sql-revoke" endterm="sql-revoke-title">
+       for details.
+      </entry>
      </row>
     </tbody>
    </tgroup>
@@ -2309,8 +2342,10 @@
   </indexterm>
 
   <para>
-   The catalog <structname>pg_listener</structname> supports the <command>LISTEN</>
+   The catalog <structname>pg_listener</structname> supports the
-   and <command>NOTIFY</> commands.  A listener creates an entry in
+   <xref linkend="sql-listen" endterm="sql-listen-title"> and
+   <xref linkend="sql-notify" endterm="sql-notify-title">
+   commands.  A listener creates an entry in
    <structname>pg_listener</structname> for each notification name
    it is listening for.  A notifier scans <structname>pg_listener</structname>
    and updates each matching entry to show that a notification has occurred.
@@ -2410,7 +2445,12 @@
       <entry><structfield>nspacl</structfield></entry>
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
-      <entry>Access privileges</entry>
+      <entry>
+       Access privileges; see
+       <xref linkend="sql-grant" endterm="sql-grant-title"> and
+       <xref linkend="sql-revoke" endterm="sql-revoke-title">
+       for details.
+      </entry>
      </row>
     </tbody>
    </tgroup>
@@ -2528,9 +2568,9 @@
   </indexterm>
 
   <para>
-   The catalog <structname>pg_operator</> stores information about operators.  See
+   The catalog <structname>pg_operator</> stores information about operators.
-   <command>CREATE OPERATOR</command> and <xref linkend="xoper"> for
+   See <xref linkend="sql-createoperator" endterm="sql-createoperator-title">
-   details on these operator parameters.
+   and <xref linkend="xoper"> for more information.
   </para>
 
   <table>
@@ -2703,9 +2743,8 @@
 
   <para>
    The catalog <structname>pg_proc</> stores information about functions (or procedures).
-   The description of <command>CREATE FUNCTION</command> and
+   See <xref linkend="sql-createfunction" endterm="sql-createfunction-title">
-   <xref linkend="xfunc"> contain more information about the meaning of
+   and <xref linkend="xfunc"> for more information.
-   some columns.
   </para>
 
   <para>
@@ -2869,16 +2908,21 @@
       <entry><structfield>proacl</structfield></entry>
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
-      <entry>Access privileges</entry>
+      <entry>
+       Access privileges; see
+       <xref linkend="sql-grant" endterm="sql-grant-title"> and
+       <xref linkend="sql-revoke" endterm="sql-revoke-title">
+       for details.
+      </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
 
   <para>
+   For compiled functions, both built-in and dynamically loaded,
    <structfield>prosrc</structfield> contains the function's C-language
-   name (link symbol) for compiled functions, both built-in and
+   name (link symbol).  For all other currently-known language types,
-   dynamically loaded.  For all other language types,
    <structfield>prosrc</structfield> contains the function's source
    text.  <structfield>probin</structfield> is unused except for
    dynamically-loaded C functions, for which it gives the name of the
@@ -3041,7 +3085,7 @@
       <entry><structfield>usesysid</structfield></entry>
       <entry><type>int4</type></entry>
       <entry></entry>
-      <entry>User id (arbitrary number used to reference this user)</entry>
+      <entry>User ID (arbitrary number used to reference this user)</entry>
      </row>
 
      <row>
@@ -3072,14 +3116,14 @@
       <entry><structfield>passwd</structfield></entry>
       <entry><type>text</type></entry>
       <entry></entry>
-      <entry>Password</entry>
+      <entry>Password (possibly encrypted)</entry>
      </row>
 
      <row>
       <entry><structfield>valuntil</structfield></entry>
       <entry><type>abstime</type></entry>
       <entry></entry>
-      <entry>Account expiry time (only used for password authentication)</entry>
+      <entry>Password expiry time (only used for password authentication)</entry>
      </row>
 
      <row>
@@ -3311,7 +3355,12 @@
       <entry><structfield>spcacl</structfield></entry>
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
-      <entry>Access privileges</entry>
+      <entry>
+       Access privileges; see
+       <xref linkend="sql-grant" endterm="sql-grant-title"> and
+       <xref linkend="sql-revoke" endterm="sql-revoke-title">
+       for details.
+      </entry>
      </row>
     </tbody>
    </tgroup>
@@ -3327,8 +3376,9 @@
   </indexterm>
 
   <para>
-   The catalog <structname>pg_trigger</structname> stores triggers on tables.  See under
+   The catalog <structname>pg_trigger</structname> stores triggers on tables.
-   <command>CREATE TRIGGER</command> for more information.
+   See <xref linkend="sql-createtrigger" endterm="sql-createtrigger-title">
+   for more information.
   </para>
 
   <table>
@@ -3443,8 +3493,8 @@
 
   <note>
    <para>
-    <literal>pg_class.reltriggers</literal> needs to match up with the
+    <literal>pg_class.reltriggers</literal> needs to agree with the
-    entries in this table.
+    number of triggers found in this table for the given relation.
    </para>
   </note>
 
@@ -3459,12 +3509,14 @@
   </indexterm>
 
   <para>
-   The catalog <structname>pg_type</structname> stores information about data types.  Base types
+   The catalog <structname>pg_type</structname> stores information about data
-   (scalar types) are created with <command>CREATE TYPE</command>.
+   types.  Base types (scalar types) are created with
+   <xref linkend="sql-createtype" endterm="sql-createtype-title">, and
+   domains with
+   <xref linkend="sql-createdomain" endterm="sql-createdomain-title">.
    A composite type is automatically created for each table in the database, to
    represent the row structure of the table.  It is also possible to create
-   composite types with <command>CREATE TYPE AS</command> and
+   composite types with <command>CREATE TYPE AS</command>.
-   domains with <command>CREATE DOMAIN</command>.
   </para>
 
   <table>
@@ -3797,17 +3849,9 @@
 
   <para>
    In addition to the system catalogs, <productname>PostgreSQL</productname>
-   provides a number of built-in views.  The system views provide convenient
+   provides a number of built-in views.  Some system views provide convenient
-   access to some commonly used queries on the system catalogs.  Some of these
+   access to some commonly used queries on the system catalogs.  Other views
-   views provide access to internal server state, as well.
+   provide access to internal server state.
-  </para>
-
-  <para>
-   <xref linkend="view-table"> lists the system views described here.
-   More detailed documentation of each view follows below.
-   There are some additional views that provide access to the results of
-   the statistics collector; they are described in <xref
-   linkend="monitoring-stats-views-table">.
   </para>
 
   <para>
@@ -3819,6 +3863,14 @@
    the information you need.
   </para>
 
+  <para>
+   <xref linkend="view-table"> lists the system views described here.
+   More detailed documentation of each view follows below.
+   There are some additional views that provide access to the results of
+   the statistics collector; they are described in <xref
+   linkend="monitoring-stats-views-table">.
+  </para>
+
   <para>
    Except where noted, all the views described here are read-only.
   </para>
@@ -4398,7 +4450,7 @@
    and <structfield>histogram_bounds</> arrays can be set on a
    column-by-column basis using the <command>ALTER TABLE SET STATISTICS</>
    command, or globally by setting the
-   <varname>default_statistics_target</varname> runtime parameter.
+   <xref linkend="guc-default-statistics-target"> runtime parameter.
   </para>
 
  </sect1>
@@ -4515,7 +4567,7 @@
       <entry><structfield>usesysid</structfield></entry>
       <entry><type>int4</type></entry>
       <entry></entry>
-      <entry>User id (arbitrary number used to reference this user)</entry>
+      <entry>User ID (arbitrary number used to reference this user)</entry>
      </row>
 
      <row>
@@ -4553,7 +4605,7 @@
       <entry><structfield>valuntil</structfield></entry>
       <entry><type>abstime</type></entry>
       <entry></entry>
-      <entry>Account expiry time (only used for password authentication)</entry>
+      <entry>Password expiry time (only used for password authentication)</entry>
      </row>
 
      <row>

doc/src/sgml/geqo.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/geqo.sgml,v 1.26 2003/11/29 19:51:37 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/geqo.sgml,v 1.27 2005/01/05 23:42:03 tgl Exp $
 Genetic Optimizer
 -->
 
@@ -65,8 +65,7 @@ Genetic Optimizer
     enormous amount of time and memory space when the number of joins
     in the query grows large. This makes the ordinary
     <productname>PostgreSQL</productname> query optimizer
-    inappropriate for database application domains that involve the
+    inappropriate for queries that join a large number of tables.
-    need for extensive queries, such as artificial intelligence.
    </para>
 
    <para>
@@ -97,7 +96,7 @@ Genetic Optimizer
    <para>
     The genetic algorithm (<acronym>GA</acronym>) is a heuristic optimization method which
     operates through
-    determined, randomized search. The set of possible solutions for the
+    nondeterministic, randomized search. The set of possible solutions for the
     optimization problem is considered as a
     <firstterm>population</firstterm> of <firstterm>individuals</firstterm>.
     The degree of adaptation of an individual to its environment is specified
@@ -176,11 +175,12 @@ Genetic Optimizer
    <title>Genetic Query Optimization (<acronym>GEQO</acronym>) in PostgreSQL</title>
 
    <para>
-    The <acronym>GEQO</acronym> module is intended for the solution of the query
+    The <acronym>GEQO</acronym> module approaches the query
-    optimization problem similar to a traveling salesman problem (<acronym>TSP</acronym>).
+    optimization problem as though it were the well-known traveling salesman
+    problem (<acronym>TSP</acronym>).
     Possible query plans are encoded as integer strings. Each string
     represents the join order from one relation of the query to the next.
-    E. g., the query tree
+    For example, the join tree
 <literallayout class="monospaced">
    /\
   /\ 2
@@ -245,7 +245,8 @@ Genetic Optimizer
      <para>
       Work is still needed to improve the genetic algorithm parameter
       settings.
-      In file <filename>backend/optimizer/geqo/geqo_params.c</filename>, routines
+      In file <filename>src/backend/optimizer/geqo/geqo_main.c</filename>,
+      routines
       <function>gimme_pool_size</function> and <function>gimme_number_generations</function>,
       we have to find a compromise for the parameter settings
       to satisfy two competing demands:
@@ -263,11 +264,20 @@ Genetic Optimizer
       </itemizedlist>
      </para>
 
+     <para>
+      At a more basic level, it is not clear that solving query optimization
+      with a GA algorithm designed for TSP is appropriate.  In the TSP case,
+      the cost associated with any substring (partial tour) is independent
+      of the rest of the tour, but this is certainly not true for query
+      optimization.  Thus it is questionable whether edge recombination
+      crossover is the most effective mutation procedure.
+     </para>
+
    </sect2>
   </sect1>
 
  <sect1 id="geqo-biblio">
-  <title>Further Readings</title>
+  <title>Further Reading</title>
 
   <para>
    The following resources contain additional information about

doc/src/sgml/plhandler.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/plhandler.sgml,v 1.3 2004/12/30 21:45:36 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/plhandler.sgml,v 1.4 2005/01/05 23:42:03 tgl Exp $
 -->
 
  <chapter id="plhandler">
@@ -56,11 +56,11 @@ $PostgreSQL: pgsql/doc/src/sgml/plhandler.sgml,v 1.3 2004/12/30 21:45:36 tgl Exp
     system table
     <classname>pg_proc</classname> and to analyze the argument
     and return types of the called function. The <literal>AS</> clause from the
-    <command>CREATE FUNCTION</command> of the function will be found
+    <command>CREATE FUNCTION</command> command for the function will be found
     in the <literal>prosrc</literal> column of the
-    <classname>pg_proc</classname> row. This may be the source
+    <classname>pg_proc</classname> row. This is commonly source
-    text in the procedural language itself (like for PL/Tcl), a
+    text in the procedural language, but in theory it could be something else,
-    path name to a file, or anything else that tells the call handler
+    such as a path name to a file, or anything else that tells the call handler
     what to do in detail.
    </para>