Some more small improvements in response to 7.4 interactive docs comments.

doc/src/sgml/ecpg.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.61 2005/01/07 05:43:28 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.62 2005/01/08 22:13:25 tgl Exp $
 -->
 
 <chapter id="ecpg">
@@ -1106,7 +1106,8 @@ struct
     the error message that is stored in
     <literal>sqlca.sqlerrm.sqlerrmc</literal> (the result of
     <function>strlen()</function>, not really interesting for a C
-    programmer).
+    programmer).  Note that some messages are too long to fit in the
+    fixed-size <literal>sqlerrmc</literal> array; they will be truncated.
    </para>
 
    <para>

doc/src/sgml/gist.sgml

@@ -1,14 +1,22 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/gist.sgml,v 1.14 2003/11/29 19:51:37 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/gist.sgml,v 1.15 2005/01/08 22:13:25 tgl Exp $
 -->
 
-<chapter Id="GiST">
+<chapter id="GiST">
 <title>GiST Indexes</title>
 
 <sect1 id="intro">
  <title>Introduction</title>
 
  <para>
+   <indexterm>
+    <primary>index</primary>
+    <secondary>GiST</secondary>
+   </indexterm>
+   <indexterm>
+    <primary>GiST</primary>
+    <see>index</see>
+   </indexterm>
    <acronym>GiST</acronym> stands for Generalized Search Tree.  It is a
    balanced, tree-structured access method, that acts as a base template in
    which to implement arbitrary indexing schemes. B+-trees, R-trees and many

doc/src/sgml/indices.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.48 2004/12/23 23:07:38 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.49 2005/01/08 22:13:25 tgl Exp $ -->
 
 <chapter id="indexes">
  <title id="indexes-title">Indexes</title>
@@ -106,8 +106,13 @@ CREATE INDEX test1_id_index ON test1 (id);
 
   <para>
    <productname>PostgreSQL</productname> provides several index types:
-   B-tree, R-tree, GiST, and Hash.  Each index type uses a different
+   B-tree, R-tree, Hash, and GiST.  Each index type uses a different
    algorithm that is best suited to different types of queries.
+   By default, the <command>CREATE INDEX</command> command will create a
+   B-tree index, which fits the most common situations.
+  </para>
+
+  <para>
    <indexterm>
     <primary>index</primary>
     <secondary>B-tree</secondary>
@@ -116,21 +121,24 @@ CREATE INDEX test1_id_index ON test1 (id);
     <primary>B-tree</primary>
     <see>index</see>
    </indexterm>
-   By default, the <command>CREATE INDEX</command> command will create a
+   B-trees can handle equality and range queries on data that can be sorted
-   B-tree index, which fits the most common situations.  B-trees can
+   into some ordering.
-   handle equality and range queries on data that can be sorted into
+   In particular, the <productname>PostgreSQL</productname> query planner
-   some ordering.  In
-   particular, the <productname>PostgreSQL</productname> query planner
    will consider using a B-tree index whenever an indexed column is
    involved in a comparison using one of these operators:
 
-   <simplelist type="inline">
+   <simplelist>
     <member><literal>&lt;</literal></member>
     <member><literal>&lt;=</literal></member>
     <member><literal>=</literal></member>
     <member><literal>&gt;=</literal></member>
     <member><literal>&gt;</literal></member>
    </simplelist>
+
+   Constructs equivalent to combinations of these operators, such as
+   <literal>BETWEEN</> and <literal>IN</>, can also be implemented with
+   a B-tree index search.  (But note that <literal>IS NULL</> is not
+   equivalent to <literal>=</> and is not indexable.)
   </para>
 
   <para>
@@ -142,8 +150,8 @@ CREATE INDEX test1_id_index ON test1 (id);
    'foo%'</literal> or <literal>col ~ '^foo'</literal>, but not
    <literal>col LIKE '%bar'</literal>.  However, if your server does
    not use the C locale you will need to create the index with a
-   special operator class.  See <xref linkend="indexes-opclass">
+   special operator class to support indexing of pattern-matching queries.
-   below.
+   See <xref linkend="indexes-opclass"> below.
   </para>
 
   <para>
@@ -164,7 +172,7 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
    consider using an R-tree index whenever an indexed column is
    involved in a comparison using one of these operators:
 
-   <simplelist type="inline">
+   <simplelist>
     <member><literal>&lt;&lt;</literal></member>
     <member><literal>&amp;&lt;</literal></member>
     <member><literal>&amp;&gt;</literal></member>
@@ -173,7 +181,8 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
     <member><literal>~=</literal></member>
     <member><literal>&amp;&amp;</literal></member>
    </simplelist>
-   (Refer to <xref linkend="functions-geometry"> about the meaning of
+
+   (See <xref linkend="functions-geometry"> for the meaning of
    these operators.)
   </para>
 
@@ -204,6 +213,14 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
    </note>  
   </para>
 
+  <para>
+   GiST indexes are not a single kind of index, but rather an infrastructure
+   within which many different indexing strategies can be implemented.
+   Accordingly, the particular operators with which a GiST index can be
+   used vary depending on the indexing strategy (the <firstterm>operator
+   class</>).  For more information see <xref linkend="GiST">.
+  </para>
+
   <para>
    The B-tree index method is an implementation of Lehman-Yao
    high-concurrency B-trees.  The R-tree index method implements

doc/src/sgml/installation.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.224 2005/01/08 09:54:47 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.225 2005/01/08 22:13:26 tgl Exp $ -->
 
 <chapter id="installation">
  <title><![%standalone-include[<productname>PostgreSQL</>]]>
@@ -12,7 +12,11 @@
   This <![%standalone-include;[document]]>
   <![%standalone-ignore;[chapter]]> describes the installation of
   <productname>PostgreSQL</productname> from the source code
-  distribution.
+  distribution.  (If you are installing a pre-packaged distribution,
+  such as an RPM or Debian package, ignore this
+  <![%standalone-include;[document]]>
+  <![%standalone-ignore;[chapter]]>
+  and read the packager's instructions instead.)
  </para>
 
  <sect1 id="install-short">

doc/src/sgml/libpq.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.176 2005/01/06 21:20:43 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.177 2005/01/08 22:13:28 tgl Exp $
 -->
 
  <chapter id="libpq">
@@ -1264,6 +1264,7 @@ statement, instead of giving a query string.
 This feature allows commands
 that will be used repeatedly to be parsed and planned just once, rather
 than each time they are executed.
+The statement must have been prepared previously in the current session.
 <function>PQexecPrepared</> is supported only in protocol 3.0 and later
 connections; it will fail when using protocol 2.0.
 </para>

doc/src/sgml/lobj.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.34 2004/12/28 22:47:15 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.35 2005/01/08 22:13:33 tgl Exp $
 -->
 
  <chapter id="largeObjects">
@@ -122,15 +122,17 @@ Oid lo_creat(PGconn *conn, int mode);
      or'ing together the bits <symbol>INV_READ</symbol>  and
      <symbol>INV_WRITE</symbol>.  The low-order sixteen bits of the mask have
      historically been used at Berkeley to designate the storage  manager  number on which the large object
-     should reside.  These
+     should reside.  These bits should always be zero now.  (The access type
-     bits should always be zero now.
+     does not actually do anything anymore either, but one or both flag bits
-     The return value is the OID that was assigned to the new large object.
+     must be set to avoid an error.)
+     The return value is the OID that was assigned to the new large object,
+     or InvalidOid (zero) on failure.
     </para>
 
     <para>
      An example:
 <programlisting>
-inv_oid = lo_creat(INV_READ|INV_WRITE);
+inv_oid = lo_creat(conn, INV_READ|INV_WRITE);
 </programlisting>
     </para>
    </sect2>
@@ -147,7 +149,8 @@ Oid lo_import(PGconn *conn, const char *filename);
      <replaceable class="parameter">filename</replaceable> 
      specifies the operating system name of
      the file to be imported as a large object.
-     The return value is the OID that was assigned to the new large object.
+     The return value is the OID that was assigned to the new large object,
+     or InvalidOid (zero) on failure.
      Note that the file is read by the client interface library, not by
      the server; so it must exist in the client filesystem and be readable
      by the client application.
@@ -164,11 +167,11 @@ Oid lo_import(PGconn *conn, const char *filename);
 int lo_export(PGconn *conn, Oid lobjId, const char *filename);
 </synopsis>
      <indexterm><primary>lo_export</></>
-     The <parameter>lobjId</parameter> argument specifies  the  OID  of  the  large
+     The <parameter>lobjId</parameter> argument specifies the OID of the large
-     object  to  export  and the <parameter>filename</parameter> argument specifies
+     object to export and the <parameter>filename</parameter> argument
-     the operating system name of the file.
+     specifies the operating system name of the file.  Note that the file is
-     Note that the file is written by the client interface library, not by
+     written by the client interface library, not by the server.  Returns 1
-     the server.
+     on success, -1 on failure.
     </para>
    </sect2>
 
@@ -176,7 +179,7 @@ int lo_export(PGconn *conn, Oid lobjId, const char *filename);
     <title>Opening an Existing Large Object</title>
 
     <para>
-     To open an existing large object, call
+     To open an existing large object for reading or writing, call
 <synopsis>
 int lo_open(PGconn *conn, Oid lobjId, int mode);
 </synopsis>
@@ -186,11 +189,13 @@ int lo_open(PGconn *conn, Oid lobjId, int mode);
      object is opened  for  reading  (<symbol>INV_READ</>),  writing (<symbol>INV_WRITE</symbol>),  or
      both.
      A  large  object cannot be opened before it is created.
-     <function>lo_open</function> returns a large object descriptor
+     <function>lo_open</function> returns a (non-negative) large object
-     for later use in <function>lo_read</function>, <function>lo_write</function>,
+     descriptor for later use in <function>lo_read</function>,
-     <function>lo_lseek</function>, <function>lo_tell</function>, and
+     <function>lo_write</function>, <function>lo_lseek</function>,
-     <function>lo_close</function>.  The descriptor is only valid for
+     <function>lo_tell</function>, and <function>lo_close</function>.
+     The descriptor is only valid for 
      the duration of the current transaction.
+     On failure, -1 is returned.
 </para>
 </sect2>
 
@@ -246,7 +251,7 @@ int lo_lseek(PGconn *conn, int fd, int offset, int whence);
      are <symbol>SEEK_SET</> (seek from object start),
      <symbol>SEEK_CUR</> (seek from current position), and
      <symbol>SEEK_END</> (seek from object end).  The return value is
-     the new location pointer.
+     the new location pointer, or -1 on error.
 </para>
 </sect2>
 
@@ -294,46 +299,56 @@ int lo_unlink(PGconn *conn, Oid lobjId);
 </synopsis>
      <indexterm><primary>lo_unlink</></> The
      <parameter>lobjId</parameter> argument specifies the OID of the
-     large object to remove.  In the event of an error, the return
+     large object to remove.  Returns 1 if successful, -1 on failure.
-     value is negative.
     </para>
    </sect2>
 
-
 </sect1>
 
 <sect1 id="lo-funcs">
 <title>Server-Side Functions</title>
 
-<para>
+  <para>
-     There are two built-in server-side functions,
+   There are server-side functions callable from SQL that correspond to
-     <function>lo_import</function><indexterm><primary>lo_import</></>
+   each of the client-side functions described above; indeed, for the
-     and
+   most part the client-side functions are simply interfaces to the
-     <function>lo_export</function>,<indexterm><primary>lo_export</></>
+   equivalent server-side functions.  The ones that are actually useful
-     for large object access, which are available for use in
+   to call via SQL commands are
-     <acronym>SQL</acronym> commands.  Here is an example of their
+   <function>lo_creat</function><indexterm><primary>lo_creat</></>,
-     use:
+   <function>lo_unlink</function><indexterm><primary>lo_unlink</></>,
+   <function>lo_import</function><indexterm><primary>lo_import</></>, and
+   <function>lo_export</function><indexterm><primary>lo_export</></>.
+   Here are examples of their use:
+
 <programlisting>
 CREATE TABLE image (
     name            text,
     raster          oid
 );
 
+SELECT lo_creat(-1);       -- returns OID of new, empty large object
+
+SELECT lo_unlink(173454);  -- deletes large object with OID 173454
+
 INSERT INTO image (name, raster)
     VALUES ('beautiful image', lo_import('/etc/motd'));
 
 SELECT lo_export(image.raster, '/tmp/motd') FROM image
     WHERE name = 'beautiful image';
 </programlisting>
-</para>
+  </para>
 
-<para>
+  <para>
-These functions read and write files in the server's file system, using the
+    The server-side <function>lo_import</function> and
-permissions of the database's owning user.  Therefore, their use is restricted
+    <function>lo_export</function> functions behave considerably differently
-to superusers.  (In contrast, the client-side import and export functions
+    from their client-side analogs.  These two functions read and write files
-read and write files in the client's file system, using the permissions of
+    in the server's file system, using the permissions of the database's
-the client program.  Their use is not restricted.)
+    owning user.  Therefore, their use is restricted to superusers.  In
-</para>
+    contrast, the client-side import and export functions read and write files
+    in the client's file system, using the permissions of the client program.
+    The client-side functions can be used by any
+    <productname>PostgreSQL</productname> user.
+  </para>
 </sect1>
 
 <sect1 id="lo-examplesect">

doc/src/sgml/manage-ag.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.39 2004/12/27 22:30:10 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.40 2005/01/08 22:13:34 tgl Exp $
 -->
 
 <chapter id="managing-databases">
@@ -54,6 +54,21 @@ $PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.39 2004/12/27 22:30:10 tgl Ex
    managing schemas is in <xref linkend="ddl-schemas">.
   </para>
 
+  <para>
+   Databases are created with the <command>CREATE DATABASE</> command
+   (see <xref linkend="manage-ag-createdb">) and destroyed with the
+   <command>DROP DATABASE</> command
+   (see <xref linkend="manage-ag-dropdb">).
+   To determine the set of existing databases, examine the
+   <structname>pg_database</> system catalog, for example
+<synopsis>
+SELECT datname FROM pg_database;
+</synopsis>
+   The <xref linkend="app-psql"> program's <literal>\l</> meta-command
+   and <option>-l</> command-line option are also useful for listing the
+   existing databases.
+  </para>
+
   <note>
    <para>
     The <acronym>SQL</> standard calls databases <quote>catalogs</>, but there
@@ -444,8 +459,23 @@ CREATE TABLE foo(i int);
    </para>
 
    <para>
-    To simplify the implementation of tablespaces, 
+    To remove an empty tablespace, use the <xref linkend="sql-droptablespace">
-    <productname>PostgreSQL</> makes extensive use of symbolic links. This
+    command.  
+   </para>
+
+   <para>
+    To determine the set of existing tablespaces, examine the
+    <structname>pg_tablespace</> system catalog, for example
+<synopsis>
+SELECT spcname FROM pg_tablespace;
+</synopsis>
+    The <xref linkend="app-psql"> program's <literal>\db</> meta-command
+    is also useful for listing the existing tablespaces.
+   </para>
+
+   <para>
+    <productname>PostgreSQL</> makes extensive use of symbolic links
+    to simplify the implementation of tablespaces. This
     means that tablespaces can be used <emphasis>only</> on systems
     that support symbolic links.
    </para>

doc/src/sgml/plpgsql.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.54 2004/12/30 21:45:36 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.55 2005/01/08 22:13:34 tgl Exp $
 -->
 
 <chapter id="plpgsql"> 
@@ -2715,6 +2715,14 @@ AFTER INSERT OR UPDATE OR DELETE ON emp
        into groups.
       </para>
      </listitem>
+
+     <listitem>
+      <para>
+       Since there are no packages, there are no package-level variables
+       either. This is somewhat annoying.  You may be able to keep per-session
+       state in temporary tables, instead.
+      </para>
+     </listitem>
     </itemizedlist>
    </para>
 

doc/src/sgml/runtime.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.300 2005/01/04 00:05:44 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.301 2005/01/08 22:13:35 tgl Exp $
 -->
 
 <Chapter Id="runtime">
@@ -69,7 +69,8 @@ $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.300 2005/01/04 00:05:44 momjian
    default, although locations such as
    <filename>/usr/local/pgsql/data</filename> or
    <filename>/var/lib/pgsql/data</filename> are popular. To initialize a
-   database cluster, use the command <command>initdb</command>,<indexterm><primary>initdb</></> which is
+   database cluster, use the command <xref
+   linkend="app-initdb">,<indexterm><primary>initdb</></> which is
    installed with <productname>PostgreSQL</productname>. The desired
    file system location of your database cluster is indicated by the
    <option>-D</option> option, for example
@@ -149,6 +150,12 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
    other than <literal>C</> or <literal>POSIX</>. Therefore, it is
    important to make this choice correctly the first time.
   </para>
+
+  <para>
+   <command>initdb</command> also sets the default character set encoding
+   for the database cluster.  Normally this should be chosen to match the
+   locale setting.  For details see <xref linkend="multibyte">.
+  </para>
  </sect1>
 
  <sect1 id="postmaster-start">
@@ -3474,7 +3481,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
         present.  The default is <literal>true</> for compatibility with
         previous releases of <productname>PostgreSQL</>.  However, this
         behavior is not SQL-standard, and many people dislike it because it
-        can mask mistakes.  Set to <literal>false</> for the SQL-standard
+        can mask mistakes (such as referencing a table where you should have
+        referenced its alias).  Set to <literal>false</> for the SQL-standard
         behavior of rejecting references to tables that are not listed in
         <literal>FROM</>.
        </para>

doc/src/sgml/user-manag.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/user-manag.sgml,v 1.26 2004/12/27 22:30:10 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/user-manag.sgml,v 1.27 2005/01/08 22:13:36 tgl Exp $
 -->
 
 <chapter id="user-manag">
@@ -39,15 +39,15 @@ $PostgreSQL: pgsql/doc/src/sgml/user-manag.sgml,v 1.26 2004/12/27 22:30:10 tgl E
    operating system users. In practice it might be convenient to
    maintain a correspondence, but this is not required. Database user
    names are global across a database cluster installation (and not
-   per individual database). To create a user use the <command>CREATE
+   per individual database). To create a user use the <xref
-   USER</command> SQL command:
+   linkend="sql-createuser" endterm="sql-createuser-title"> SQL command:
 <synopsis>
 CREATE USER <replaceable>name</replaceable>;
 </synopsis>
    <replaceable>name</replaceable> follows the rules for SQL
    identifiers: either unadorned without special characters, or
    double-quoted. To remove an existing user, use the analogous
-   <command>DROP USER</command> command:
+   <xref linkend="sql-dropuser" endterm="sql-dropuser-title"> command:
 <synopsis>
 DROP USER <replaceable>name</replaceable>;
 </synopsis>
@@ -62,8 +62,8 @@ DROP USER <replaceable>name</replaceable>;
   </indexterm>
 
   <para>
-   For convenience, the programs <command>createuser</command>
+   For convenience, the programs <xref linkend="app-createuser">
-   and <command>dropuser</command> are provided as wrappers
+   and <xref linkend="app-dropuser"> are provided as wrappers
    around these SQL commands that can be called from the shell command
    line:
 <synopsis>
@@ -72,6 +72,16 @@ dropuser <replaceable>name</replaceable>
 </synopsis>
   </para>
 
+  <para>
+   To determine the set of existing users, examine the <structname>pg_user</>
+   system catalog, for example
+<synopsis>
+SELECT usename FROM pg_user;
+</synopsis>
+   The <xref linkend="app-psql"> program's <literal>\du</> meta-command
+   is also useful for listing the existing users.
+  </para>
+
   <para>
    In order to bootstrap the database system, a freshly initialized
    system always contains one predefined user. This user will have the
@@ -102,8 +112,8 @@ dropuser <replaceable>name</replaceable>
    is determined by the client authentication setup, as explained in
    <xref linkend="client-authentication">. (Thus, a client is not
    necessarily limited to connect as the user with the same name as
-   its operating system user, in the same way a person is not
+   its operating system user, just as a person's login name 
-   constrained in its login name by her real name.)  Since the user
+   need not match her real name.)  Since the user
    identity determines the set of privileges available to a connected
    client, it is important to carefully configure this when setting up
    a multiuser environment.
@@ -195,15 +205,35 @@ ALTER USER myname SET enable_indexscan TO off;
   <para>
    As in Unix, groups are a way of logically grouping users to ease
    management of privileges: privileges can be granted to, or revoked
-   from, a group as a whole.  To create a group, use
+   from, a group as a whole.  To create a group, use the <xref
+   linkend="sql-creategroup" endterm="sql-creategroup-title"> SQL command:
 <synopsis>
 CREATE GROUP <replaceable>name</replaceable>;
 </synopsis>
-   To add users to or remove users from a group, use
+
+   To add users to or remove users from an existing group, use <xref
+   linkend="sql-altergroup" endterm="sql-altergroup-title">:
 <synopsis>
 ALTER GROUP <replaceable>name</replaceable> ADD USER <replaceable>uname1</replaceable>, ... ;
 ALTER GROUP <replaceable>name</replaceable> DROP USER <replaceable>uname1</replaceable>, ... ;
 </synopsis>
+
+   To destroy a group, use <xref
+   linkend="sql-dropgroup" endterm="sql-dropgroup-title">:
+<synopsis>
+DROP GROUP <replaceable>name</replaceable>;
+</synopsis>
+   This only drops the group, not its member users.
+  </para>
+
+  <para>
+   To determine the set of existing groups, examine the <structname>pg_group</>
+   system catalog, for example
+<synopsis>
+SELECT groname FROM pg_group;
+</synopsis>
+   The <xref linkend="app-psql"> program's <literal>\dg</> meta-command
+   is also useful for listing the existing groups.
   </para>
  </sect1>
 

doc/src/sgml/xfunc.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.94 2005/01/07 23:08:44 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.95 2005/01/08 22:13:36 tgl Exp $
 -->
 
  <sect1 id="xfunc">
@@ -161,7 +161,15 @@ SELECT clean_emp();
     refers to the first argument, <literal>$2</> to the second, and so on.
     If an argument is of a composite type, then the dot notation,
     e.g., <literal>$1.name</literal>, may be used to access attributes
-    of the argument.
+    of the argument.  The arguments can only be used as data values,
+    not as identifiers.  Thus for example this is reasonable:
+<programlisting>
+INSERT INTO mytable VALUES ($1);
+</programlisting>
+but this will not work:
+<programlisting>
+INSERT INTO $1 VALUES (42);
+</programlisting>
    </para>
 
    <sect2>

doc/src/sgml/xtypes.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/xtypes.sgml,v 1.23 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/xtypes.sgml,v 1.24 2005/01/08 22:13:38 tgl Exp $
 -->
 
  <sect1 id="xtypes">
@@ -240,8 +240,9 @@ CREATE TYPE complex (
   data: the first four bytes must be an <type>int32</type> containing
   the total length in bytes of the datum (including itself).  The C
   functions operating on the data type must be careful to unpack any
-  toasted values they are handed (this detail can normally be hidden in the
+  toasted values they are handed, by using <function>PG_DETOAST_DATUM</>.
-  <function>GETARG</function> macros).  Then,
+  (This detail is customarily hidden by defining type-specific
+  <function>GETARG</function> macros.) Then, 
   when running the <command>CREATE TYPE</command> command, specify the
   internal length as <literal>variable</> and select the appropriate
   storage option.