Complete merge of all old man page information.

lisp.sgml is a placeholder for Eric Marsden's upcoming contribution.
catalogs.sgml is not yet marked up or integrated.
 It should perhaps become an appendix.

doc/src/sgml/catalogs.sgml

+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v 2.1 1999/07/22 15:11:03 thomas Exp $
+.TH "SYSTEM CATALOGS" INTRO 03/13/94 PostgreSQL PostgreSQL
+.SH "Section 7 - System Catalogs"
+.de LS
+.PP
+.if n .ta 5 +13 +13
+.if t .ta 0.5i +1.3i +1.3i
+.in 0
+.nf
+..
+.de LE
+.fi
+.in
+..
+.SH "DESCRIPTION"
+In this
+section we list each of the attributes of the system catalogs and
+define their meanings.
+.SH "CLASS/TYPE SYSTEM CATALOGS"
+These catalogs form the core of the extensibility system:
+.LS
+	\fBname\fP	\fBshared/local\fP	\fBdescription\fP
+	pg_aggregate	local	aggregate functions
+	pg_am	local	access methods
+	pg_amop	local	operators usable with specific access methods
+	pg_amproc	local	procedures used with specific access methods
+	pg_attribute	local	class attributes
+	pg_class	local	classes
+	pg_index	local	secondary indices
+	pg_inherits	local	class inheritance hierarchy
+	pg_language	local	procedure implementation languages
+	pg_opclass	local	operator classes
+	pg_operator	local	query language operators
+	pg_proc	local	procedures (functions)
+	pg_type	local	data types
+.LE
+.SH "ENTITIES"
+These catalogs deal with identification of entities known throughout
+the site:
+.LS
+	\fBname\fP	\fBshared/local\fP	\fBdescription\fP
+	pg_database	shared	current databases
+	pg_group	shared	user groups
+	pg_shadow	shared	valid users
+.LE
+.SH "RULE SYSTEM CATALOGS"
+.LS
+	\fBname\fP	\fBshared/local\fP	\fBdescription\fP
+	pg_listener	local	processes waiting on alerters
+	pg_prs2plans	local	instance system procedures
+	pg_prs2rule	local	instance system rules
+	pg_prs2stub	local	instance system ``stubs''
+	pg_rewrite	local	rewrite system information
+.LE
+.SH "LARGE OBJECT CATALOGS"
+.PP
+These catalogs are specific to the Inversion file system and large
+objects in general:
+.LS
+	\fBname\fP	\fBshared/local\fP	\fBdescription\fP
+	pg_lobj	local	description of a large object
+	pg_naming	local	Inversion name space mapping
+	pg_platter	local	jukebox platter inventory
+	pg_plmap	local	jukebox platter extent map
+.LE
+.SH "INTERNAL CATALOGS"
+.PP
+These catalogs are internal classes that are not stored as normal
+heaps and cannot be accessed through normal means (attempting to do so
+causes an error).
+.LS
+	\fBname\fP	\fBshared/local\fP	\fBdescription\fP
+	pg_log	shared	transaction commit/rollback log
+	pg_magic	shared	magic constant
+	pg_time	shared	commit/rollback times
+	pg_variable	shared	special variable values
+.LE
+.PP
+There are several other classes defined with \*(lqpg_\*(rq names.
+Aside from those that end in \*(lqind\*(rq (secondary indices), these
+are all obsolete or otherwise deprecated.
+.SH "CLASS/TYPE SYSTEM CATALOGS"
+.PP
+The following catalogs relate to the class/type system.
+.nf M
+/*
+ * aggregates
+ *
+ * see DEFINE AGGREGATE for an explanation of transition functions
+ */
+pg_aggregate
+    NameData      aggname	/* aggregate name (e.g., "count") */
+    oid         aggowner	/* usesysid of creator */
+    regproc     aggtransfn1	/* first transition function */
+    regproc     aggtransfn2	/* second transition function */
+    regproc     aggfinalfn	/* final function */
+    oid         aggbasetype	/* type of data on which aggregate
+				   operates */
+    oid         aggtranstype1	/* type returned by aggtransfn1 */
+    oid         aggtranstype2	/* type returned by aggtransfn2 */
+    oid         aggfinaltype	/* type returned by aggfinalfn */
+    text        agginitval1	/* external format of initial
+				   (starting) value of aggtransfn1 */
+    text        agginitval2	/* external format of initial
+				   (starting) value of aggtransfn2 */
+.fi
+.nf M
+pg_am
+    NameData      amname		/* access method name */
+    oid         amowner	/* usesysid of creator */
+    char        amkind		/* - deprecated */
+				/* originally:
+				   h=hashed
+				   o=ordered
+				   s=special */
+    int2        amstrategies	/* total NUMBER of strategies by which
+				   we can traverse/search this AM */
+    int2        amsupport	/* total NUMBER of support functions
+				   that this AM uses */
+    regproc     amgettuple	/* "next valid tuple" function */
+    regproc     aminsert	/* "insert this tuple" function */
+    regproc     amdelete	/* "delete this tuple" function */
+    regproc     amgetattr	/* - deprecated */
+    regproc     amsetlock	/* - deprecated */
+    regproc     amsettid	/* - deprecated */
+    regproc     amfreetuple	/* - deprecated */
+    regproc     ambeginscan	/* "start new scan" function */
+    regproc     amrescan	/* "restart this scan" function */
+    regproc     amendscan	/* "end this scan" function */
+    regproc     ammarkpos	/* "mark current scan position"
+				   function */
+    regproc     amrestrpos	/* "restore marked scan position"
+				   function */
+    regproc     amopen		/* - deprecated */
+    regproc     amclose	/* - deprecated */
+    regproc     ambuild	/* "build new index" function */
+    regproc     amcreate 	/* - deprecated */
+    regproc     amdestroy	/* - deprecated */
+.fi
+.nf M
+pg_amop
+    oid         amopid		/* access method with which this 
+				   operator be used */
+    oid         amopclaid	/* operator class with which this
+				   operator can be used */
+    oid         amopopr	/* the operator */
+    int2        amopstrategy	/* traversal/search strategy number
+				   to which this operator applies */
+    regproc     amopselect	/* function to calculate the operator
+				   selectivity */
+    regproc     amopnpages	/* function to calculate the number of
+				   pages that will be examined */
+.fi
+.nf M
+pg_amproc
+    oid         amid		/* access method with which this
+				   procedure is associated */
+    oid         amopclaid	/* operator class with which this
+				   operator can be used */
+    oid         amproc		/* the procedure */
+    int2        amprocnum	/* support function number to which
+				   this operator applies */
+.fi
+.nf M
+pg_class
+     NameData     relname	/* class name */
+     oid        relowner	/* usesysid of owner */
+     oid        relam	/* access method */
+     int4       relpages	/* # of 8KB pages */
+     int4       reltuples	/* # of instances */
+     abstime    relexpires	/* time after which instances are
+				   deleted from non-archival storage */
+     reltime    relpreserved	/* timespan after which instances are
+				   deleted from non-archival storage */
+     bool       relhasindex	/* does the class have a secondary
+				   index? */
+     bool       relisshared	/* is the class shared or local? */
+     char       relkind		/* type of relation:
+				   i=index
+				   r=relation (heap)
+				   s=special
+				   u=uncatalogued (temporary) */
+     char       relarch	/* archive mode:
+			   h=heavy
+			   l=light
+			   n=none */
+     int2       relnatts	/* current # of non-system
+				   attributes */
+     int2       relsmgr	/* storage manager:
+			   0=magnetic disk
+			   1=sony WORM jukebox
+			   2=main memory */
+     int28      relkey	/* - unused */
+     oid8       relkeyop	/* - unused */
+     aclitem    relacl[1]	/* access control lists */
+.fi
+.nf M
+pg_attribute
+    oid         attrelid	/* class containing this attribute */
+    NameData      attname	/* attribute name */
+    oid         atttypid	/* attribute type */
+    oid         attdefrel	/* - deprecated */
+    int4        attnvals	/* - deprecated */
+    oid         atttyparg	/* - deprecated */
+    int2        attlen	/* attribute length, in bytes
+			   -1=variable */
+    int2        attnum	/* attribute number
+			   >0=user attribute
+			   <0=system attribute */
+    int2        attbound	/* - deprecated */
+    bool        attbyval	/* type passed by value? */
+    bool        attcanindex	/* - deprecated */
+    oid         attproc	/* - deprecated */
+    int4        attnelems	/* # of array dimensions */
+    int4        attcacheoff	/* cached offset into tuple */
+    bool        attisset	/* is attribute set-valued? */
+.fi
+.nf M
+pg_inherits
+    oid         inhrel	/* child class */
+    oid         inhparent	/* parent class */
+    int4        inhseqno	/* - deprecated */
+.fi
+.nf M
+    oid         indexrelid	/* oid of secondary index class */
+    oid         indrelid	/* oid of indexed heap class */
+    oid         indproc	/* function to compute index key from
+				   attribute(s) in heap
+				   0=not a functional index */
+    int28       indkey	/* attribute numbers of key 
+			   attribute(s) */
+    oid8        indclass	/* opclass of each key */
+    bool        indisclustered	/* is the index clustered?
+				   - unused */
+    bool        indisarchived	/* is the index archival?
+				   - unused */
+    text        indpred	/* query plan for partial index 
+			   predicate */
+.fi
+.nf M
+pg_type
+    NameData      typname	/* type name */
+    oid         typowner	/* usesysid of owner */
+    int2        typlen	/* length in internal form
+			   -1=variable-length */
+    int2        typprtlen	/* length in external form */
+    bool        typbyval	/* type passed by value? */
+    char        typtype	/* kind of type:
+			   c=catalog (composite)
+			   b=base */
+    bool        typisdefined	/* defined or still a shell? */
+    char        typdelim	/* delimiter for array external form */
+    oid         typrelid	/* class (if composite) */
+    oid         typelem	/* type of each array element */
+    regproc     typinput	/* external-internal conversion
+				   function */ 
+    regproc     typoutput	/* internal-external conversion
+				   function */
+    regproc     typreceive	/* client-server conversion function */
+    regproc     typsend	/* server-client conversion function */
+    text        typdefault	/* default value */
+.fi
+.nf M
+pg_operator
+    NameData      oprname	/* operator name */
+    oid         oprowner	/* usesysid of owner */
+    int2        oprprec	/* - deprecated */
+    char        oprkind	/* kind of operator:
+			   b=binary
+			   l=left unary
+			   r=right unary */
+    bool        oprisleft	/* is operator left/right associative? */
+    bool        oprcanhash	/* is operator usable for hashjoin? */
+    oid         oprleft	/* left operand type */
+    oid         oprright	/* right operand type */
+    oid         oprresult	/* result type */
+    oid         oprcom	/* commutator operator */
+    oid         oprnegate	/* negator operator */
+    oid         oprlsortop	/* sort operator for left operand */
+    oid         oprrsortop	/* sort operator for right operand */
+    regproc     oprcode	/* function implementing this operator */
+    regproc     oprrest	/* function to calculate operator
+			   restriction selectivity */
+    regproc     oprjoin	/* function to calculate operator 
+			   join selectivity */
+.fi
+.nf M
+pg_opclass
+    NameData      opcname	/* operator class name */
+.fi
+.nf M
+pg_proc
+    NameData      proname	/* function name */
+    oid         proowner	/* usesysid of owner */
+    oid         prolang	/* function implementation language */
+    bool        proisinh	/* - deprecated */
+    bool        proistrusted	/* run in server or untrusted function
+				   process? */
+    bool        proiscachable	/* can the function return values be
+				   cached? */
+    int2        pronargs	/* # of arguments */
+    bool        proretset	/* does the function return a set?
+				   - unused */
+    oid         prorettype	/* return type */
+    oid8        proargtypes	/* argument types */
+    int4        probyte_pct	/* % of argument size (in bytes) that
+				   needs to be examined in order to
+				   compute the function */ 
+    int4        properbyte_cpu	/* sensitivity of the function's
+				   running time to the size of its
+				   inputs */
+    int4        propercall_cpu	/* overhead of the function's
+				   invocation (regardless of input
+				   size) */
+    int4        prooutin_ratio	/* size of the function's output as a
+				   percentage of the size of the input */
+    text        prosrc	/* function definition:
+			   INTERNAL function: actual C name of function
+			   C function: currently, this field is unused
+			   SQL function: text of query(s)
+			   PL function: text in procedural language */
+    bytea       probin	/* path to object file (C functions only) */
+.fi
+.nf M
+pg_language
+    NameData      lanname	/* language name */
+    text        lancompiler	/* - deprecated */
+.fi
+.SH "ENTITIES"
+.nf M
+pg_database
+    NameData      datname		/* database name */
+    oid         datdba		/* usesysid of database administrator */
+    text        datpath		/* directory of database under
+				   $PGDATA */ 
+.fi
+.nf M
+pg_group
+    NameData      groname	/* group name */
+    int2        grosysid	/* group's UNIX group id */
+    int2        grolist[1]	/* list of usesysids of group members */
+.fi
+.nf M
+pg_shadow
+    NameData      usename		/* user's name */
+    int2        usesysid	/* user's UNIX user id */
+    bool        usecreatedb	/* can user create databases? */
+    bool        usetrace	/* can user set trace flags? */
+    bool        usesuper	/* can user be POSTGRES superuser? */
+    bool        usecatupd	/* can user update catalogs? */
+.fi
+.SH "RULE SYSTEM CATALOGS"
+.nf M
+pg_listener
+    NameData      relname	/* class for which asynchronous 
+			   notification is desired */
+    int4        listenerpid	/* process id of server corresponding
+				   to a frontend program waiting for
+				   asynchronous notification */
+    int4        notification	/* whether an event notification for
+				   this process id still pending */
+
+.fi
+.nf M
+pg_prs2rule
+    NameData      prs2name	/* rule name */
+    char        prs2eventtype	/* rule event type:
+				   R=retrieve
+				   U=update (replace)
+				   A=append
+				   D=delete */
+    oid         prs2eventrel	/* class to which event applies */
+    int2        prs2eventattr	/* attribute to which event applies */
+    float8      necessary	/* - deprecated */
+    float8      sufficient	/* - deprecated */
+    text        prs2text	/* text of original rule definition */
+.fi
+.nf M
+pg_prs2plans
+    oid         prs2ruleid	/* prs2rule instance for which this
+				   plan is used */
+    int2        prs2planno	/* plan number (one rule may invoke
+				   multiple plans) */
+    text        prs2code	/* external representation of the plan */
+.fi
+.nf M
+pg_prs2stub
+    oid         prs2relid	/* class to which this rule applies */
+    bool        prs2islast	/* is this the last stub fragment? */
+    int4        prs2no		/* stub fragment number */
+    stub        prs2stub	/* stub fragment */
+.fi
+.nf M
+pg_rewrite
+    NameData      rulename	/* rule name */
+    char        ev_type	/* event type:
+			   RETRIEVE, REPLACE, APPEND, DELETE
+			   codes are parser-dependent (!?) */
+    oid         ev_class	/* class to which this rule applies */
+    int2        ev_attr	/* attribute to which this rule applies */
+    bool        is_instead	/* is this an "instead" rule? */
+    text        ev_qual	/* qualification with which to modify
+			   (rewrite) the plan that triggered this
+			   rule */
+    text        action	/* parse tree of action */
+.fi
+.SH "LARGE OBJECT CATALOGS"
+.nf M
+pg_lobj
+    oid         ourid		/* 'ourid' from pg_naming that
+				   identifies this object in the
+				   Inversion file system namespace */
+    int4        objtype		/* storage type code:
+				   0=Inversion
+				   1=Unix
+				   2=External
+				   3=Jaquith */
+    bytea       object_descripto/* opaque object-handle structure */
+.fi
+.nf M
+pg_naming
+    NameData      filename	/* filename component */
+    oid         ourid		/* random oid used to identify this
+				   instance in other instances (can't
+				   use the actual oid for obscure
+				   reasons */
+    oid         parentid	/* pg_naming instance of parent
+				   Inversion file system directory */
+.fi
+.nf M
+pg_platter
+     NameData     plname		/* platter name */
+     int4       plstart		/* the highest OCCUPIED extent */
+.fi
+.nf M
+pg_plmap
+     oid        plid		/* platter (in pg_platter) on which
+				   this extent (of blocks) resides */
+     oid        pldbid		/* database of the class to which this
+				   extent (of blocks) belongs */
+     oid        plrelid		/* class to which this extend (of
+				   blocks) belongs */
+     int4       plblkno		/* starting block number within the
+				   class */ 
+     int4       ploffset	/* offset within the platter at which
+				   this extent begins */
+     int4       plextentsz	/* length of this extent */
+.fi

doc/src/sgml/dfunc.sgml

-<Chapter Id="dfunc">
-<Title>Linking Dynamically-Loaded Functions</Title>
+ <chapter id="dfunc">
+  <title id="dfunc-title">Linking Dynamically-Loaded Functions</title>
 
-<Para>
+<!--
+.SH "Compiling Dynamically-Loaded C Functions"
+.PP
+Different operating systems require different procedures for compiling
+C source files so that Postgres can load them dynamically.  This section
+discusses the required compiler and loader options on each system.
+.PP
+Under Linux ELF, object files can be generated by specifing the compiler
+flag -fpic.
+.PP
+Under Ultrix, all object files that Postgres is expected to load
+dynamically must be compiled using
+.IR /bin/cc
+with the \*(lq-G 0\*(rq option turned on.  The object file name in the
+.IR as
+clause should end in \*(lq.o\*(rq.
+.PP
+Under HP-UX, DEC OSF/1, AIX and SunOS 4, all object files must be
+turned into
+.IR "shared libraries"
+using the operating system's native object file loader,
+.IR ld(1).
+.PP
+Under HP-UX, an object file must be compiled using the native HP-UX C
+compiler,
+.IR /bin/cc ,
+with both the \*(lq+z\*(rq and \*(lq+u\*(rq flags turned on.  The
+first flag turns the object file into \*(lqposition-independent
+code\*(rq (PIC); the second flag removes some alignment restrictions
+that the PA-RISC architecture normally enforces.  The object file must
+then be turned into a shared library using the HP-UX loader,
+.IR /bin/ld .
+The command lines to compile a C source file, \*(lqfoo.c\*(rq, look
+like:
+.nf
+cc <other flags> +z +u -c foo.c
+ld <other flags> -b -o foo.sl foo.o
+.fi
+The object file name in the
+.BR as
+clause should end in \*(lq.sl\*(rq.
+.PP
+An extra step is required under versions of HP-UX prior to 9.00.  If
+the Postgres header file
+.nf
+include/c.h
+.fi
+is not included in the source file, then the following line must also
+be added at the top of every source file:
+.nf
+#pragma HP_ALIGN HPUX_NATURAL_S500
+.fi
+However, this line must not appear in programs compiled under HP-UX
+9.00 or later.
+.PP
+Under DEC OSF/1, an object file must be compiled and then turned
+into a shared library using the OSF/1 loader,
+.IR /bin/ld .
+In this case, the command lines look like:
+.nf
+cc <other flags> -c foo.c
+ld <other flags> -shared -expect_unresolved '*' -o foo.so foo.o
+.fi
+The object file name in the
+.BR as
+clause should end in \*(lq.so\*(rq.
+.PP
+Under SunOS 4, an object file must be compiled and then turned into a
+shared library using the SunOS 4 loader,
+.IR /bin/ld .
+The command lines look like:
+.nf
+cc <other flags> -PIC -c foo.c
+ld <other flags> -dc -dp -Bdynamic -o foo.so foo.o
+.fi
+The object file name in the
+.BR as
+clause should end in \*(lq.so\*(rq.
+.PP
+Under AIX, object files are compiled normally but building the shared
+library requires a couple of steps.  First, create the object file:
+.nf
+cc <other flags> -c foo.c
+.fi
+You must then create a symbol \*(lqexports\*(rq file for the object
+file:
+.nf
+mkldexport foo.o `pwd` > foo.exp
+.fi
+Finally, you can create the shared library:
+.nf
+ld <other flags> -H512 -T512 -o foo.so -e _nostart \e
+   -bI:.../lib/postgres.exp -bE:foo.exp foo.o \e
+   -lm -lc 2>/dev/null
+.fi
+You should look at the Postgres User's Manual for an explanation of this
+procedure.
+-->
+
+<para>
      After you have created and  registered  a  user-defined
-     function,  your  work  is  essentially done.  <ProductName>Postgres</ProductName>,
-     however, must load the object code (e.g., a <FileName>.o</FileName> file, or
+     function,  your  work  is  essentially done.  <productname>Postgres</productname>,
+     however, must load the object code (e.g., a <filename>.o</filename> file, or
      a  shared  library)  that implements your function.  As
-     previously mentioned, <ProductName>Postgres</ProductName> loads your code at  
+     previously mentioned, <productname>Postgres</productname> loads your code at  
      runtime,  as  required.  In order to allow your code to be
      dynamically loaded, you may have to compile  and  
      link-edit  it  in  a  special  way.   This  section  briefly
      describes how to  perform  the  compilation  and  
      link-editing  required before you can load your user-defined
-     functions into a running <ProductName>Postgres</ProductName>  server.   Note  that
+     functions into a running <productname>Postgres</productname>  server.   Note  that
      this process has  changed  as  of  Version  4.2.
-<Tip>
-<Para>
-The  old  <ProductName>Postgres</ProductName> dynamic 
+<tip>
+<para>
+The  old  <productname>Postgres</productname> dynamic 
 loading mechanism required
 in-depth knowledge in terms of executable format,  placement
 and alignment of executable instructions within memory, etc.
 on the part of the person writing the dynamic loader.   Such
 loaders tended to be slow and buggy.  As of Version 4.2, the
-<ProductName>Postgres</ProductName> dynamic loading mechanism has been rewritten to use
+<productname>Postgres</productname> dynamic loading mechanism has been rewritten to use
 the dynamic loading mechanism provided by the operating 
 system.  This approach is generally faster, more  reliable  and
 more  portable  than our previous dynamic loading mechanism.
@@ -30,58 +129,59 @@ The reason for this is that nearly all  modern  versions  of
 UNIX use a dynamic loading mechanism to implement shared 
 libraries and must therefore provide a fast and reliable 
 mechanism.   On  the  other  hand, the object file must be 
-postprocessed a bit before it can be loaded into  <ProductName>Postgres</ProductName>.   We
+postprocessed a bit before it can be loaded into  <productname>Postgres</productname>.   We
 hope  that  the large increase in speed and reliability will
 make up for the slight decrease in convenience.
 </para>
-</Tip>
+</tip>
 </para>
 <para>
      You should  expect  to read (and reread, and re-reread) the
      manual pages for the C compiler, cc(1),  and  the  link
      editor,  ld(1),  if  you  have  specific questions.  In
      addition, the regression test suites in  the  directory
-     <FileName>PGROOT/src/regress</FileName> contain several 
+     <filename>PGROOT/src/regress</filename> contain several 
      working examples of this process.  If you copy  what  these
      tests do, you should not have any problems.
      The following terminology will be used below:
-<ItemizedList>
-<ListItem>
-<Para>
-     <FirstTerm>Dynamic loading</FirstTerm>
-          is  what  <ProductName>Postgres</ProductName>  does  to  an object file.  The
-          object file is copied into  the  running  <ProductName>Postgres</ProductName>
+<itemizedlist>
+<listitem>
+<para>
+     <firstterm>Dynamic loading</firstterm>
+          is  what  <productname>Postgres</productname>  does  to  an object file.  The
+          object file is copied into  the  running  <productname>Postgres</productname>
           server  and the functions and variables within the
           file are made available to  the  functions  within
-          the  <ProductName>Postgres</ProductName>  process.   <ProductName>Postgres</ProductName> does this using
+          the  <productname>Postgres</productname>  process.
+      <productname>Postgres</productname> does this using
           the dynamic  loading  mechanism  provided  by  the
           operating system.
-</Para>
-</ListItem>
-<ListItem>
-<Para>
-     <FirstTerm>Loading and link editing</FirstTerm>
+</para>
+</listitem>
+<listitem>
+<para>
+     <firstterm>Loading and link editing</firstterm>
           is  what you do to an object file in order to produce 
           another kind of object file  (e.g.,  an  executable 
           program or a shared library).  You perform
           this using the link editing program, ld(1).
-</Para>
-</ListItem>
-</ItemizedList>
-</Para>
+</para>
+</listitem>
+</itemizedlist>
+</para>
 
-<Para>
+<para>
      The following general restrictions and notes also apply
      to the discussion below:
-<ItemizedList>
-<ListItem>
-<Para>
+<itemizedlist>
+<listitem>
+<para>
 Paths  given  to the create function command must be
         absolute paths (i.e., start with "/") that refer  to
         directories  visible  on  the  machine  on which the
-        <ProductName>Postgres</ProductName> server is running.
-<Tip>
-<Para>
+        <productname>Postgres</productname> server is running.
+<tip>
+<para>
 Relative paths do in fact work, 
 but  are  relative  to
 the directory where the database resides (which is generally
@@ -89,45 +189,45 @@ invisible to the frontend application).  Obviously, it makes
 no sense to make the path relative to the directory in which
 the user started the frontend application, since the  server
 could be running on a completely different machine!
-</Para>
-</Tip>
-</Para>
-</ListItem>
-<ListItem>
-<Para>
-The  <ProductName>Postgres</ProductName> user must be able to traverse the path
+</para>
+</tip>
+</para>
+</listitem>
+<listitem>
+<para>
+The  <productname>Postgres</productname> user must be able to traverse the path
         given to the create function command and be able  to
-        read  the object file.  This is because the <ProductName>Postgres</ProductName>
-        server runs as the <ProductName>Postgres</ProductName> user, not  as  the  user
+        read  the object file.  This is because the <productname>Postgres</productname>
+        server runs as the <productname>Postgres</productname> user, not  as  the  user
         who  starts  up  the  frontend process.  (Making the
         file or a higher-level directory  unreadable  and/or
         unexecutable  by the "postgres" user is an extremely
         common mistake.)
-</Para>
-</ListItem>
-<ListItem>
-<Para>
+</para>
+</listitem>
+<listitem>
+<para>
 Symbol names defined within object  files  must  not
         conflict  with each other or with symbols defined in
-        <ProductName>Postgres</ProductName>.
-</Para>
-</ListItem>
-<ListItem>
-<Para>
+        <productname>Postgres</productname>.
+</para>
+</listitem>
+<listitem>
+<para>
 The GNU C compiler usually does not provide the special  
         options that are required to use the operating
         system's dynamic loader interface.  In  such  cases,
         the  C compiler that comes with the operating system
         must be used.
-</Para>
-</ListItem>
-</ItemizedList>
+</para>
+</listitem>
+</itemizedlist>
 </para>
 
-<Sect1>
-<Title><Acronym>ULTRIX</Acronym></Title>
+<sect1>
+<title><acronym>ULTRIX</acronym></title>
 
-<Para>
+<para>
      It is very  easy  to  build  dynamically-loaded  object
      files  under  ULTRIX.  ULTRIX does not have any shared library 
      mechanism and hence does not place any restrictions  on  
@@ -138,42 +238,42 @@ The GNU C compiler usually does not provide the special
      produce each object file with the option -G 0.  (Notice
      that  that's  the  numeral  ``0''  and  not  the letter
      ``O'').  For example,
-<ProgramListing>
+<programlisting>
 # simple ULTRIX example
 % cc -G 0 -c foo.c
-</ProgramListing>
+</programlisting>
      produces an object file called foo.o that can  then  be
-     dynamically  loaded into <ProductName>Postgres</ProductName>.
+     dynamically  loaded into <productname>Postgres</productname>.
 No additional loading or link-editing must be performed.
-</Para>
-</Sect1>
+</para>
+</sect1>
 
-<Sect1>
-<Title><Acronym>DEC OSF/1</Acronym></Title>
+<sect1>
+<title><acronym>DEC OSF/1</acronym></title>
 
-<Para>
+<para>
      Under DEC OSF/1, you can take any  simple  object  file
      and produce a shared object file by running the ld command
  over it with the correct options.  The commands to
      do this look like:
-<ProgramListing>
+<programlisting>
 # simple DEC OSF/1 example
 % cc -c foo.c
 % ld -shared -expect_unresolved '*' -o foo.so foo.o
-</ProgramListing>
+</programlisting>
 
      The  resulting  shared  object  file can then be loaded
-     into <ProductName>Postgres</ProductName>.  When specifying the object file name to
+     into <productname>Postgres</productname>.  When specifying the object file name to
      the  create function command, one must give it the name
      of the shared object file (ending in .so)  rather  than
      the  simple  object  file.
-<Tip>
-<Para>
-Actually, <ProductName>Postgres</ProductName> does not care
+<tip>
+<para>
+Actually, <productname>Postgres</productname> does not care
 what  you  name  the
 file  as  long as it is a shared object file.  If you prefer
 to name your shared object files with the extension .o, this
-is fine with <ProductName>Postgres</ProductName>
+is fine with <productname>Postgres</productname>
  so long as you make sure that the correct 
 file name is given to the create function command.   In
 other words, you must simply be consistent.  However, from a
@@ -183,19 +283,20 @@ files have been made into shared object files and which have
 not.   For  example, it's very hard to write Makefiles to do
 the link-editing automatically if both the object  file  and
 the shared object file end in .o!
-</Para>
-</Tip>
+</para>
+</tip>
 
 If the file you specify is
      not a shared object, the backend will hang!
-</Para>
-</Sect1>
+</para>
+</sect1>
 
-<Sect1>
-<Title>
-<Acronym>SunOS 4.x</Acronym>, <Acronym>Solaris 2.x</Acronym> and <Acronym>HP-UX</Acronym></Title>
+<sect1>
+<title>
+<acronym>SunOS 4.x</acronym>, <acronym>Solaris 2.x</acronym> and
+    <acronym>HP-UX</acronym></title>
 
-<Para>
+<para>
      Under SunOS 4.x, Solaris 2.x and HP-UX, the simple
      object file must be created  by  compiling  the  source
      file  with  special compiler flags and a shared library
@@ -209,44 +310,61 @@ If the file you specify is
      into  a shared library using the HP-UX link editor with
      the -b option.  This sounds complicated but is actually
      very simple, since the commands to do it are just:
-<ProgramListing>
+<programlisting>
 # simple HP-UX example
 % cc +z +u -c foo.c
 % ld -b -o foo.sl foo.o
-</ProgramListing>
-</Para>
+</programlisting>
+</para>
 
-<Para>
+<para>
      As with the .so files mentioned in the last subsection,
      the create function command must be told which file  is
      the  correct  file  to load (i.e., you must give it the
      location of the shared library, or .sl file).
      Under SunOS 4.x, the commands look like:
-<ProgramListing>
+<programlisting>
 # simple SunOS 4.x example
 % cc -PIC -c foo.c
 % ld -dc -dp -Bdynamic -o foo.so foo.o
-</ProgramListing>
+</programlisting>
 
      and the equivalent lines under Solaris 2.x are:
-<ProgramListing>
+<programlisting>
 # simple Solaris 2.x example
 % cc -K PIC -c foo.c
 % ld -G -Bdynamic -o foo.so foo.o
-</ProgramListing>
+</programlisting>
     or
-<ProgramListing>
+<programlisting>
 # simple Solaris 2.x example
 % gcc -fPIC -c foo.c
 % ld -G -Bdynamic -o foo.so foo.o
-</ProgramListing>
-</Para>
+</programlisting>
+</para>
 
-<Para>
+<para>
      When linking shared libraries, you may have to  specify
      some  additional  shared  libraries  (typically  system
      libraries, such as the C and math libraries) on your ld
      command line.
-</Para>
-</Sect1>
-</Chapter>
+</para>
+</sect1>
+</chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
+sgml-local-ecat-files:nil
+End:
+-->

doc/src/sgml/extend.sgml

-<Chapter Id="extend">
-<Title>Extending <Acronym>SQL</Acronym>: An Overview</Title>
-
-<Para>
-     In  the  sections  that follow, we will discuss how you
-     can extend the <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> query language by adding:
-<ItemizedList Mark="bullet" Spacing="compact">
-<ListItem>
-<Para>
+ <chapter id="extend">
+  <title>Extending <acronym>SQL</acronym>: An Overview</title>
+
+  <para>
+   In  the  sections  that follow, we will discuss how you
+   can extend the <productname>Postgres</productname> 
+   <acronym>SQL</acronym> query language by adding:
+
+   <itemizedlist spacing="compact" mark="bullet">
+    <listitem>
+     <para>
       functions
-</Para>
-</ListItem>
-<ListItem>
-<Para>
+     </para>
+    </listitem>
+    <listitem>
+     <para>
       types
-</Para>
-</ListItem>
-<ListItem>
-<Para>
+     </para>
+    </listitem>
+    <listitem>
+     <para>
       operators
-</Para>
-</ListItem>
-<ListItem>
-<Para>
+     </para>
+    </listitem>
+    <listitem>
+     <para>
       aggregates
-</Para>
-</ListItem>
-</ItemizedList>
-</Para>
-
-<Sect1>
-<Title>How Extensibility Works</Title>
-
-<Para>
-     <ProductName>Postgres</ProductName> is extensible because its operation  is  
-     catalog-driven.   If  you  are familiar with standard 
-     relational systems, you know that  they  store  information
-     about  databases,  tables,  columns,  etc., in what are
-     commonly known as system catalogs.  (Some systems  call
-     this  the data dictionary).  The catalogs appear to the
-     user as classes, like any other, but  the  <Acronym>DBMS</Acronym>  stores
-     its  internal  bookkeeping in them.  One key difference
-     between <ProductName>Postgres</ProductName> and  standard  relational  systems  is
-     that <ProductName>Postgres</ProductName> stores much more information in its 
-     catalogs -- not only information about tables and  columns,
-     but also information about its types, functions, access
-     methods, and so on.  These classes can be  modified  by
-     the  user, and since <ProductName>Postgres</ProductName> bases its internal operation 
-     on these classes, this means that <ProductName>Postgres</ProductName> can  be
-     extended   by   users.    By  comparison,  conventional
-     database systems can only be extended by changing hardcoded  
-     procedures within the <Acronym>DBMS</Acronym> or by loading modules
-     specially-written by the <Acronym>DBMS</Acronym> vendor.
-</Para>
-<Para>
-     <ProductName>Postgres</ProductName> is also unlike most  other  data  managers  in
-     that  the server can incorporate user-written code into
-     itself through dynamic loading.  That is, the user  can
-     specify  an  object code file (e.g., a compiled .o file
-     or shared library) that implements a new type or  function 
-     and <ProductName>Postgres</ProductName> will load it as required.  Code written 
-     in <Acronym>SQL</Acronym> are even more trivial to add to the  server.
-     This ability to modify its operation "on the fly" makes
-     <ProductName>Postgres</ProductName> uniquely suited for rapid prototyping  of  new
-     applications and storage structures.
-</Para>
-</Sect1>
-
-<Sect1>
-<Title>The <ProductName>Postgres</ProductName> Type System</Title>
-
-<Para>
-     The  <ProductName>Postgres</ProductName> type system can be broken down in several ways.
-     Types are divided into base types and composite  types.
-     Base  types  are those, like <FirstTerm>int4</FirstTerm>, that are implemented
-     in a language such as <ProductName>C</ProductName>.  They generally correspond  to
-     what are often known as "abstract data types"; <ProductName>Postgres</ProductName>
-     can only operate on such types through methods provided
-     by  the  user and only understands the behavior of such
-     types to the extent that the user describes them.  
-     Composite  types  are  created whenever the user creates a
-     class.  EMP is an example of a composite  type.   
-</Para>
-<Para>
-     <ProductName>Postgres</ProductName>  stores  these  types  in only one way (within the
-     file that stores all instances of the  class)  but  the
-     user can "look inside" at the attributes of these types
-     from the query language and optimize their retrieval by
-     (for example) defining indices on the attributes.
-     <ProductName>Postgres</ProductName>  base  types are further divided into built-in
-     types and user-defined  types.   Built-in  types  (like
-     <FirstTerm>int4</FirstTerm>)  are  those  that  are  compiled into the system.
-     User-defined types are those created by the user in the
-     manner to be described below.
-</Para>
-</Sect1>
-
-<Sect1>
-<Title>About the <ProductName>Postgres</ProductName> System Catalogs</Title>
-
-<Para>
-     Having  introduced the basic extensibility concepts, we
-     can now take a look at how the  catalogs  are  actually
-     laid  out.  You can skip this section for now, but some
-     later sections will  be  incomprehensible  without  the
-     information  given  here,  so  mark this page for later
-     reference.
-     All system catalogs have names  that  begin  with  <FirstTerm>pg_</FirstTerm>.
-     The  following  classes contain information that may be
-     useful to the end user.  (There are many  other  system
-     catalogs,  but there should rarely be a reason to query
-     them directly.)
-
-<TABLE TOCENTRY="1">
-<TITLE>Postgres System Catalogs</TITLE>
-<TITLEABBREV>Catalogs</TITLEABBREV>
-<TGROUP COLS="2">
-<THEAD>
-<ROW>
-<ENTRY>Catalog Name</ENTRY>
-<ENTRY>Description</ENTRY>
-</ROW>
-</THEAD>
-<TBODY>
-<ROW>
-<ENTRY>pg_database</ENTRY>
-<ENTRY> databases</ENTRY>
-</ROW>
-<ROW>
-<ENTRY>pg_class</ENTRY>
-<ENTRY> classes</ENTRY>
-</ROW>
-<ROW>
-<ENTRY>pg_attribute</ENTRY>
-<ENTRY> class attributes</ENTRY>
-</ROW>
-<ROW>
-<ENTRY>pg_index</ENTRY>
-<ENTRY> secondary indices</ENTRY>
-</ROW>
-<ROW>
-<ENTRY>pg_proc</ENTRY>
-<ENTRY> procedures (both C and SQL)</ENTRY>
-</ROW>
-<ROW>
-<ENTRY>pg_type</ENTRY>
-<ENTRY> types (both base and complex)</ENTRY>
-</ROW>
-<ROW>
-<ENTRY>pg_operator</ENTRY>
-<ENTRY> operators</ENTRY>
-</ROW>
-<ROW>
-<ENTRY>pg_aggregate</ENTRY>
-<ENTRY> aggregates and aggregate functions</ENTRY>
-</ROW>
-<ROW>
-<ENTRY>pg_am</ENTRY>
-<ENTRY> access methods</ENTRY>
-</ROW>
-<ROW>
-<ENTRY>pg_amop</ENTRY>
-<ENTRY> access method operators</ENTRY>
-</ROW>
-<ROW>
-<ENTRY>pg_amproc</ENTRY>
-<ENTRY> access method support functions</ENTRY>
-</ROW>
-<ROW>
-<ENTRY>pg_opclass</ENTRY>
-<ENTRY> access method operator classes</ENTRY>
-</ROW>
-</TBODY>
-</TGROUP>
-</TABLE>
-</Para>
-
-<Para>
-<Figure Id="EXTEND-CATALOGS" Float="1">
-<Title>The major <ProductName>Postgres</ProductName> system catalogs</Title>
-<Graphic Align="center" FileRef="catalogs.gif" Format="GIF"></Graphic>
-</Figure>
-
-     The Reference Manual gives a more detailed  explanation
-     of  these catalogs and their attributes.  However,
-<XRef LinkEnd="EXTEND-CATALOGS" EndTerm="EXTEND-CATALOGS">
-     shows the major entities and their  relationships
-     in  the system catalogs.  (Attributes that do not refer
-     to other entities are not shown unless they are part of
-     a primary key.)
-     This diagram is more or less incomprehensible until you
-     actually start looking at the contents of the  catalogs
-     and  see  how  they relate to each other.  For now, the
-     main things to take away from this diagram are as  follows:
+     </para>
+    </listitem>
+   </itemizedlist>
+  </para>
+
+  <sect1>
+   <title>How Extensibility Works</title>
+
+   <para>
+    <productname>Postgres</productname> is extensible because its operation  is  
+    catalog-driven.   If  you  are familiar with standard 
+    relational systems, you know that  they  store  information
+    about  databases,  tables,  columns,  etc., in what are
+    commonly known as system catalogs.  (Some systems  call
+    this  the data dictionary).  The catalogs appear to the
+    user as classes, like any other, but  the  <acronym>DBMS</acronym>  stores
+    its  internal  bookkeeping in them.  One key difference
+    between <productname>Postgres</productname> and  standard  relational  systems  is
+    that <productname>Postgres</productname> stores much more information in its 
+    catalogs -- not only information about tables and  columns,
+    but also information about its types, functions, access
+    methods, and so on.  These classes can be  modified  by
+    the  user, and since <productname>Postgres</productname> bases its internal operation 
+    on these classes, this means that <productname>Postgres</productname> can  be
+    extended   by   users.    By  comparison,  conventional
+    database systems can only be extended by changing hardcoded  
+    procedures within the <acronym>DBMS</acronym> or by loading modules
+    specially-written by the <acronym>DBMS</acronym> vendor.
+   </para>
+
+   <para>
+    <productname>Postgres</productname> is also unlike most  other  data  managers  in
+    that  the server can incorporate user-written code into
+    itself through dynamic loading.  That is, the user  can
+    specify  an  object code file (e.g., a compiled .o file
+    or shared library) that implements a new type or  function 
+    and <productname>Postgres</productname> will load it as required.  Code written 
+    in <acronym>SQL</acronym> are even more trivial to add to the  server.
+    This ability to modify its operation "on the fly" makes
+    <productname>Postgres</productname> uniquely suited for rapid prototyping  of  new
+    applications and storage structures.
+   </para>
+  </sect1>
+
+  <sect1>
+   <title>The <productname>Postgres</productname> Type System</title>
+
+   <para>
+    The <productname>Postgres</productname> type system
+    can be broken down in several ways.
+    Types are divided into base types and composite  types.
+    Base  types  are those, like <firstterm>int4</firstterm>, that are implemented
+    in a language such as <productname>C</productname>.  They generally correspond  to
+    what are often known as "abstract data types"; <productname>Postgres</productname>
+    can only operate on such types through methods provided
+    by  the  user and only understands the behavior of such
+    types to the extent that the user describes them.  
+    Composite  types  are  created whenever the user creates a
+    class.  EMP is an example of a composite  type.   
+   </para>
+
+   <para>
+    <productname>Postgres</productname>  stores  these  types
+    in only one way (within the
+    file that stores all instances of the  class)  but  the
+    user can "look inside" at the attributes of these types
+    from the query language and optimize their retrieval by
+    (for example) defining indices on the attributes.
+    <productname>Postgres</productname>  base  types are further
+    divided into built-in
+    types and user-defined  types.   Built-in  types  (like
+    <firstterm>int4</firstterm>)  are  those  that  are  compiled
+    into the system.
+    User-defined types are those created by the user in the
+    manner to be described below.
+   </para>
+  </sect1>
+
+  <sect1>
+   <title>About the <productname>Postgres</productname> System Catalogs</title>
+
+   <para>
+    Having  introduced the basic extensibility concepts, we
+    can now take a look at how the  catalogs  are  actually
+    laid  out.  You can skip this section for now, but some
+    later sections will  be  incomprehensible  without  the
+    information  given  here,  so  mark this page for later
+    reference.
+    All system catalogs have names  that  begin  with
+    <firstterm>pg_</firstterm>.
+    The  following  classes contain information that may be
+    useful to the end user.  (There are many  other  system
+    catalogs,  but there should rarely be a reason to query
+    them directly.)
+
+    <table tocentry="1">
+     <title>Postgres System Catalogs</title>
+     <titleabbrev>Catalogs</titleabbrev>
+     <tgroup cols="2">
+      <thead>
+       <row>
+	<entry>Catalog Name</entry>
+	<entry>Description</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+	<entry>pg_database</entry>
+	<entry> databases</entry>
+       </row>
+       <row>
+	<entry>pg_class</entry>
+	<entry> classes</entry>
+       </row>
+       <row>
+	<entry>pg_attribute</entry>
+	<entry> class attributes</entry>
+       </row>
+       <row>
+	<entry>pg_index</entry>
+	<entry> secondary indices</entry>
+       </row>
+       <row>
+	<entry>pg_proc</entry>
+	<entry> procedures (both C and SQL)</entry>
+       </row>
+       <row>
+	<entry>pg_type</entry>
+	<entry> types (both base and complex)</entry>
+       </row>
+       <row>
+	<entry>pg_operator</entry>
+	<entry> operators</entry>
+       </row>
+       <row>
+	<entry>pg_aggregate</entry>
+	<entry> aggregates and aggregate functions</entry>
+       </row>
+       <row>
+	<entry>pg_am</entry>
+	<entry> access methods</entry>
+       </row>
+       <row>
+	<entry>pg_amop</entry>
+	<entry> access method operators</entry>
+       </row>
+       <row>
+	<entry>pg_amproc</entry>
+	<entry> access method support functions</entry>
+       </row>
+       <row>
+	<entry>pg_opclass</entry>
+	<entry> access method operator classes</entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
+   </para>
+
+   <para>
+    <figure float="1" id="EXTEND-CATALOGS">
+     <title>The major <productname>Postgres</productname> system catalogs</title>
+     <graphic fileref="catalogs.gif" format="GIF" align="center"></graphic>
+    </figure>
+
+    The Reference Manual gives a more detailed  explanation
+    of  these catalogs and their attributes.  However,
+    <xref endterm="EXTEND-CATALOGS" linkend="EXTEND-CATALOGS">
+    shows the major entities and their  relationships
+    in  the system catalogs.  (Attributes that do not refer
+    to other entities are not shown unless they are part of
+    a primary key.)
+    This diagram is more or less incomprehensible until you
+    actually start looking at the contents of the  catalogs
+    and  see  how  they relate to each other.  For now, the
+    main things to take away from this diagram are as  follows:
      
-<ItemizedList Mark="bullet" Spacing="compact">
-<ListItem>
-<Para>
-      In  several of the sections that follow, we will
-            present various join queries on the system 
-            catalogs  that display information we need to extend
-            the system.  Looking at this diagram should make
-            some  of  these  join  queries  (which are often
-            three- or four-way joins)  more  understandable,
-            because  you  will  be  able  to  see  that  the
-            attributes used in the queries form foreign keys
-            in other classes.
-</Para>
-</ListItem>
-<ListItem>
-<Para>  Many  different  features  (classes, attributes,
-            functions,  types,  access  methods,  etc.)  are
-            tightly  integrated  in  this  schema.  A simple
-            create command may modify many  of  these  catalogs.
-</Para>
-</ListItem>
-<ListItem>
-<Para>  Types and procedures
-            are central to the schema.
-
-<Note>
-<Para>
-We  use  the words <FirstTerm>procedure</FirstTerm> and <FirstTerm>function</FirstTerm> more or less
-interchangably.
-</Para>
-</Note>
-
-            Nearly  every catalog contains some reference to
-            instances in one or both of these classes.   For
-            example,  <ProductName>Postgres</ProductName>  frequently  uses type 
-            signatures (e.g.,  of  functions  and  operators)  to
-            identify unique instances of other catalogs.
-
-</Para>
-</ListItem>
-<ListItem>
-<Para>  There are many attributes and relationships that
-            have obvious meanings, but there are many  
-            (particularly  those  that  have  to  do with access
-            methods) that do not.  The relationships between
-            pg_am,   pg_amop,   pg_amproc,  pg_operator  and
-            pg_opclass are particularly hard  to  understand
-            and  will  be described in depth (in the section
-            on interfacing types and operators  to  indices)
-            after we have discussed basic extensions.
-</para>
-</ListItem>
-</ItemizedList>
-
-</Para>
-</sect1>
-</Chapter>
+    <itemizedlist spacing="compact" mark="bullet">
+     <listitem>
+      <para>
+       In  several of the sections that follow, we will
+       present various join queries on the system 
+       catalogs  that display information we need to extend
+       the system.  Looking at this diagram should make
+       some  of  these  join  queries  (which are often
+       three- or four-way joins)  more  understandable,
+       because  you  will  be  able  to  see  that  the
+       attributes used in the queries form foreign keys
+       in other classes.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       Many  different  features  (classes, attributes,
+       functions,  types,  access  methods,  etc.)  are
+       tightly  integrated  in  this  schema.  A simple
+       create command may modify many  of  these  catalogs.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       Types and procedures
+       are central to the schema.
+
+       <note>
+	<para>
+	 We  use  the words <firstterm>procedure</firstterm>
+	 and <firstterm>function</firstterm> more or less interchangably.
+	</para>
+       </note>
+
+       Nearly  every catalog contains some reference to
+       instances in one or both of these classes.   For
+       example,  <productname>Postgres</productname>  frequently  uses type 
+       signatures (e.g.,  of  functions  and  operators)  to
+       identify unique instances of other catalogs.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       There are many attributes and relationships that
+       have obvious meanings, but there are many  
+       (particularly  those  that  have  to  do with access
+       methods) that do not.  The relationships between
+       pg_am,   pg_amop,   pg_amproc,  pg_operator  and
+       pg_opclass are particularly hard  to  understand
+       and  will  be described in depth (in the section
+       on interfacing types and operators  to  indices)
+       after we have discussed basic extensions.
+      </para>
+     </listitem>
+    </itemizedlist>
+   </para>
+  </sect1>
+ </chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
+sgml-local-ecat-files:nil
+End:
+-->

doc/src/sgml/indices.sgml

-<chapter id="indices">
-<title>Indices</title>
+ <chapter id="indices">
+  <title id="indices-title">Indices and Keys</title>
 
-<para>
+  <para>
+   Indexes are primarily used to enhance database
+   performance. They should be defined on table columns (or class
+   attributes) which are used as qualifications in repetative queries.
+   Inappropriate use will result in slower performance, since update
+   and insertion times are increased in the presence of indices.
+  </para>
 
-<sect1>
-<title>Partial Indices</title>
+  <para>
+   Two forms of indices may be defined:
 
-<para>
-<note>
-<title>Author</title>
-<para>
-This is from a reply to a question on the e-mail list
-by <ulink url="aoki@CS.Berkeley.EDU">Paul M. Aoki</ulink>
-on 1998-08-11.
+   <itemizedlist>
+    <listitem>
+     <para>
+      For a <firstterm>value index</firstterm>,
+      the key fields for the
+      index are specified as column names; a column may also have
+      an associated operator class. An operator class is used
+      to specify the operators to be used for a particular
+      index. For example, a btree index on four-byte integers
+      would use the <literal>int4_ops</literal> class;
+      this operator class includes
+      comparison functions for four-byte integers. The default
+      operator class is the appropriate operator class for that
+      field type.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      For a <firstterm>functional index</firstterm>, an index is defined
+      on the result of a user-defined function applied
+      to one or more attributes of a single class.
+      These functional indices
+      can be used to obtain fast access to data
+      based on operators that would normally require some
+      transformation to apply them to the base data.
+     </para>
+    </listitem>
+   </itemizedlist>
+  </para>
+
+  <para>
+   Postgres provides btree, rtree and hash access methods for
+   secondary indices.  The btree access method is an implementation of
+   the Lehman-Yao high-concurrency btrees.  The rtree access method
+   implements standard rtrees using Guttman's quadratic split algorithm.
+   The hash access method is an implementation of Litwin's linear
+   hashing.  We mention the algorithms used solely to indicate that all
+   of these access methods are fully dynamic and do not have to be
+   optimized periodically (as is the case with, for example, static hash
+   access methods).
+  </para>
+
+  <para>
+   The Postgres query optimizer will consider using btree indices in a scan
+   whenever an indexed attribute is involved in a comparison using one of:
+
+   <simplelist type="inline">
+    <member>&lt;</member>
+    <member>&lt;=</member>
+    <member>=</member>
+    <member>&gt;=</member>
+    <member>&gt;</member>
+   </simplelist>
+  </para>
+
+  <para>
+   Both box classes support indices on the <literal>box</literal> data 
+   type in <productname>Postgres</productname>.
+   The difference between them is that <literal>bigbox_ops</literal>
+   scales box coordinates down, to avoid floating point exceptions from
+   doing multiplication, addition, and subtraction on very large
+   floating-point coordinates.  If the field on which your rectangles lie
+   is about 20,000 units square or larger, you should use
+   <literal>bigbox_ops</literal>.
+   The <literal>poly_ops</literal> operator class supports rtree
+   indices on <literal>polygon</literal> data.
+  </para>
+
+  <para>
+   The <productname>Postgres</productname>
+   query optimizer will consider using an rtree index whenever
+   an indexed attribute is involved in a comparison using one of:
+
+   <simplelist type="inline">
+    <member>&lt;&lt;</member>
+    <member>&amp;&lt;</member>
+    <member>&amp;&gt;</member>
+    <member>&gt;&gt;</member>
+    <member>@</member>
+    <member>~=</member>
+    <member>&amp;&amp;</member>
+   </simplelist>
+  </para>
+
+  <para>
+   The <productname>Postgres</productname>
+   query optimizer will consider using a hash index whenever
+   an indexed attribute is involved in a comparison using
+   the <literal>=</literal> operator.
+  </para>
+
+  <para>
+   Currently, only the BTREE access method supports multi-column
+   indexes. Up to 7 keys may be specified.
+  </para>
+
+  <para>
+   Use <xref endterm="sql-dropindex-title"
+    linkend="sql-dropindex-title">
+   to remove an index.
+  </para>
+
+  <para>
+   The <literal>int24_ops</literal>
+   operator class is useful for constructing indices on int2 data, and
+   doing comparisons against int4 data in query qualifications.
+   Similarly, <literal>int42_ops</literal>
+   support indices on int4 data that is to be compared against int2 data
+   in queries.
+  </para>
+
+  <para>
+   The following select list returns all ops_names:
+
+   <programlisting>
+SELECT am.amname AS acc_name,
+       opc.opcname AS ops_name,
+       opr.oprname AS ops_comp
+    FROM pg_am am, pg_amop amop,
+         pg_opclass opc, pg_operator opr
+    WHERE amop.amopid = am.oid AND
+          amop.amopclaid = opc.oid AND
+          amop.amopopr = opr.oid
+    ORDER BY acc_name, ops_name, ops_comp
+   </programlisting>
+  </para>
+
+  <sect1 id="keys">
+   <title id="keys-title">Keys</title>
+
+   <para>
+    <note>
+     <title>Author</title>
+     <para>
+      Written by 
+      <ulink url="herouth@oumail.openu.ac.il">Herouth Maoz</ulink>
+      This originally appeared on the User's Mailing List on 1998-03-02
+      in response to the question:
+      "What is the difference between PRIMARY KEY and UNIQUE constraints?".
+     </para>
+    </note>
+   </para>
+
+   <para>
+    <programlisting>
+Subject: Re: [QUESTIONS] PRIMARY KEY | UNIQUE
+
+        What's the difference between:
+
+              PRIMARY KEY(fields,...) and
+              UNIQUE (fields,...)
+
+       - Is this an alias?
+       - If PRIMARY KEY is already unique, then why
+         is there another kind of key named UNIQUE?
+    </programlisting>
+   </para>
+
+   <para>
+    A primary key is the field(s) used to identify a specific row. For example,
+    Social Security numbers identifying a person.
+   </para>
+
+   <para>
+    A simply UNIQUE combination of fields has nothing to do with identifying
+    the row. It's simply an integrity constraint. For example, I have
+    collections of links. Each collection is identified by a unique number,
+    which is the primary key. This key is used in relations.
+   </para>
+
+   <para>
+    However, my application requires that each collection will also have a
+    unique name. Why? So that a human being who wants to modify a collection
+    will be able to identify it. It's much harder to know, if you have two
+    collections named "Life Science", the the one tagged 24433 is the one you
+    need, and the one tagged 29882 is not.
+   </para>
+
+   <para>
+    So, the user selects the collection by its name. We therefore make sure,
+    withing the database, that names are unique. However, no other table in the
+    database relates to the collections table by the collection Name. That
+    would be very inefficient.
+   </para>
+
+   <para>
+    Moreover, despite being unique, the collection name does not actually
+    define the collection! For example, if somebody decided to change the name
+    of the collection from "Life Science" to "Biology", it will still be the
+    same collection, only with a different name. As long as the name is unique,
+    that's OK.
+   </para>
+
+   <para>
+    So:
+
+    <itemizedlist>
+     <listitem>
+      <para>
+       Primary key:
+       <itemizedlist spacing="compact" mark="bullet">
+	<listitem>
+	 <para>
+	  Is used for identifying the row and relating to it.
+	 </para>
+	</listitem>
+	<listitem>
+	 <para>
+	  Is impossible (or hard) to update.
+	 </para>
+	</listitem>
+	<listitem>
+	 <para>
+	  Should not allow NULLs.
+	 </para>
+	</listitem>
+       </itemizedlist>
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       Unique field(s):
+       <itemizedlist spacing="compact" mark="bullet">
+	<listitem>
+	 <para>
+	  Are used as an alternative access to the row.
+	 </para>
+	</listitem>
+	<listitem>
+	 <para>
+	  Are updateable, so long as they are kept unique.
+	 </para>
+	</listitem>
+	<listitem>
+	 <para>
+	  NULLs are acceptable.
+	 </para>
+	</listitem>
+       </itemizedlist>
+      </para>
+     </listitem>
+    </itemizedlist>
+   </para>
+
+   <para>
+    As for why no non-unique keys are defined explicitly in standard
+    <acronym>SQL</acronym> syntax? Well, you
+    must understand that indices are implementation-dependent.
+    <acronym>SQL</acronym> does not
+    define the implementation, merely the relations between data in the
+    database. <productname>Postgres</productname> does allow
+    non-unique indices, but indices
+    used to enforce <acronym>SQL</acronym> keys are always unique.
+   </para>
+
+   <para>
+    Thus, you may query a table by any combination of its columns, despite the
+    fact that you don't have an index on these columns. The indexes are merely
+    an implementational aid which each <acronym>RDBMS</acronym> offers
+    you, in order to cause
+    commonly used queries to be done more efficiently.
+    Some <acronym>RDBMS</acronym> may give you
+    additional measures, such as keeping a key stored in main memory. They will
+    have a special command, for example
+    <programlisting>
+CREATE MEMSTORE ON &lt;table&gt; COLUMNS &lt;cols&gt;
+    </programlisting>
+    (this is not an existing command, just an example).
+   </para>
+
+   <para>
+    In fact, when you create a primary key or a unique combination of fields,
+    nowhere in the <acronym>SQL</acronym> specification does it say
+    that an index is created, nor that
+    the retrieval of data by the key is going to be more efficient than a
+    sequential scan!
+   </para>
+
+   <para>
+    So, if you want to use a combination of fields which is not unique as a
+    secondary key, you really don't have to specify anything - just start
+    retrieving by that combination! However, if you want to make the retrieval
+    efficient, you'll have to resort to the means your
+    <acronym>RDBMS</acronym> provider gives you
+    - be it an index, my imaginary MEMSTORE command, or an intelligent
+    <acronym>RDBMS</acronym>
+    which creates indices without your knowledge based on the fact that you have
+    sent it many queries based on a specific combination of keys... (It learns
+    from experience).
+   </para>
+  </sect1>
+
+  <sect1 id="partial-index">
+   <title id="partial-index-title">Partial Indices</title>
+
+   <note>
+    <title>Author</title>
+    <para>
+     This is from a reply to a question on the e-mail list
+     by <ulink url="aoki@CS.Berkeley.EDU">Paul M. Aoki</ulink>
+     on 1998-08-11.
 <!--
   Paul M. Aoki         | University of California at Berkeley
   aoki@CS.Berkeley.EDU | Dept. of EECS, Computer Science Division #1776
                        | Berkeley, CA 94720-1776
 -->
-</note>
-
-A <firstterm>partial index</firstterm>
-is an index built over a subset of a table; the subset is defined by
-a predicate.  <productname>Postgres</productname>
- supported partial indices with arbitrary
-predicates.  I believe IBM's db2 for as/400 supports partial indices
-using single-clause predicates.
-
-<para>
-The main motivation for partial indices is this:
-if all of the queries you ask that can
-profitably use an index fall into a certain range, why build an index
-over the whole table and suffer the associated space/time costs?
-
-(There are other reasons too; see 
-<xref linkend="STON89b-full" endterm="STON89b"> for details.)
-
-<para>
-The machinery to build, update and query partial indices isn't too
-bad.  The hairy parts are index selection (which indices do I build?)
-and query optimization (which indices do I use?); i.e., the parts
-that involve deciding what predicate(s) match the workload/query in
-some useful way.  For those who are into database theory, the problems
-are basically analogous to the corresponding materialized view
-problems, albeit with different cost parameters and formulae.  These
-are, in the general case, hard problems for the standard ordinal 
-<acronym>SQL</acronym>
-types; they're super-hard problems with black-box extension types,
-because the selectivity estimation technology is so crude.
-
-<para>
-Check <xref linkend="STON89b-full" endterm="STON89b">,
-<xref linkend="OLSON93-full" endterm="OLSON93">,
-and
-<xref linkend="SESHADRI95-full" endterm="SESHADRI95">
-for more information.
+    </para>
+   </note>
+
+   <para>
+    A <firstterm>partial index</firstterm>
+    is an index built over a subset of a table; the subset is defined by
+    a predicate.  <productname>Postgres</productname>
+    supported partial indices with arbitrary
+    predicates.  I believe IBM's db2 for as/400 supports partial indices
+    using single-clause predicates.
+   </para>
+
+   <para>
+    The main motivation for partial indices is this:
+    if all of the queries you ask that can
+    profitably use an index fall into a certain range, why build an index
+    over the whole table and suffer the associated space/time costs?
+
+    (There are other reasons too; see 
+    <xref endterm="STON89b" linkend="STON89b-full"> for details.)
+   </para>
+
+   <para>
+    The machinery to build, update and query partial indices isn't too
+    bad.  The hairy parts are index selection (which indices do I build?)
+    and query optimization (which indices do I use?); i.e., the parts
+    that involve deciding what predicate(s) match the workload/query in
+    some useful way.  For those who are into database theory, the problems
+    are basically analogous to the corresponding materialized view
+    problems, albeit with different cost parameters and formulae.  These
+    are, in the general case, hard problems for the standard ordinal 
+    <acronym>SQL</acronym>
+    types; they're super-hard problems with black-box extension types,
+    because the selectivity estimation technology is so crude.
+   </para>
+
+   <para>
+    Check <xref endterm="STON89b" linkend="STON89b-full">,
+    <xref endterm="OLSON93" linkend="OLSON93-full">,
+    and
+    <xref endterm="SESHADRI95" linkend="SESHADRI95-full">
+    for more information.
+   </para>
+  </sect1>
+ </chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->

doc/src/sgml/lisp.sgml

+ <chapter id="lisp">
+  <title id="lisp-title">Lisp Programming Interface</title>
+
+  <abstract>
+   <para>
+    <filename>pg.el</filename> is a socket-level interface to
+    <productname>Postgres</productname> for emacs.
+   </para>
+  </abstract>
+
+  <note>
+   <title>Author</title>
+   <para>
+    Written by
+    <ulink url="mailto:emarsden@mail.dotcom.fr">Eric Marsden</ulink>
+    on 21 Jul 1999.
+   </para>
+  </note>
+
+  <para>
+   <filename>pg.el</filename> is a socket-level interface to
+   <productname>Postgres</productname> for emacs (text
+   editor extraordinaire). The module is capable of type coercions from a
+   range of SQL types to the equivalent Emacs Lisp type. It currently
+   supports neither crypt or Kerberos authentication, nor large objects.
+  </para>
+
+  <para>
+   The code (version 0.2) is available under GNU GPL from
+   <ulink url="http://www.chez.com/emarsden/downloads/pg.el">
+    http://www.chez.com/emarsden/downloads/pg.el</ulink>
+  </para>
+
+  <para>
+Changes since last release:
+
+   <itemizedlist mark="bullet" spacing="compact">
+    <listitem>
+     <para>
+      now works with XEmacs (tested with Emacs 19.34 & 20.2, and XEmacs
+      20.4)
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      added functions to provide database metainformation (list of
+      databases, of tables, of columns)
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      arguments to `pg:result' are now :keywords
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      MULE-resistant
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      more self-testing code
+     </para>
+    </listitem>
+   </itemizedlist>
+  </para>
+
+  <para>
+   Please note that this is a programmer's API, and doesn't provide any
+   form of user interface. Example:
+
+   <programlisting>
+ (defun demo ()
+    (interactive)
+    (let* ((conn (pg:connect "template1" "postgres" "postgres"))
+           (res (pg:exec conn "SELECT * from scshdemo WHERE a = 42")))
+      (message "status is %s"   (pg:result res :status))
+      (message "metadata is %s" (pg:result res :attributes))
+      (message "data is %s"     (pg:result res :tuples))
+      (pg:disconnect conn)))
+   </programlisting>
+  </para>
+ </chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
+sgml-local-ecat-files:nil
+End:
+-->

doc/src/sgml/oper.sgml

@@ -12,7 +12,7 @@
    <ProductName>Postgres</ProductName> provides a large number of 
    built-in operators on system types.
    These operators are declared in the system catalog
-   pg_operator.  Every entry in pg_operator includes
+   <literal>pg_operator</literal>.  Every entry in <literal>pg_operator</literal> includes
    the name of the procedure that implements the operator and the
    class <Acronym>OIDs</Acronym> of the input and output types.
   </Para>

doc/src/sgml/postgres.sgml

-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.28 1999/06/23 06:15:12 thomas Exp $
-
-Postgres integrated documentation.
-Other subset docs should be copied and shrunk from here.
-thomas 1998-02-23
-
-$Log: postgres.sgml,v $
-Revision 1.28  1999/06/23 06:15:12  thomas
-Add backup/restore info to Admin Guide.
-Split management chapter from start-ag.sgml to manage-ag.sgml.
-
-Revision 1.27  1999/06/03 04:21:49  thomas
-Markup changes for v6.5 release.
-Clean out duplicate stuff in odbc.sgml resulting from a faulty patch.
-
-Revision 1.26  1999/06/01 17:26:18  thomas
-Make sure that only one intro is included in the integrated doc.
-Multiple intros cause trouble since they have some section elements
- (e.g. "y2k.sgml") in common leading to duplicate labels.
-Include emacs formatting hints in the intro*.sgml sources.
-
-Revision 1.25  1999/05/27 15:49:08  thomas
-Markup fixes.
-Update for v6.5 release.
-
-Revision 1.24  1999/05/26 17:30:29  thomas
-Add chapters on CVS access, MVCC, SQL theory to the docs.
-Add an appendix with more details on date/time attributes and handling.
-Update most references to Postgres version numbers to 6.5,
- *except* for the porting list which will require a report
- from a successful installation to be updated.
-
-Revision 1.23  1999/05/22 02:27:24  thomas
-Finish initial markup of cvs.sgml, and include it in the programmer's guide
- and the integrated doc. Clean up other markup.
-
-Revision 1.22  1999/05/20 05:39:27  thomas
-Rearrange and consolidate the Admin Guide.
-Add reference pages for utilities and remove standalone chapters for same.
-Add material for an appendix on date/time properties, but not yet
- integrated with the User's Guide.
-Break up the former chapter on pg_options
- into Admin and Programmer's Guides.
-
-Revision 1.21  1999/05/04 02:19:20  thomas
-Include chapters on security and an intro to SQL.
-
-Revision 1.20  1999/04/06 15:41:13  thomas
-Fix markup to include all closing tags.
-Required by newest versions of DocBook and style sheets.
-
-Revision 1.19  1999/03/30 15:23:03  thomas
-Include libpq+.sgml in the doc set.
-Had been omitted from the integrated doc for no good reason.
-
-Revision 1.18  1999/02/13 03:52:46  thomas
-Include chapter on SQL language elements (keywords, etc).
-Should merge with or complement Stefan's Master's Thesis intro to SQL.
-
-Revision 1.17  1999/01/19 16:06:25  thomas
-Merge current.sgml into release.sgml so all release notes are in the same
- file. Per Bruce's preference. Go to it Bruce!
-No info yet for v6.4.2 or upcoming releases.
-
-Revision 1.16  1999/01/07 02:59:45  thomas
-Include installation instructions for WIN32 client-side libraries.
-From Magnus Hagander <mha@sollentuna.net>.
-
-Revision 1.15  1998/12/18 16:23:34  thomas
-Fix typos in rules.sgml.
-Add Emacs configuration block to postgres.sgml.
-
-Revision 1.14  1998/10/31 09:36:34  thomas
-Cleanup for v6.4 release.
-Make new file current.sgml to hold release info for the current release.
- Should be moved to release.sgml before filling with next release info.
-
-Revision 1.13  1998/10/30 19:37:09  thomas
-Minor editing and markup changes as a result of preparing the Postscript
- documentation for v6.4.
-Bigger updates to the installation instructions (install and config).
-
-Revision 1.12  1998/10/27 06:14:01  thomas
-Include configuration chapter with new info on configure and make.
-
-Revision 1.11  1998/10/25 00:24:31  thomas
-Add Y2K statement for intros.
-Make sure notation section is included in most intros.
-
-Revision 1.7-1.10  1998/10/21 05:31:52  thomas
-Include new information from Massimo. Rearrange ODBC docs.
-Add information for operator precedence.
-Split introduction sections into separate files to allow the legal notice
- and notation sections appear in all documents without having the history
- show up everplace too.
-Add full list of reserved and non-reserved key words in syntax.sgml.
-Add a separate chapter to the admin guide on security.
-Move SQL reference pages up into the User's Guide.
-
--->
-
 <!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
 
 <!entity about    SYSTEM "about.sgml">
@@ -123,8 +21,8 @@ Move SQL reference pages up into the User's Guide.
 <!entity datetime SYSTEM "datetime.sgml">
 <!entity environ  SYSTEM "environ.sgml">
 <!entity func     SYSTEM "func.sgml">
+<!entity indices  SYSTEM "indices.sgml">
 <!entity inherit  SYSTEM "inherit.sgml">
-<!entity keys     SYSTEM "keys.sgml">
 <!entity manage   SYSTEM "manage.sgml">
 <!entity mvcc     SYSTEM "mvcc.sgml">
 <!entity oper     SYSTEM "oper.sgml">
@@ -156,28 +54,29 @@ Move SQL reference pages up into the User's Guide.
 <!entity trouble   SYSTEM "trouble.sgml">
 
 <!-- programmer's guide -->
-<!entity intro-pg SYSTEM "intro-pg.sgml">
 <!entity arch-pg  SYSTEM "arch-pg.sgml">
-<!entity extend   SYSTEM "extend.sgml">
-<!entity rules    SYSTEM "rules.sgml">
-<!entity xfunc    SYSTEM "xfunc.sgml">
-<!entity xtypes   SYSTEM "xtypes.sgml">
-<!entity xoper    SYSTEM "xoper.sgml">
-<!entity xaggr    SYSTEM "xaggr.sgml">
-<!entity xindex   SYSTEM "xindex.sgml">
-<!entity gist     SYSTEM "gist.sgml">
 <!entity dfunc    SYSTEM "dfunc.sgml">
-<!entity lobj     SYSTEM "lobj.sgml">
-<!entity trigger  SYSTEM "trigger.sgml">
-<!entity spi      SYSTEM "spi.sgml">
+<!entity ecpg     SYSTEM "ecpg.sgml">
+<!entity extend   SYSTEM "extend.sgml">
 <!entity func-ref SYSTEM "func-ref.sgml">
+<!entity gist     SYSTEM "gist.sgml">
+<!entity intro-pg SYSTEM "intro-pg.sgml">
+<!entity jdbc     SYSTEM "jdbc.sgml">
 <!entity libpq    SYSTEM "libpq.sgml">
 <!entity libpqpp  SYSTEM "libpq++.sgml">
 <!entity libpgtcl SYSTEM "libpgtcl.sgml">
-<!entity ecpg     SYSTEM "ecpg.sgml">
+<!entity lisp     SYSTEM "lisp.sgml">
+<!entity lobj     SYSTEM "lobj.sgml">
 <!entity odbc     SYSTEM "odbc.sgml">
-<!entity jdbc     SYSTEM "jdbc.sgml">
+<!entity rules    SYSTEM "rules.sgml">
+<!entity spi      SYSTEM "spi.sgml">
+<!entity trigger  SYSTEM "trigger.sgml">
+<!entity xaggr    SYSTEM "xaggr.sgml">
+<!entity xfunc    SYSTEM "xfunc.sgml">
+<!entity xindex   SYSTEM "xindex.sgml">
 <!entity xplang   SYSTEM "xplang.sgml">
+<!entity xoper    SYSTEM "xoper.sgml">
+<!entity xtypes   SYSTEM "xtypes.sgml">
 
 <!-- developer's guide -->
 <!entity arch-dev SYSTEM "arch-dev.sgml">
@@ -277,7 +176,7 @@ Your name here...
   &oper;
   &func;
   &typeconv;
-  &keys;
+  &indices;
   &array;
   &inherit;
   &mvcc;
@@ -341,7 +240,6 @@ Your name here...
    &trigger;
    &spi;
    &xplang;
-  <!-- &libpq; -->
  </Part>
 
  <part Id="part-interfaces">
@@ -359,6 +257,7 @@ Your name here...
    &libpgtcl;
    &odbc;
    &jdbc;
+   &lisp;
  </Part>
  
  <part Id="part-developer">

doc/src/sgml/programmer.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.18 1999/06/23 06:21:19 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.19 1999/07/22 15:11:04 thomas Exp $
 
 Postgres Programmer's Guide.
 
 $Log: programmer.sgml,v $
+Revision 1.19  1999/07/22 15:11:04  thomas
+Complete merge of all old man page information.
+lisp.sgml is a placeholder for Eric Marsden's upcoming contribution.
+catalogs.sgml is not yet marked up or integrated.
+ It should perhaps become an appendix.
+
 Revision 1.18  1999/06/23 06:21:19  thomas
 Remove User's Guide entities since they were not being used.
 
@@ -34,28 +40,29 @@ Make new file current.sgml to hold release info for the current release.
 <!entity notation SYSTEM "notation.sgml">
 <!entity y2k      SYSTEM "y2k.sgml">
 
-<!entity intro-pg SYSTEM "intro-pg.sgml">
 <!entity arch-pg  SYSTEM "arch-pg.sgml">
-<!entity extend   SYSTEM "extend.sgml">
-<!entity rules    SYSTEM "rules.sgml">
-<!entity xfunc    SYSTEM "xfunc.sgml">
-<!entity xtypes   SYSTEM "xtypes.sgml">
-<!entity xoper    SYSTEM "xoper.sgml">
-<!entity xaggr    SYSTEM "xaggr.sgml">
-<!entity xindex   SYSTEM "xindex.sgml">
-<!entity gist     SYSTEM "gist.sgml">
 <!entity dfunc    SYSTEM "dfunc.sgml">
-<!entity lobj     SYSTEM "lobj.sgml">
-<!entity trigger  SYSTEM "trigger.sgml">
-<!entity spi      SYSTEM "spi.sgml">
+<!entity ecpg     SYSTEM "ecpg.sgml">
+<!entity extend   SYSTEM "extend.sgml">
 <!entity func-ref SYSTEM "func-ref.sgml">
+<!entity gist     SYSTEM "gist.sgml">
+<!entity intro-pg SYSTEM "intro-pg.sgml">
+<!entity jdbc     SYSTEM "jdbc.sgml">
 <!entity libpq    SYSTEM "libpq.sgml">
 <!entity libpqpp  SYSTEM "libpq++.sgml">
 <!entity libpgtcl SYSTEM "libpgtcl.sgml">
-<!entity ecpg     SYSTEM "ecpg.sgml">
+<!entity lisp     SYSTEM "lisp.sgml">
+<!entity lobj     SYSTEM "lobj.sgml">
 <!entity odbc     SYSTEM "odbc.sgml">
-<!entity jdbc     SYSTEM "jdbc.sgml">
+<!entity rules    SYSTEM "rules.sgml">
+<!entity spi      SYSTEM "spi.sgml">
+<!entity trigger  SYSTEM "trigger.sgml">
+<!entity xaggr    SYSTEM "xaggr.sgml">
+<!entity xfunc    SYSTEM "xfunc.sgml">
+<!entity xindex   SYSTEM "xindex.sgml">
 <!entity xplang   SYSTEM "xplang.sgml">
+<!entity xoper    SYSTEM "xoper.sgml">
+<!entity xtypes   SYSTEM "xtypes.sgml">
 
 <!-- developer's guide -->
 <!entity arch-dev SYSTEM "arch-dev.sgml">
@@ -172,6 +179,7 @@ Disable it until we put in some info.
   &ecpg;
   &odbc;
   &jdbc;
+  &lisp;
  
 <!-- development -->
  

doc/src/sgml/security.sgml

@@ -102,6 +102,221 @@
      </varlistentry>
     </variablelist>
    </para>
+
+   <Sect2>
+    <Title>Host-Based Access Control</Title>
+
+    <Para>
+.SH NAME
+$PGDATA/pg_hba.conf
+.SH DESCRIPTION
+
+     <firstterm>Host-based access control</firstterm>
+     is the name for the basic controls PostgreSQL
+     exercises on what clients are allowed to access a database and how
+     the users on those clients must authenticate themselves.
+    </para>
+
+    <para>
+     Each database system contains a file named
+     <filename>pg_hba.conf</filename>, in its <envar>PGDATA</envar>
+     directory, which controls who can connect to each database.
+    </para>
+
+    <para>
+     Every client accessing a database
+     <emphasis>must</emphasis>
+     be covered by one of
+     the entries in <filename>pg_hba.conf</filename>.
+     Otherwise all attempted connections from that
+     client will be rejected with a "User authentication failed" error
+     message.
+    </para>
+
+    <para>
+     The general format of the <filename>pg_hba.conf</filename>
+     file is of a set of records, one per
+     line.  Blank lines and lines beginning with a hash character
+     ("#") are ignored.  A record is
+     made up of a number of fields which are separated by spaces and/or tabs.
+    </para>
+
+    <para>
+     Connections from clients can be made using UNIX domain sockets or Internet
+     domain sockets (ie. TCP/IP).  Connections made using UNIX domain sockets
+     are controlled using records of the following format:
+
+     <synopsis>
+local <replaceable>database</replaceable> <replaceable>authentication method</replaceable>
+     </synopsis>
+
+     where
+
+     <simplelist>
+      <member>
+       <replaceable>database</replaceable>
+       specifies the database that this record applies to.  The value
+	<literal>all</literal>
+	specifies that it applies to all databases.
+      </member>
+      <member>
+       <replaceable>authentication method</replaceable>
+       specifies the method a user must use to authenticate themselves when
+       connecting to that database using UNIX domain sockets.  The different methods
+       are described below.
+      </member>
+     </simplelist>
+    </para>
+
+    <para>
+     Connections made using Internet domain sockets are controlled using records
+     of the following format.
+
+     <synopsis>
+host <replaceable>database</replaceable> <replaceable>TCP/IP address</replaceable> <replaceable>TCP/IP mask</replaceable> <replaceable>authentication method</replaceable>
+     </synopsis>
+    </para>
+
+    <para>
+     The <replaceable>TCP/IP address</replaceable>
+     is logically anded to both the specified
+     <replaceable>TCP/IP mask</replaceable>
+     and the TCP/IP address
+     of the connecting client.
+     If the two resulting values are equal then the
+     record is used for this connection.  If a connection matches more than one
+     record then the earliest one in the file is used.
+     Both the
+     <replaceable>TCP/IP address</replaceable>
+     and the
+     <replaceable>TCP/IP mask</replaceable>
+     are specified in dotted decimal notation.
+    </para>
+
+    <para>
+     If a connection fails to match any record then the
+     <firstterm>reject</firstterm>
+     authentication method is applied (see below).
+    </para>
+
+    <sect3>
+     <title>Authentication Methods</title>
+
+     <para>
+      The following authentication methods are supported for both UNIX and TCP/IP
+      domain sockets:
+
+      <variablelist>
+       <varlistentry>
+	<term>trust</term>
+	<listitem>
+	 <para>
+	  The connection is allowed unconditionally.
+	 </para>
+	</listitem>
+       </varlistentry>
+
+       <varlistentry>
+	<term>reject</term>
+	<listitem>
+	 <para>
+	  The connection is rejected unconditionally.
+	 </para>
+	</listitem>
+       </varlistentry>
+
+       <varlistentry>
+	<term>crypt</term>
+	<listitem>
+	 <para>
+	  The client is asked for a password for the user.  This is sent encrypted
+	  (using <citetitle>crypt(3)</citetitle>)
+	  and compared against the password held in the 
+	  <filename>pg_shadow</filename> table.
+	  If the passwords match, the connection is allowed.
+	 </para>
+	</listitem>
+       </varlistentry>
+
+       <varlistentry>
+	<term>password</term>
+	<listitem>
+	 <para>
+	  The client is asked for a password for the user.  This is sent in clear
+	  and compared against the password held in the
+	  <filename>pg_shadow</filename> table.
+	  If the passwords match, the connection is allowed.  An optional password file
+	  may be specified after the
+	  <literal>password</literal>
+	  keyword which is used to match the supplied password rather than the pg_shadow
+	  table.  See
+	  <citerefentry><refentrytitle>pg_passwd</refentrytitle></citerefentry>.
+	 </para>
+	</listitem>
+       </varlistentry>
+      </variablelist>
+     </para>
+
+     <para>
+      The following authentication methods are supported for TCP/IP
+      domain sockets only:
+
+      <variablelist>
+       <varlistentry>
+	<term>krb4</term>
+	<listitem>
+	 <para>
+	  Kerberos V4 is used to authenticate the user.
+	 </para>
+	</listitem>
+       </varlistentry>
+
+       <varlistentry>
+	<term>krb5</term>
+	<listitem>
+	 <para>
+	  Kerberos V5 is used to authenticate the user.
+	 </para>
+	</listitem>
+       </varlistentry>
+
+       <varlistentry>
+	<term>ident</term>
+	<listitem>
+	 <para>
+	  The ident server on the client is used to authenticate the user (RFC 1413).
+	  An optional map name may be specified after the
+	  <literal>ident</literal>
+	  keyword which allows ident user names to be mapped onto
+	  <productname>Postgres</productname> user names.
+	  Maps are held in the file
+	  <filename>$<envar>PGDATA</envar>/pg_ident.conf</filename>.
+	 </para>
+	</listitem>
+       </varlistentry>
+      </variablelist>
+     </para>
+    </sect3>
+
+    <sect3>
+     <title>Examples</title>
+
+     <para>
+      <programlisting>
+# Trust any connection via UNIX domain sockets.
+local	trust
+# Trust any connection via TCP/IP from this machine.
+host	all	127.0.0.1	255.255.255.255		trust
+# We don't like this machine.
+host	all	192.168.0.10	255.255.255.0		reject
+# This machine can't encrypt so we ask for passwords in clear.
+host	all	192.168.0.3	255.255.255.0		password
+# The rest of this group of machines should provide encrypted passwords.
+host	all	192.168.0.0	255.255.255.0		crypt
+      </programlisting>
+     </para>
+    </sect3>
+   </sect2>
   </sect1>
 
   <sect1>
@@ -138,20 +353,50 @@
      have to explicitly insert/update the <literal>pg_group table</literal>.
      For example:
 
-        jolly=> insert into pg_group (groname, grosysid, grolist)
-        jolly=>     values ('posthackers', '1234', '{5443, 8261}');
-        INSERT 548224
-        jolly=> grant insert on foo to group posthackers;
-        CHANGE
-        jolly=>
-
-   The fields in pg_group are:
-     * groname: the group name. This a name and should be purely
-       alphanumeric. Do not include underscores or other punctuation.
-     * grosysid: the group id. This is an int4. This should be unique for
-       each group.
-     * grolist: the list of pg_user id's that belong in the group. This
-       is an int4[].
+     <programlisting>
+jolly=> insert into pg_group (groname, grosysid, grolist)
+jolly=>     values ('posthackers', '1234', '{5443, 8261}');
+INSERT 548224
+jolly=> grant insert on foo to group posthackers;
+CHANGE
+jolly=>
+     </programlisting>
+    </para>
+
+    <para>
+     The fields in <filename>pg_group</filename> are:
+
+     <variablelist>
+      <varlistentry>
+       <term>groname</term>
+       <listitem>
+	<para>
+	 The group name. This a name and should be purely
+	 alphanumeric. Do not include underscores or other punctuation.
+	</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>grosysid</term>
+       <listitem>
+	<para>
+	 The group id. This is an int4. This should be unique for
+	 each group.
+	</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>grolist</term>
+       <listitem>
+	<para>
+	 The list of pg_user id's that belong in the group. This
+	 is an int4[].
+	</para>
+       </listitem>
+      </varlistentry>
+     </variablelist>
     </para>
    </sect2>
 

doc/src/sgml/syntax.sgml

@@ -3,14 +3,18 @@
 
   <abstract>
    <para>
-    <acronym>SQL</acronym> manipulates sets of data. The language is
-    composed of various <firstterm>key words</firstterm>. Arithmetic
-    and procedural expressions are allowed. We will cover these topics
-    in this chapter; subsequent chapters will include details on data
-    types, functions, and operators.
+    A description of the general syntax of SQL.
    </para>
   </abstract>
 
+  <para>
+   <acronym>SQL</acronym> manipulates sets of data. The language is
+   composed of various <firstterm>key words</firstterm>. Arithmetic
+   and procedural expressions are allowed. We will cover these topics
+   in this chapter; subsequent chapters will include details on data
+   types, functions, and operators.
+  </para>
+
   <sect1>
    <title>Key Words</title>
 
@@ -230,7 +234,7 @@ MAXVALUE MINVALUE MODE
 NOCREATEDB NOCREATEUSER NOTHING NOTNULL 
 OIDS OPERATOR 
 PASSWORD PROCEDURAL
-RECIPE RENAME  RETURNS ROW RULE
+RECIPE RENAME RETURNS ROW RULE
 SEQUENCE SERIAL SHARE START STATEMENT STDIN STDOUT 
 TRUSTED 
 VALID VERSION
@@ -302,18 +306,455 @@ UNCOMMITTED UNNAMED
    </sect2>
   </sect1>
 
+  <sect1>
+   <title>Comments</title>
+
+   <para>
+    A <firstterm>comment</firstterm>
+    is an arbitrary sequence of characters following double dashes up to the end
+    of the line.  We also support double-slashes as comments, e.g.:
+
+    <programlisting>
+-- This is a standard SQL comment
+// And this is another supported comment style, like C++
+    </programlisting>
+
+We also support C-style block comments, e.g.:
+
+    <programlisting>
+/* multi
+   line
+   comment */
+    </programlisting>
+   </para>
+  </sect1>
+
+  <sect1>
+   <title>Names</title>
+
+   <para>
+    Names in SQL are sequences of less than NAMEDATALEN alphanumeric characters,
+    starting with an alphabetic character.  By default, NAMEDATALEN is set
+    to 32, but at the time the system is built, NAMEDATALEN can be changed
+    by changing the #ifdef in src/backend/include/postgres.h.  Underscore
+    ("_") is considered an alphabetic character.
+   </para>
+  </sect1>
+
+  <sect1>
+   <title>Constants</title>
+
+   <para>
+    There are six types of
+    <firstterm>constants</firstterm>
+    for use in SQL.  They are described below.
+   </para>
+
+   <sect2>
+    <title>String Constants</title>
+
+    <para>
+     <firstterm>Strings</firstterm>
+     in SQL are arbitrary sequences of ASCII characters bounded by single
+     quotes ("'", e.g. 'This is a string').
+     Uppercase alphabetics within strings are accepted
+     literally.  Non-printing characters may be embedded within strings by
+     prepending them with a backslash
+     ("\"; e.g. "\<replaceable>tab</replaceable>".
+     SQL92 allows single quotes to be embedded in strings by typing two 
+     adjacent single quotes (e.g. 'Dianne''s horse'), and for
+     historical reasons <productname>Postgres</productname> also allows 
+     single quotes to be escaped with a backslash
+     (e.g. 'Dianne\'s horse').
+    </para>
+
+    <para>
+     Because of the limitations on
+     instance sizes, string constants are currently limited to a length of
+     a little less than 8192 bytes.  Larger strings may be handled using the
+     Postgres Large Object interface.
+    </para>
+   </sect2>
+
+   <sect2>
+    <title>Integer Constants</title>
+
+    <para>
+     <firstterm>Integer constants</firstterm>
+     in SQL are collection of ASCII digits with no decimal point.  Legal
+     values range from -2147483648 to +2147483647.  This will vary
+     depending on the operating system and host machine.
+    </para>
+   </sect2>
+
+   <sect2>
+    <title>Floating Point Constants</title>
+
+    <para>
+     <firstterm>Floating point constants</firstterm>
+     consist of an integer part, a decimal point, and a fraction part or
+     scientific notation of the following format:
+
+     <synopsis>
+{<replaceable>dig</replaceable>}.{<replaceable>dig</replaceable>} [e [+-] {<replaceable>dig</replaceable>}]
+     </synopsis>
+
+     where <replaceable>dig</replaceable> is one or more digits.
+     You must include at least one <replaceable>dig</replaceable> after the
+     period and after the [+-] if you use those options.  An exponent with
+     a missing mantissa has a mantissa of 1 inserted.  There may be no
+     extra characters embedded in the string.  
+     Floating point constaints are of type float8.
+    </para>
+   </sect2>
+
+   <sect2>
+    <title>Constants of Postgres User-Defined Types</title>
+
+    <para>
+     A constant of an
+     <emphasis>arbitrary</emphasis>
+     type can be entered using the notations:
+
+     <synopsis>
+<replaceable>type</replaceable> '<replaceable>string</replaceable>'
+'<replaceable>string</replaceable>'::<replaceable>type</replaceable>
+CAST '<replaceable>string</replaceable>' AS <replaceable>type</replaceable>
+     </synopsis>
+
+     The value inside the string is passed to the input
+     conversion routine for the type called type-name. The result is a
+     constant of the indicated type.  The explicit typecast may be omitted
+     if there is no ambiguity as to the type the constant must be, in which
+     case it is automatically coerced.
+    </para>
+   </sect2>
+
+   <sect2>
+    <title>Array constants</title>
+
+    <para>
+     <firstterm>Array constants</firstterm>
+     are arrays of any Postgres type, including other arrays, string
+     constants, etc.  The general format of an array constant is the
+     following:
+
+     <synopsis>
+{<replaceable>val1</replaceable><replaceable>delim</replaceable><replaceable>val2</replaceable><replaceable>delim</replaceable>}
+     </synopsis>
+
+     where <replaceable>delim</replaceable>
+     is the delimiter for the type stored in the <literal>pg_type</literal> class.
+     (For built-in types, this is the comma character (",").  An
+     example of an array constant is
+
+     <programlisting>
+{{1,2,3},{4,5,6},{7,8,9}}
+     </programlisting>
+
+     This constant is a two-dimensional, 3 by 3 array consisting of three
+     sub-arrays of integers.
+    </para>
+
+    <para>
+     Individual array elements can and should be placed between quotation
+     marks whenever possible to avoid ambiguity problems with respect to
+     leading white space.
+    </para>
+   </sect2>
+  </sect1>
+
+  <sect1>
+   <title>Fields and Columns</title>
+
+   <sect2>
+    <title>Fields</title>
+
+    <para>
+     A <firstterm>field</firstterm>
+     is either an attribute of a given class or one of the following:
+
+     <variablelist>
+      <varlistentry>
+       <term>oid</term>
+       <listitem>
+	<para>
+	 stands for the unique identifier of an instance which is added by
+	 Postgres to all instances automatically. Oids are not reused and are 32
+	 bit quantities.
+	</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>xmin</term>
+       <listitem>
+	<para>
+	 The identity of the inserting transaction.
+	</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>xmax</term>
+       <listitem>
+	<para>
+	 The identity of the deleting transaction.
+	</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>cmin</term>
+       <listitem>
+	<para>
+	 The command identifier within the transaction.
+	</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>cmax</term>
+       <listitem>
+	<para>
+	 The identity of the deleting command.
+	</para>
+       </listitem>
+      </varlistentry>
+     </variablelist>
+    </para>
+
+    <para>
+     For further information on these fields consult
+     <xref linkend="STON87a" endterm="STON87a">.
+     Times are represented internally as instances of the
+     <literal>abstime</literal>
+     data type.  Transaction and command identifiers are 32 bit quantities.
+     Transactions are assigned sequentially starting at 512.
+    </para>
+   </sect2>
+
+   <sect2>
+    <title>Columns</title>
+
+    <para>
+     A <firstterm>column</firstterm> is a construct of the form:
+
+     <synopsis>
+<replaceable>instance</replaceable>{.<replaceable>composite_field</replaceable>}.<replaceable>field</replaceable> `['<replaceable>number</replaceable>`]'
+     </synopsis>
+
+     <replaceable>instance</replaceable>
+     identifies a particular class and can be thought of as standing for
+     the instances of that class.  An instance variable is either a class
+     name, a surrogate for a class defined by means of a FROM clause,
+     or the keyword NEW or CURRENT.
+     NEW and CURRENT can only appear in the action portion of a rule, while
+     other instance variables can be used in any SQL statement.
+     <replaceable>composite_field</replaceable>
+     is a field of of one of the Postgres composite types,
+     while successive composite fields address attributes in the
+     class(s) to which the composite field evaluates.  Lastly,
+     <replaceable>field</replaceable>
+     is a normal (base type) field in the class(s) last addressed.  If
+     <replaceable>field</replaceable>
+     is of type <literal>array</literal>,
+     then the optional <replaceable>number</replaceable>
+     designator indicates a specific element in the array.  If no number is
+     indicated, then all array elements are returned.
+    </para>
+   </sect2>
+  </sect1>
+
+  <sect1>
+   <title>Operators</title>
+
+   <para>
+    Any built-in system, or user-defined operator may be used in SQL.
+    For the list of built-in and system operators consult
+    <xref linkend="operators" endterm="operators">.
+    For a list of user-defined operators consult your system administrator
+    or run a query on the <literal>pg_operator</literal> class.
+    Parentheses may be used for arbitrary grouping of operators in expressions.
+   </para>
+  </sect1>
+
   <sect1>
    <title>Expressions</title>
 
    <para>
     <acronym>SQL92</acronym> allows <firstterm>expressions</firstterm>
-    to transform data in expressions. Expressions may contain operators
+    to transform data in tables. Expressions may contain operators
     (see <xref linkend="operators-title" endterm="operators-title">
     for more details) and functions
     (<xref linkend="functions-title" endterm="functions-title"> has
     more information).
+   </para>
 
+   <para>
+    An expression is one of the following:
+
+    <simplelist>
+     <member>( a_expr )</member>
+     <member>constant</member>
+     <member>attribute</member>
+     <member><replaceable>a_expr</replaceable> <replaceable>binary_operator</replaceable> <replaceable>a_expr</replaceable></member>
+     <member><replaceable>a_expr</replaceable> <replaceable>right_unary_operator</replaceable></member>
+     <member><replaceable>left_unary_operator</replaceable> <replaceable>a_expr</replaceable></member>
+     <member>parameter</member>
+     <member>functional expressions</member>
+     <member>aggregate expressions</member>
+    </simplelist>
+   </para>
+
+   <para>
+    We have already discussed constants and attributes.  The two kinds of
+    operator expressions indicate respectively binary and left_unary
+    expressions.  The following sections discuss the remaining options.
    </para>
+
+   <sect2>
+    <title>Parameters</title>
+
+    <para>
+     A <firstterm>parameter</firstterm>
+     is used to indicate a parameter in a SQL function.  Typically this
+     is used in SQL function definition statement.  The form of a
+     parameter is:
+
+     <synopsis>
+$<replaceable class="parameter">number</replaceable>
+     </synopsis>
+    </para>
+
+    <para>
+     For example, consider the definition of a function,
+     <function>dept</function>, as
+
+     <programlisting>
+CREATE FUNCTION dept (name)
+	RETURNS dept
+	AS 'select * from 
+	    dept where name=$1'
+	LANGUAGE 'sql';
+     </programlisting>
+    </para>
+   </sect2>
+
+   <sect2>
+    <title>Functional Expressions</title>
+
+    <para>
+     A <firstterm>functional expression</firstterm>
+     is the name of a legal SQL function, followed by its argument list
+     enclosed in parentheses:
+
+     <synopsis>
+<replaceable>function</replaceable> (<replaceable>a_expr</replaceable> [, <replaceable>a_expr</replaceable> )
+     </synopsis>
+    </para>
+
+    <para>
+     For example, the following computes the square root of an employee
+     salary:
+
+     <programlisting>
+sqrt(emp.salary)
+     </programlisting>
+    </para>
+   </sect2>
+
+   <sect2>
+    <title>Aggregate Expression</title>
+
+    <para>
+     An <firstterm>aggregate expression</firstterm>
+     represents a simple aggregate (i.e., one that computes a single value)
+     or an aggregate function (i.e., one that computes a set of values).
+     The syntax is the following:
+
+     <synopsis>
+<replaceable>aggregate_name</replaceable> (<replaceable>attribute</replaceable>)
+     </synopsis>
+
+     where <replaceable>aggregate_name</replaceable>
+     must be a previously defined aggregate.
+    </para>
+   </sect2>
+
+   <sect2>
+    <title>Target List</title>
+
+    <para>
+     A <firstterm>target list</firstterm>
+     is a parenthesized, comma-separated list of one or more elements, each
+     of which must be of the form:
+
+     <synopsis>
+<replaceable>a_expr</replaceable> [ AS <replaceable>result_attname</replaceable> ]
+     </synopsis>
+
+     where <replaceable>result_attname</replaceable>
+     is the name of the attribute to be created (or an
+     already existing attribute name in the case of update statements.)  If
+     <replaceable>result_attname</replaceable>
+     is not present, then 
+     <replaceable>a_expr</replaceable>
+     must contain only one attribute name which is assumed to be the name
+     of the result field.  In <productname>Postgres</productname>
+     default naming is only used if
+     <replaceable>a_expr</replaceable>
+     is an attribute.
+    </para>
+   </sect2>
+
+   <sect2>
+    <title>Qualification</title>
+
+    <para>
+     A <firstterm>qualification</firstterm>
+     consists of any number of clauses connected by the logical operators:
+
+     <simplelist>
+      <member>NOT</member>
+      <member>AND</member>
+      <member>OR</member>
+     </simplelist>
+
+     A clause is an <replaceable>a_expr</replaceable>
+     that evaluates to a <literal>boolean</literal> over a set of instances.
+    </para>
+   </sect2>
+
+   <sect2>
+    <title>From List</title>
+
+    <para>
+     The <firstterm>from list</firstterm>
+     is a comma-separated list of <firstterm>from expressions</firstterm>.
+     Each "from expression" is of the form:
+
+     <synopsis>
+[ <replaceable>class_reference</replaceable> ] <replaceable>instance_variable</replaceable>
+	{, [ <replaceable>class_ref</replaceable> ] <replaceable>instance_variable</replaceable>... }
+     </synopsis>
+
+     where <replaceable>class_reference</replaceable>
+     is of the form
+
+     <synopsis>
+<replaceable>class_name</replaceable> [ * ]
+     </synopsis>
+
+     The "from expression"
+     defines one or more instance variables to range over the class
+     indicated in <replaceable>class_reference</replaceable>.
+     One can also request 
+     the instance variable to range over all classes that are beneath the
+     indicated class in the inheritance hierarchy by postpending the
+     designator asterisk ("*").
+    </para>
+   </sect2>
   </sect1>
  </chapter>
 

doc/src/sgml/user.sgml

-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.12 1999/06/03 04:21:51 thomas Exp $
-
-Postgres User's Manual.
-Derived from postgres.sgml.
-thomas 1998-02-24
-
-$Log: user.sgml,v $
-Revision 1.12  1999/06/03 04:21:51  thomas
-Markup changes for v6.5 release.
-Clean out duplicate stuff in odbc.sgml resulting from a faulty patch.
-
-Revision 1.11  1999/05/26 17:30:30  thomas
-Add chapters on CVS access, MVCC, SQL theory to the docs.
-Add an appendix with more details on date/time attributes and handling.
-Update most references to Postgres version numbers to 6.5,
- *except* for the porting list which will require a report
- from a successful installation to be updated.
-
-Revision 1.10  1999/05/22 02:27:25  thomas
-Finish initial markup of cvs.sgml, and include it in the programmer's guide
- and the integrated doc. Clean up other markup.
-
-Revision 1.9  1999/05/20 05:39:29  thomas
-Rearrange and consolidate the Admin Guide.
-Add reference pages for utilities and remove standalone chapters for same.
-Add material for an appendix on date/time properties, but not yet
- integrated with the User's Guide.
-Break up the former chapter on pg_options
- into Admin and Programmer's Guides.
-
-Revision 1.8  1999/05/04 02:26:06  thomas
-Include new introductory chapter on SQL from Stefan S.
-Should this be in the tutorial instead?
-
-Revision 1.7  1998/10/30 19:37:16  thomas
-Minor editing and markup changes as a result of preparing the Postscript
- documentation for v6.4.
-Bigger updates to the installation instructions (install and config).
-
-Revision 1.6  1998/09/30 05:41:54  thomas
-Clean up pages. Add information for operator precedence.
-Split introduction sections into separate files to allow the legal notice
- and notation sections appear in all documents without having the history
- show up everplace too.
-Add full list of reserved and non-reserved key words in syntax.sgml.
-Add a separate chapter to the admin guide on security.
-
-Revision 1.5  1998/08/17 16:20:32  thomas
-Move SQL reference pages up into the User's Guide.
-
--->
-
 <!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
 
 <!entity about    SYSTEM "about.sgml">
@@ -67,9 +14,9 @@ Move SQL reference pages up into the User's Guide.
 <!entity datetime SYSTEM "datetime.sgml">
 <!entity environ  SYSTEM "environ.sgml">
 <!entity func     SYSTEM "func.sgml">
+<!entity indices  SYSTEM "indices.sgml">
 <!entity inherit  SYSTEM "inherit.sgml">
 <!entity intro    SYSTEM "intro.sgml">
-<!entity keys     SYSTEM "keys.sgml">
 <!entity manage   SYSTEM "manage.sgml">
 <!entity mvcc     SYSTEM "mvcc.sgml">
 <!entity oper     SYSTEM "oper.sgml">
@@ -157,7 +104,7 @@ Your name here...
  &oper;
  &func;
  &typeconv;
- &keys;
+ &indices;
  &array;
  &inherit;
  &mvcc;

doc/src/sgml/xfunc.sgml

-<Chapter Id="xfunc">
-<Title>Extending <Acronym>SQL</Acronym>: Functions</Title>
-
-<Para>
-     As  it  turns  out,  part of defining a new type is the
-     definition of functions  that  describe  its  behavior.
-     Consequently,  while  it  is  possible  to define a new
-     function without defining a new type,  the  reverse  is
-     not  true.   We therefore describe how to add new functions 
-     to <ProductName>Postgres</ProductName> before  describing  
-     how  to  add  new types.
-     <ProductName>Postgres</ProductName>  <Acronym>SQL</Acronym>  
-     provides  two  types of functions: query language functions 
-     (functions written in <Acronym>SQL</Acronym>  and  programming  
-     language  functions  (functions  written in a compiled 
-     programming language such as <Acronym>C</Acronym>.)  Either  kind
-     of  function  can take a base type, a composite type or
-     some combination as arguments (parameters).   In  addition, 
-     both kinds of functions can return a base type or
-     a composite type.  It's easier to define <Acronym>SQL</Acronym> 
-     functions, so we'll start with those.  Examples in this section 
-     can also be found in <FileName>funcs.sql</FileName> 
-     and <FileName>funcs.c</FileName>.
-</Para>
-
-<Sect1>
-<Title>Query Language (<Acronym>SQL</Acronym>) Functions</Title>
-
-<Sect2>
-<Title><Acronym>SQL</Acronym> Functions on Base Types</Title>
-
-<Para>
-     The simplest possible <Acronym>SQL</Acronym> function has no arguments and
-     simply returns a base type, such as <Acronym>int4</Acronym>:
+ <chapter id="xfunc">
+  <title id="xfunc-title">Extending <acronym>SQL</acronym>: Functions</title>
+
+  <para>
+   As  it  turns  out,  part of defining a new type is the
+   definition of functions  that  describe  its  behavior.
+   Consequently,  while  it  is  possible  to define a new
+   function without defining a new type,  the  reverse  is
+   not  true.   We therefore describe how to add new functions 
+   to <productname>Postgres</productname> before  describing  
+   how  to  add  new types.
+  </para>
+
+  <para>
+   <productname>Postgres</productname>  <acronym>SQL</acronym>  
+   provides  three types of functions:
+
+   <itemizedlist>
+    <listitem>
+     <para>
+      query language functions 
+      (functions written in <acronym>SQL</acronym>)
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      procedural language 
+      functions (functions written in, for example, PLTCL or PLSQL)
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      programming  
+      language  functions  (functions  written in a compiled 
+      programming language such as <acronym>C</acronym>)
+     </para>
+    </listitem>
+   </itemizedlist>
+
+   Every kind
+   of  function  can take a base type, a composite type or
+   some combination as arguments (parameters).   In  addition, 
+   every kind of function can return a base type or
+   a composite type.  It's easiest to define <acronym>SQL</acronym> 
+   functions, so we'll start with those.  Examples in this section 
+   can also be found in <filename>funcs.sql</filename> 
+   and <filename>funcs.c</filename>.
+  </para>
+
+  <sect1>
+   <title>Query Language (<acronym>SQL</acronym>) Functions</title>
+
+   <para>
+    SQL functions execute an arbitrary list of SQL queries, returning
+    the results of the last query in the list.  SQL functions in general
+    return sets.  If their returntype is not specified as a
+    <literal>setof</literal>,
+    then an arbitrary element of the last query's result will be returned.
+   </para>
+
+   <para>
+    The body of a SQL function following AS
+    should be a list of queries separated by whitespace characters and
+    bracketed within quotation marks.  Note that quotation marks used in
+    the queries must be escaped, by preceding them with two
+    backslashes.
+   </para>
+
+   <para>
+    Arguments to the SQL function may be referenced in the queries using
+    a $n syntax: $1 refers to the first argument, $2 to the second, and so
+    on.  If an argument is complex, then a <firstterm>dot</firstterm>
+    notation (e.g. "$1.emp") may be
+    used to access attributes of the argument or
+    to invoke functions.
+   </para>
+
+   <sect2>
+    <title>Examples</title>
+
+    <para>
+     To illustrate a simple SQL function, consider the following,
+     which might be used to debit a bank account:
+
+     <programlisting>
+create function TP1 (int4, float8) returns int4
+    as 'update BANK set balance = BANK.balance - $2
+        where BANK.acctountno = $1
+        select(x = 1)'
+    language 'sql';
+     </programlisting>
+
+     A user could execute this function to debit account 17 by $100.00 as
+     follows:
+
+     <programlisting>
+select (x = TP1( 17,100.0));
+     </programlisting>
+    </para>
+
+    <para>
+     The following more interesting example takes a single argument of type
+     EMP, and retrieves multiple results:
+
+     <programlisting>
+select function hobbies (EMP) returns set of HOBBIES
+    as 'select (HOBBIES.all) from HOBBIES
+        where $1.name = HOBBIES.person'
+    language 'sql';
+     </programlisting>
+    </para>
+   </sect2>
+
+   <sect2>
+    <title><acronym>SQL</acronym> Functions on Base Types</title>
+
+    <para>
+     The simplest possible <acronym>SQL</acronym> function has no arguments and
+     simply returns a base type, such as <acronym>int4</acronym>:
      
-<ProgramListing>
+     <programlisting>
     CREATE FUNCTION one() RETURNS int4
      AS 'SELECT 1 as RESULT' LANGUAGE 'sql';
 
@@ -44,23 +129,22 @@
          +-------+
          |1      |
          +-------+
-</ProgramListing>
-
-</Para>
-<Para>
+     </programlisting>
+    </para>
+    <para>
      Notice that we defined a target list for  the  function
      (with  the  name  RESULT),  but  the target list of the
      query that invoked the function overrode the function's
      target  list.   Hence,  the  result  is labelled answer
      instead of one.
-</Para>
-<Para>
-     It's almost as easy to define <Acronym>SQL</Acronym> functions  
+    </para>
+    <para>
+     It's almost as easy to define <acronym>SQL</acronym> functions  
      that take base types as arguments.  In the example below, notice
      how we refer to the arguments within the function as $1
-     and $2.
-     
-<ProgramListing>
+     and $2:
+
+     <programlisting>
     CREATE FUNCTION add_em(int4, int4) RETURNS int4
      AS 'SELECT $1 + $2;' LANGUAGE 'sql';
 
@@ -71,22 +155,22 @@
          +-------+
          |3      |
          +-------+
-</ProgramListing>
-</Para>
-</sect2>
+     </programlisting>
+    </para>
+   </sect2>
 
-<Sect2>
-<Title><Acronym>SQL</Acronym> Functions on Composite Types</Title>
+   <sect2>
+    <title><acronym>SQL</acronym> Functions on Composite Types</title>
 
-<Para>
+    <para>
      When  specifying  functions with arguments of composite
      types (such as EMP), we must  not  only  specify  which
      argument  we  want (as we did above with $1 and $2) but
      also the attributes of  that  argument.   For  example,
      take the function double_salary that computes what your
-     salary would be if it were doubled.
-     
-<ProgramListing>
+     salary would be if it were doubled:
+
+     <programlisting>
     CREATE FUNCTION double_salary(EMP) RETURNS int4
      AS 'SELECT $1.salary * 2 AS salary;' LANGUAGE 'sql';
 
@@ -100,17 +184,17 @@
          +-----+-------+
          |Sam  | 2400  |
          +-----+-------+
-</ProgramListing>
-</para>
-<Para>
+     </programlisting>
+    </para>
+    <para>
      Notice the use of the syntax $1.salary.
      Before launching into the  subject  of  functions  that
      return  composite  types,  we  must first introduce the
      function notation for projecting attributes.  The  simple  way 
      to explain this is that we can usually use the
-     notation attribute(class)  and  class.attribute  interchangably.
-     
-<ProgramListing>
+     notation attribute(class)  and  class.attribute  interchangably:
+
+     <programlisting>
     --
     -- this is the same as:
     --  SELECT EMP.name AS youngster FROM EMP WHERE EMP.age &lt; 30
@@ -124,59 +208,60 @@
          +----------+
          |Sam       |
          +----------+
-</ProgramListing>
-</para>
-<Para>
+     </programlisting>
+    </para>
+    <para>
      As  we shall see, however, this is not always the case.
      This function notation is important when we want to use
      a  function that returns a single instance.  We do this
      by assembling the entire instance within the  function,
      attribute  by attribute.  This is an example of a function 
      that returns a single EMP instance:
-     
-<ProgramListing>
+
+     <programlisting>
     CREATE FUNCTION new_emp() RETURNS EMP
      AS 'SELECT \'None\'::text AS name,
       1000 AS salary,
       25 AS age,
        \'(2,2)\'::point AS cubicle'
       LANGUAGE 'sql';
-</ProgramListing>
-
-</Para>
-<Para>
+     </programlisting>
+    </para>
+    <para>
      In this case we have specified each of  the  attributes
      with  a  constant value, but any computation or expression 
      could have been substituted for these constants.
      Defining a function like this can be tricky.   Some  of
      the more important caveats are as follows:
-     
-     
-<ItemizedList>
-<ListItem>
-<Para>
-     The  target  list  order must be exactly the same as
-     that in which the attributes appear  in  the  CREATE
-     TABLE statement (or when you execute a .*  query).
-</Para>
-      </ListItem>
-      <ListItem>
-<Para>
-You must typecast the expressions (using ::) very carefully 
-or you will see  the  following error:
-        
-<ProgramListing>
-   WARN::function declared to return type EMP does not retrieve (EMP.*)
-</ProgramListing>
-</Para>
-      </ListItem>
-<ListItem>
-<Para>
-When calling a function that returns an instance, we
+
+     <itemizedlist>
+      <listitem>
+       <para>
+	The  target  list  order must be exactly the same as
+	that in which the attributes appear  in  the  CREATE
+	TABLE statement (or when you execute a .*  query).
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+	You must typecast the expressions (using ::) very carefully 
+	or you will see  the  following error:
+
+	<programlisting>
+	 <computeroutput>
+WARN::function declared to return type EMP does not retrieve (EMP.*)
+	 </computeroutput>
+	</programlisting>
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+	When calling a function that returns an instance, we
         cannot retrieve the entire instance.  We must either
         project an attribute out of the instance or pass the
         entire instance into another function.
-<ProgramListing>
+
+	<programlisting>
     SELECT name(new_emp()) AS nobody;
 
             +-------+
@@ -184,35 +269,35 @@ When calling a function that returns an instance, we
             +-------+
             |None   |
             +-------+
-</ProgramListing>
-</Para>
-      </ListItem>
-<ListItem>
-<Para>
-The reason why, in general, we must use the function
+	</programlisting>
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+	The reason why, in general, we must use the function
         syntax  for projecting attributes of function return
         values is that the parser  just  doesn't  understand
         the  other (dot) syntax for projection when combined
         with function calls.
-        
-<ProgramListing>
+
+	<programlisting>
             SELECT new_emp().name AS nobody;
             WARN:parser: syntax error at or near "."
-</ProgramListing>
-</Para>
-      </ListItem>
-</ItemizedList>
-</para>     
-<Para>
-     Any collection of commands in the  <Acronym>SQL</Acronym>  query  
+	</programlisting>
+       </para>
+      </listitem>
+     </itemizedlist>
+    </para>     
+    <para>
+     Any collection of commands in the  <acronym>SQL</acronym>  query  
      language can be packaged together and defined as a function.
-     The commands can include updates (i.e., <Acronym>insert</Acronym>,  
-     <Acronym>update</Acronym> and <Acronym>delete</Acronym>) as well 
-     as <Acronym>select</Acronym> queries.  However, the final command 
-     must be a <Acronym>select</Acronym> that returns whatever is
+     The commands can include updates (i.e., <acronym>insert</acronym>,  
+     <acronym>update</acronym> and <acronym>delete</acronym>) as well 
+     as <acronym>select</acronym> queries.  However, the final command 
+     must be a <acronym>select</acronym> that returns whatever is
      specified as the function's returntype.
-     
-<ProgramListing>
+
+     <programlisting>
     CREATE FUNCTION clean_EMP () RETURNS int4
      AS 'DELETE FROM EMP WHERE EMP.salary &lt;= 0;
     SELECT 1 AS ignore_this'
@@ -226,74 +311,312 @@ The reason why, in general, we must use the function
          |1 |
          +--+
          
-</ProgramListing>
-</Para>
-</sect2>
-</sect1>
+     </programlisting>
+    </para>
+   </sect2>
+  </sect1>
+
+  <sect1>
+   <title>Procedural Language Functions</title>
+
+   <para>
+    Procedural languages aren't built into Postgres. They are offered
+    by loadable modules. Please refer to the documentation for the
+    PL in question for details about the syntax and how the AS
+    clause is interpreted by the PL handler.
+   </para>
 
-<Sect1>
-<Title>Programming Language Functions</Title>
+   <para>
+    There are two procedural languages available with the standard
+    <productname>Postgres</productname> distribution (PLTCL and PLSQL), and other
+    languages can be defined.
+    Refer to <xref linkend="xplang-title" endterm="xplang-title"> for
+    more information.
+   </para>
+  </sect1>
 
-<Sect2>
-<Title>Programming Language Functions on Base Types</Title>
+  <sect1>
+   <title>Internal Functions</title>
 
-<Para>
-     Internally, <ProductName>Postgres</ProductName> regards a
+   <para>
+    Internal functions are functions written in C which have been statically
+    linked into the <productname>Postgres</productname> backend
+    process. The AS
+    clause gives the C-language name of the function, which need not be the
+    same as the name being declared for SQL use.
+    (For reasons of backwards compatibility, an empty AS
+    string is accepted as meaning that the C-language function name is the
+    same as the SQL name.)  Normally, all internal functions present in the
+    backend are declared as SQL functions during database initialization,
+    but a user could use <command>CREATE FUNCTION</command>
+    to create additional alias names for an internal function.
+   </para>
+  </sect1>
+
+  <sect1>
+   <title>Compiled (C) Language Functions</title>
+
+   <para>
+    Functions written in C can be defined to Postgres, which will dynamically
+    load them into its address space.  The AS
+    clause gives the full path name of the object file that contains the
+    function.  This file is loaded either using
+    load(l)
+    or automatically the first time the function is necessary for
+    execution. Repeated execution of a function will cause negligible
+    additional overhead, as the function will remain in a main memory
+    cache.
+   </para>
+
+   <para>
+    The string which specifies the object file (the string in the AS clause)
+    should be the <emphasis>full path</emphasis>
+    of the object code file for the function, bracketed by quotation
+    marks.  (<productname>Postgres</productname> will not compile a
+    function automatically; it must
+    be compiled before it is used in a CREATE FUNCTION
+    command.  See below for additional information.)
+   </para>
+
+   <sect2>
+    <title>C Language Functions on Base Types</title>
+
+    <para>
+     The following table gives the C type required for parameters in the C
+     functions that will be loaded into Postgres.  The "Defined In"
+     column gives the actual header file (in the
+     <filename>.../src/backend/</filename>
+     directory) that the equivalent C type is defined.  However, if you
+     include <filename>utils/builtins.h</filename>,
+     these files will automatically be
+     included.
+
+     <table tocentry="1">
+      <title>Equivalent C Types
+       for Built-In <productname>Postgres</productname> Types</title>
+      <titleabbrev>Equivalent C Types</titleabbrev>
+      <tgroup cols="3">
+       <thead>
+	<row>
+	 <entry>
+	  Built-In Type
+	 </entry>
+	 <entry>
+	  C Type
+	 </entry>
+	 <entry>
+	  Defined In
+	 </entry>
+	</row>
+       </thead>
+       <tbody>
+	<row>
+	 <entry>abstime</entry>
+	 <entry>AbsoluteTime</entry>
+	 <entry>utils/nabstime.h</entry>
+	</row>
+	<row>
+	 <entry>bool</entry>
+	 <entry>bool</entry>
+	 <entry>include/c.h</entry>
+	</row>
+	<row>
+	 <entry>box</entry>
+	 <entry>(BOX *)</entry>
+	 <entry>utils/geo-decls.h</entry>
+	</row>
+	<row>
+	 <entry>bytea</entry>
+	 <entry>(bytea *)</entry>
+	 <entry>include/postgres.h</entry>
+	</row>
+	<row>
+	 <entry>char</entry>
+	 <entry>char</entry>
+	 <entry>N/A</entry>
+	</row>
+	<row>
+	 <entry>cid</entry>
+	 <entry>CID</entry>
+	 <entry>include/postgres.h</entry>
+	</row>
+	<row>
+	 <entry>datetime</entry>
+	 <entry>(DateTime *)</entry>
+	 <entry>include/c.h or include/postgres.h</entry>
+	</row>
+	<row>
+	 <entry>int2</entry>
+	 <entry>int2</entry>
+	 <entry>include/postgres.h</entry>
+	</row>
+	<row>
+	 <entry>int28</entry>
+	 <entry>(int28 *)</entry>
+	 <entry>include/postgres.h</entry>
+	</row>
+	<row>
+	 <entry>int4</entry>
+	 <entry>int4</entry>
+	 <entry>include/postgres.h</entry>
+	</row>
+	<row>
+	 <entry>float4</entry>
+	 <entry>float32 or (float4 *)</entry>
+	<entry>include/c.h or include/postgres.h</entry>
+	</row>
+	<row>
+	 <entry>float8</entry>
+	 <entry>float64 or (float8 *)</entry>
+	 <entry>include/c.h or include/postgres.h</entry>
+	</row>
+	<row>
+	 <entry>lseg</entry>
+	 <entry>(LSEG *)</entry>
+	 <entry>include/geo-decls.h</entry>
+	</row>
+	<row>
+	 <entry>name</entry>
+	 <entry>(Name)</entry>
+	 <entry>include/postgres.h</entry>
+	</row>
+	<row>
+	 <entry>oid</entry>
+	 <entry>oid</entry>
+	 <entry>include/postgres.h</entry>
+	</row>
+	<row>
+	 <entry>oid8</entry>
+	 <entry>(oid8 *)</entry>
+	 <entry>include/postgres.h</entry>
+	</row>
+	<row>
+	 <entry>path</entry>
+	 <entry>(PATH *)</entry>
+	 <entry>utils/geo-decls.h</entry>
+	</row>
+	<row>
+	 <entry>point</entry>
+	 <entry>(POINT *)</entry>
+	 <entry>utils/geo-decls.h</entry>
+	</row>
+	<row>
+	 <entry>regproc</entry>
+	 <entry>regproc or REGPROC</entry>
+	 <entry>include/postgres.h</entry>
+	</row>
+	<row>
+	 <entry>reltime</entry>
+	 <entry>RelativeTime</entry>
+	 <entry>utils/nabstime.h</entry>
+	</row>
+	<row>
+	 <entry>text</entry>
+	 <entry>(text *)</entry>
+	 <entry>include/postgres.h</entry>
+	</row>
+	<row>
+	 <entry>tid</entry>
+	 <entry>ItemPointer</entry>
+	 <entry>storage/itemptr.h</entry>
+	</row>
+	<row>
+	 <entry>timespan</entry>
+	 <entry>(TimeSpan *)</entry>
+	 <entry>include/c.h or include/postgres.h</entry>
+	</row>
+	<row>
+	 <entry>tinterval</entry>
+	 <entry>TimeInterval</entry>
+	 <entry>utils/nabstime.h</entry>
+	</row>
+	<row>
+	 <entry>uint2</entry>
+	 <entry>uint16</entry>
+	 <entry>include/c.h</entry>
+	</row>
+	<row>
+	 <entry>uint4</entry>
+	 <entry>uint32</entry>
+	 <entry>include/c.h</entry>
+	</row>
+	<row>
+	 <entry>xid</entry>
+	 <entry>(XID *)</entry>
+	 <entry>include/postgres.h</entry>
+	</row>
+       </tbody>
+      </tgroup>
+     </table>
+    </para>
+
+    <para>
+     Internally, <productname>Postgres</productname> regards a
      base type as a "blob  of memory."   The  user-defined  
      functions that you define over a type in turn define the 
-     way  that  <ProductName>Postgres</ProductName> can operate  
-     on  it.  That is, <ProductName>Postgres</ProductName> will 
+     way  that  <productname>Postgres</productname> can operate  
+     on  it.  That is, <productname>Postgres</productname> will 
      only store and retrieve the data from disk and use  your  
      user-defined functions to input, process, and output the data.
      Base types can have one of three internal formats:
-<ItemizedList>
-<ListItem><Para>pass by value, fixed-length</Para>
-      </ListItem>
-<ListItem><Para>pass by reference, fixed-length</Para>
-      </ListItem>
-<ListItem><Para>pass by reference, variable-length</Para>
-      </ListItem>
-</ItemizedList>
-</Para>
-
-<Para>
+
+     <itemizedlist>
+      <listitem>
+       <para>
+	pass by value, fixed-length
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+	pass by reference, fixed-length
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+	pass by reference, variable-length
+       </para>
+      </listitem>
+     </itemizedlist>
+    </para>
+
+    <para>
      By-value  types  can  only be 1, 2 or 4 bytes in length
      (even if your computer supports by-value types of other
-     sizes).   <ProductName>Postgres</ProductName>  itself 
+     sizes).   <productname>Postgres</productname>  itself 
      only passes integer types by value.  You should be careful 
      to define your types such that  they  will  be  the  same  
      size (in bytes) on all architectures.  For example, the 
-     <Acronym>long</Acronym> type is dangerous because  it  
+     <acronym>long</acronym> type is dangerous because  it  
      is 4 bytes on some machines and 8 bytes on others, whereas 
-     <Acronym>int</Acronym>  type  is  4  bytes  on  most  
-     <Acronym>UNIX</Acronym> machines  (though  not  on most 
+     <acronym>int</acronym>  type  is  4  bytes  on  most  
+     <acronym>UNIX</acronym> machines  (though  not  on most 
      personal computers).  A reasonable implementation of  
-     the  <Acronym>int4</Acronym>  type  on  <Acronym>UNIX</Acronym>
+     the  <acronym>int4</acronym>  type  on  <acronym>UNIX</acronym>
      machines might be:
      
-<ProgramListing>
-    /* 4-byte integer, passed by value */
-    typedef int int4;
-</ProgramListing>
-</Para>
+     <programlisting>
+/* 4-byte integer, passed by value */
+typedef int int4;
+     </programlisting>
+    </para>
 
-<Para>
+    <para>
      On  the  other hand, fixed-length types of any size may
      be passed by-reference.  For example, here is a  sample
-     implementation of a <ProductName>Postgres</ProductName> type:
+     implementation of a <productname>Postgres</productname> type:
      
-<ProgramListing>
-         /* 16-byte structure, passed by reference */
-    typedef struct
-    {
-        double  x, y;
-    } Point;
-</ProgramListing>
-</Para>
-
-<Para>
+     <programlisting>
+/* 16-byte structure, passed by reference */
+typedef struct
+{
+    double  x, y;
+} Point;
+     </programlisting>
+    </para>
+
+    <para>
      Only  pointers  to  such types can be used when passing
-     them in and out of <ProductName>Postgres</ProductName> functions.
+     them in and out of <productname>Postgres</productname> functions.
      Finally, all variable-length types must also be  passed
      by  reference.   All  variable-length  types must begin
      with a length field of exactly 4 bytes, and all data to
@@ -302,42 +625,42 @@ The reason why, in general, we must use the function
      length  field  is  the  total  length  of the structure
      (i.e.,  it  includes  the  size  of  the  length  field
      itself).  We can define the text type as follows:
-</Para>
-
-<Para>
-<ProgramListing>
-         typedef struct {
-             int4 length;
-             char data[1];
-         } text;
-</ProgramListing>
-</Para>
-
-<Para>
+
+     <programlisting>
+typedef struct {
+    int4 length;
+    char data[1];
+} text;
+     </programlisting>
+    </para>
+
+    <para>
      Obviously,  the  data  field is not long enough to hold
-     all possible strings -- it's impossible to declare such
-     a  structure  in  <Acronym>C</Acronym>.  When manipulating 
+     all possible strings; it's impossible to declare such
+     a  structure  in  <acronym>C</acronym>.  When manipulating 
      variable-length types, we must  be  careful  to  allocate  
      the  correct amount  of memory and initialize the length field.  
      For example, if we wanted to  store  40  bytes  in  a  text
      structure, we might use a code fragment like this:
-<ProgramListing>
-         #include "postgres.h"
-         ...
-         char buffer[40]; /* our source data */
-         ...
-         text *destination = (text *) palloc(VARHDRSZ + 40);
-         destination-&gt;length = VARHDRSZ + 40;
-         memmove(destination-&gt;data, buffer, 40);
-         ...
-</ProgramListing>
-</Para>
 
-<Para>
+     <programlisting>
+#include "postgres.h"
+...
+char buffer[40]; /* our source data */
+...
+text *destination = (text *) palloc(VARHDRSZ + 40);
+destination-&gt;length = VARHDRSZ + 40;
+memmove(destination-&gt;data, buffer, 40);
+...
+     </programlisting>
+    </para>
+
+    <para>
      Now that we've gone over all of the possible structures
      for base types, we can show some examples of real functions. 
-     Suppose <FileName>funcs.c</FileName> look like:
-<ProgramListing>
+     Suppose <filename>funcs.c</filename> look like:
+
+     <programlisting>
          #include &lt;string.h&gt;
          #include "postgres.h"
 
@@ -394,56 +717,58 @@ The reason why, in general, we must use the function
              strncat(VARDATA(new_text), VARDATA(arg2), VARSIZE(arg2)-VARHDRSZ);
              return (new_text);
          }
-</ProgramListing>
-</Para>
+     </programlisting>
+    </para>
 
-<Para>
-     On <Acronym>OSF/1</Acronym> we would type:
+    <para>
+     On <acronym>OSF/1</acronym> we would type:
      
-<ProgramListing>
+     <programlisting>
          CREATE FUNCTION add_one(int4) RETURNS int4
-              AS 'PGROOT/tutorial/funcs.so' LANGUAGE 'c';
+              AS '<replaceable>PGROOT</replaceable>/tutorial/funcs.so' LANGUAGE 'c';
 
          CREATE FUNCTION makepoint(point, point) RETURNS point
-              AS 'PGROOT/tutorial/funcs.so' LANGUAGE 'c';
+              AS '<replaceable>PGROOT</replaceable>/tutorial/funcs.so' LANGUAGE 'c';
     
          CREATE FUNCTION concat_text(text, text) RETURNS text
-              AS 'PGROOT/tutorial/funcs.so' LANGUAGE 'c';
+              AS '<replaceable>PGROOT</replaceable>/tutorial/funcs.so' LANGUAGE 'c';
                                   
          CREATE FUNCTION copytext(text) RETURNS text
-              AS 'PGROOT/tutorial/funcs.so' LANGUAGE 'c';
-</ProgramListing>
-</Para>
+              AS '<replaceable>PGROOT</replaceable>/tutorial/funcs.so' LANGUAGE 'c';
+     </programlisting>
+    </para>
 
-<Para>
+    <para>
      On  other  systems,  we might have to make the filename
      end in .sl (to indicate that it's a shared library).
-</Para>
-</Sect2>
+    </para>
+   </sect2>
 
-<Sect2>
-<Title>Programming Language Functions on Composite Types</Title>
+   <sect2>
+    <title>C Language Functions on Composite Types</title>
 
-<Para>
+    <para>
      Composite types do not  have  a  fixed  layout  like  C
      structures.   Instances of a composite type may contain
      null fields.  In addition,  composite  types  that  are
      part  of  an  inheritance  hierarchy may have different
      fields than other members of the same inheritance hierarchy.    
-     Therefore,  <ProductName>Postgres</ProductName>  provides  
+     Therefore,  <productname>Postgres</productname>  provides  
      a  procedural interface for accessing fields of composite types  
-     from C.  As <ProductName>Postgres</ProductName> processes 
+     from C.  As <productname>Postgres</productname> processes 
      a set of instances, each instance will be passed into your 
-     function as an  opaque  structure of type <Acronym>TUPLE</Acronym>.
+     function as an  opaque  structure of type <acronym>TUPLE</acronym>.
      Suppose we want to write a function to answer the query
-<ProgramListing>
+
+     <programlisting>
          * SELECT name, c_overpaid(EMP, 1500) AS overpaid
            FROM EMP
            WHERE name = 'Bill' or name = 'Sam';
-</ProgramListing>
+     </programlisting>
+
      In the query above, we can define c_overpaid as:
      
-<ProgramListing>
+     <programlisting>
          #include "postgres.h"
          #include "executor/executor.h"  /* for GetAttributeByName() */
          
@@ -458,136 +783,248 @@ The reason why, in general, we must use the function
                  return (false);
              return(salary &gt; limit);
          }
-</ProgramListing>
-</Para>
+     </programlisting>
+    </para>
 
-<Para>
-     <Acronym>GetAttributeByName</Acronym> is the 
-     <ProductName>Postgres</ProductName> system function that
+    <para>
+     <acronym>GetAttributeByName</acronym> is the 
+     <productname>Postgres</productname> system function that
      returns attributes out of the current instance.  It has
      three arguments: the argument of type TUPLE passed into
      the  function, the name of the desired attribute, and a
      return parameter that describes whether  the  attribute
-     is  null.   <Acronym>GetAttributeByName</Acronym> will 
+     is  null.   <acronym>GetAttributeByName</acronym> will 
      align data properly so you can cast its return value to 
      the  desired  type. For  example, if you have an attribute 
-     name which is of the type name, the <Acronym>GetAttributeByName</Acronym> 
+     name which is of the type name, the <acronym>GetAttributeByName</acronym> 
      call would look like:
-<ProgramListing>
+
+     <programlisting>
          char *str;
          ...
          str = (char *) GetAttributeByName(t, "name", &amp;isnull)
-</ProgramListing>
-</Para>
+     </programlisting>
+    </para>
 
-<Para>
-     The  following  query  lets  <ProductName>Postgres</ProductName>  
+    <para>
+     The  following  query  lets  <productname>Postgres</productname>  
      know  about  the c_overpaid function:
-<ProgramListing>
+
+     <programlisting>
          * CREATE FUNCTION c_overpaid(EMP, int4) RETURNS bool
-              AS 'PGROOT/tutorial/obj/funcs.so' LANGUAGE 'c';
-</ProgramListing>
-</Para>
+              AS '<replaceable>PGROOT</replaceable>/tutorial/obj/funcs.so' LANGUAGE 'c';
+     </programlisting>
+    </para>
 
-<Para>
+    <para>
      While there are ways to construct new instances or modify  
      existing instances from within a C function, these
      are far too complex to discuss in this manual.
-</Para>
-</Sect2>
+    </para>
+   </sect2>
 
-<Sect2>
-<Title>Caveats</Title>
+   <sect2>
+    <title>Writing Code</title>
 
-<Para>
+    <para>
      We now turn to the more difficult task of writing  
      programming  language  functions.  Be warned: this section
      of the manual will not make you a programmer.  You must
-     have  a  good  understanding of <Acronym>C</Acronym> 
+     have  a  good  understanding of <acronym>C</acronym> 
      (including the use of pointers and the malloc memory manager)  
-     before  trying to write <Acronym>C</Acronym> functions for 
-     use with <ProductName>Postgres</ProductName>. While  it may 
+     before  trying to write <acronym>C</acronym> functions for 
+     use with <productname>Postgres</productname>. While  it may 
      be possible to load functions written in languages other 
-     than <Acronym>C</Acronym> into  <ProductName>Postgres</ProductName>,  
+     than <acronym>C</acronym> into  <productname>Postgres</productname>,  
      this  is  often difficult  (when  it  is possible at all) 
-     because other languages, such as <Acronym>FORTRAN</Acronym> 
-     and <Acronym>Pascal</Acronym> often do not follow the same 
-     "calling convention" as <Acronym>C</Acronym>.  That is, other
+     because other languages, such as <acronym>FORTRAN</acronym> 
+     and <acronym>Pascal</acronym> often do not follow the same 
+     <firstterm>calling convention</firstterm>
+     as <acronym>C</acronym>.  That is, other
      languages  do  not  pass  argument  and  return  values
      between functions in the same way.  For this reason, we
      will assume that your  programming  language  functions
-     are written in <Acronym>C</Acronym>.
-     The  basic  rules  for building <Acronym>C</Acronym> functions 
+     are written in <acronym>C</acronym>.
+    </para>
+
+    <para>
+     C functions with base type arguments can be written in a
+     straightforward fashion.  The C equivalents of built-in Postgres types
+     are accessible in a C file if 
+     <filename><replaceable>PGROOT</replaceable>/src/backend/utils/builtins.h</filename>
+     is included as a header file.  This can be achieved by having
+
+     <programlisting>
+#include &lt;utils/builtins.h&gt;
+     </programlisting>
+
+     at the top of the C source file.
+    </para>
+
+    <para>
+     The  basic  rules  for building <acronym>C</acronym> functions 
      are as follows:
 
-<ItemizedList>
-<ListItem>
-<Para>
-            Most of the header (include) files for 
-            <ProductName>Postgres</ProductName>
-            should      already      be     installed     in
-            <FileName>PGROOT/include</FileName>  (see  Figure  2).
-            You should always include
-            
-<ProgramListing>
-                -I$PGROOT/include
-</ProgramListing>
-            on  your  cc  command lines.  Sometimes, you may
-            find that you require header files that  are  in
-            the  server source itself (i.e., you need a file
-            we neglected to install in include).   In  those
-            cases you may need to add one or more of
-<ProgramListing>
-                -I$PGROOT/src/backend
-                -I$PGROOT/src/backend/include
-                -I$PGROOT/src/backend/port/&lt;PORTNAME&gt;
-                -I$PGROOT/src/backend/obj
-</ProgramListing>
-            (where &lt;PORTNAME&gt; is the name of the port, e.g.,
-            alpha or sparc).
-</para>
-</ListItem>
-<ListItem>
-<Para>      When allocating memory, use  the
-            <ProductName>Postgres</ProductName>
-            routines  palloc  and  pfree  instead of the 
-            corresponding <Acronym>C</Acronym> library  routines  
-            malloc  and  free.
-            The  memory  allocated  by  palloc will be freed
-            automatically at the end  of  each  transaction,
-            preventing memory leaks.
-</Para>
-      </ListItem>
-      <ListItem>
-<Para>   Always  zero  the bytes of your structures using
-            memset or bzero.  Several routines (such as  the
-            hash access method, hash join and the sort algorithm) 
-            compute functions of the  raw  bits  contained  in 
-            your structure.  Even if you initialize all fields 
-            of your structure, there  may  be
-            several bytes of alignment padding (holes in the
-            structure) that may contain garbage values.
-</Para>
-      </ListItem>
-      <ListItem>
-<Para>      Most of the internal <ProductName>Postgres</ProductName> 
-            types are declared in  postgres.h,  so  it's a good 
-            idea to always include that file as well.  Including 
-            postgres.h will also include elog.h and palloc.h for you.
-</Para>
-      </ListItem>
-      <ListItem>
-<Para>      Compiling and loading your object code  so  that
-            it  can  be  dynamically  loaded  into  
-            <ProductName>Postgres</ProductName>
-            always requires special flags.  See  Appendix  A
-            for  a  detailed explanation of how to do it for
-            your particular operating system.
-</Para>
-</ListItem>
-</ItemizedList>
-</Para>
-</Sect2>
-</sect1>
-</chapter>
+     <itemizedlist>
+      <listitem>
+       <para>
+	Most of the header (include) files for 
+	<productname>Postgres</productname>
+	should      already      be     installed     in
+	<filename><replaceable>PGROOT</replaceable>/include</filename>  (see  Figure  2).
+	You should always include
+
+	<programlisting>
+-I$PGROOT/include
+	</programlisting>
+
+	on  your  cc  command lines.  Sometimes, you may
+	find that you require header files that  are  in
+	the  server source itself (i.e., you need a file
+	we neglected to install in include).   In  those
+	cases you may need to add one or more of
+
+	<programlisting>
+-I$PGROOT/src/backend
+-I$PGROOT/src/backend/include
+-I$PGROOT/src/backend/port/&lt;PORTNAME&gt;
+-I$PGROOT/src/backend/obj
+	</programlisting>
+
+	(where &lt;PORTNAME&gt; is the name of the port, e.g.,
+	alpha or sparc).
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+	When allocating memory, use  the
+	<productname>Postgres</productname>
+	routines  palloc  and  pfree  instead of the 
+	corresponding <acronym>C</acronym> library  routines  
+	malloc  and  free.
+	The  memory  allocated  by  palloc will be freed
+	automatically at the end  of  each  transaction,
+	preventing memory leaks.
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+	Always  zero  the bytes of your structures using
+	memset or bzero.  Several routines (such as  the
+	hash access method, hash join and the sort algorithm) 
+	compute functions of the  raw  bits  contained  in 
+	your structure.  Even if you initialize all fields 
+	of your structure, there  may  be
+	several bytes of alignment padding (holes in the
+	structure) that may contain garbage values.
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+	    Most of the internal <productname>Postgres</productname> 
+	types are declared in <filename>postgres.h</filename>,
+	    so  it's a good 
+	idea to always include that file as well.  Including 
+	postgres.h will also include elog.h and palloc.h for you.
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+	Compiling and loading your object code  so  that
+	it  can  be  dynamically  loaded  into  
+	<productname>Postgres</productname>
+	always requires special flags.
+	See <xref linkend="dfunc-title" endterm="dfunc-title">
+	for  a  detailed explanation of how to do it for
+	your particular operating system.
+       </para>
+      </listitem>
+     </itemizedlist>
+    </para>
+   </sect2>
+  </sect1>
+
+  <sect1>
+   <title>Function Overloading</title>
+
+   <para>
+    More than one function may be defined with the same name, as long as
+    the arguments they take are different.  In other words, function names
+    can be <firstterm>overloaded</firstterm>.
+    A function may also have the same name as an attribute.  In the case
+    that there is an ambiguity between a function on a complex type and
+    an attribute of the complex type, the attribute will always be used.
+   </para>
+
+   <sect2>
+    <title>Name Space Conflicts</title>
+
+    <para>
+     As of <productname>Postgres</productname> v6.5,
+     <command>CREATE FUNCTION</command> can decouple a C language
+     function name from the name of the entry point. This is now the
+     preferred technique to accomplish function overloading.
+    </para>
+
+    <sect3>
+     <title>Pre-v6.5</title>
+
+     <para>
+      For functions written in C, the SQL name declared in
+      <command>CREATE FUNCTION</command>
+      must be exactly the same as the actual name of the function in the
+      C code (hence it must be a legal C function name).
+     </para>
+
+     <para>
+      There is a subtle implication of this restriction: while the
+      dynamic loading routines in most operating systems are more than 
+      happy to allow you to load any number of shared libraries that 
+      contain conflicting (identically-named) function names, they may 
+      in fact botch the load in interesting ways.  For example, if you
+      define a dynamically-loaded function that happens to have the
+      same name as a function built into Postgres, the DEC OSF/1 dynamic 
+      loader causes Postgres to call the function within itself rather than 
+      allowing Postgres to call your function.  Hence, if you want your
+      function to be used on different architectures, we recommend that 
+      you do not overload C function names.
+     </para>
+
+     <para>
+      There is a clever trick to get around the problem just described.
+      Since there is no problem overloading SQL functions, you can 
+      define a set of C functions with different names and then define 
+      a set of identically-named SQL function wrappers that take the
+      appropriate argument types and call the matching C function.
+     </para>
+
+     <para>
+      Another solution is not to use dynamic loading, but to link your
+      functions into the backend statically and declare them as INTERNAL
+      functions.  Then, the functions must all have distinct C names but
+      they can be declared with the same SQL names (as long as their
+      argument types differ, of course).  This way avoids the overhead of
+      an SQL wrapper function, at the cost of more effort to prepare a
+      custom backend executable.
+     </para>
+    </sect3>
+   </sect2>
+  </sect1>
+ </chapter>
 
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
+sgml-local-ecat-files:nil
+End:
+-->

doc/src/sgml/xindex.sgml

+<!--
+$Header: /cvsroot/pgsql/doc/src/sgml/xindex.sgml,v 1.5 1999/07/22 15:11:05 thomas Exp $
+Postgres documentation
+-->
+
  <chapter id="xindex">
   <title>Interfacing Extensions To Indices</title>
 

doc/src/sgml/xplang.sgml

-<Chapter Id="xplang">
-<Title>Procedural Languages</Title>
+ <chapter id="xplang">
+  <title id="xplang-title">Procedural Languages</title>
 
 <!-- **********
      * General information about procedural language support
      **********
 -->
 
-<Para>
+<para>
     Beginning with the release of version 6.3,
-    <ProductName>Postgres</ProductName> supports
+    <productname>Postgres</productname> supports
     the definition of procedural languages.
     In the case of a function or trigger
     procedure defined in a procedural language, the database has
@@ -18,60 +18,60 @@
     handler itself is a special programming language function
     compiled into a shared object
     and loaded on demand.
-</Para>
+</para>
 
 <!-- **********
      * Installation of procedural languages
      **********
 -->
 
-<Sect1>
-<Title>Installing Procedural Languages</Title>
+<sect1>
+<title>Installing Procedural Languages</title>
 
-<Procedure>
-    <Title>
+<procedure>
+    <title>
     Procedural Language Installation
-    </Title>
+    </title>
 
     <para>
     A procedural language is installed in the database in three steps.
     </para>
-	<Step Performance="Required">
-	    <Para>
+	<step performance="Required">
+	    <para>
 	        The shared object for the language handler
 		must be compiled and installed. By default the
 		handler for PL/pgSQL is built and installed into the
 		database library directory. If Tcl/Tk support is
 		configured in, the handler for PL/Tcl is also built
 		and installed in the same location.
-	    </Para>
-	    <Para>
+	    </para>
+	    <para>
 	        Writing a handler for a new procedural language (PL)
 		is outside the scope of this manual. 
-	    </Para>
-	</Step>
-	<Step Performance="Required">
-	    <Para>
+	    </para>
+	</step>
+	<step performance="Required">
+	    <para>
 	        The handler must be declared with the command
-		<ProgramListing>
-    CREATE FUNCTION <Replaceable>handler_function_name</Replaceable> () RETURNS OPAQUE AS
-        '<Filename>path-to-shared-object</Filename>' LANGUAGE 'C';
-		</ProgramListing>
-		The special return type of <Acronym>OPAQUE</Acronym> tells
+		<programlisting>
+    CREATE FUNCTION <replaceable>handler_function_name</replaceable> () RETURNS OPAQUE AS
+        '<filename>path-to-shared-object</filename>' LANGUAGE 'C';
+		</programlisting>
+		The special return type of <acronym>OPAQUE</acronym> tells
 		the database, that this function does not return one of
 		the defined base- or composite types and is not directly usable
-		in <Acronym>SQL</Acronym> statements.
-	    </Para>
-	</Step>
-	<Step Performance="Required">
-	    <Para>
+		in <acronym>SQL</acronym> statements.
+	    </para>
+	</step>
+	<step performance="Required">
+	    <para>
 	    	The PL must be declared with the command
-		<ProgramListing>
-    CREATE [ TRUSTED ] PROCEDURAL LANGUAGE '<Replaceable>language-name</Replaceable>'
-        HANDLER <Replaceable>handler_function_name</Replaceable>
-	LANCOMPILER '<Replaceable>description</Replaceable>';
-		</ProgramListing>
-		The optional keyword <Acronym>TRUSTED</Acronym> tells
+		<programlisting>
+    CREATE [ TRUSTED ] PROCEDURAL LANGUAGE '<replaceable>language-name</replaceable>'
+        HANDLER <replaceable>handler_function_name</replaceable>
+	LANCOMPILER '<replaceable>description</replaceable>';
+		</programlisting>
+		The optional keyword <acronym>TRUSTED</acronym> tells
 		if ordinary database users that have no superuser
 		privileges can use this language to create functions
 		and trigger procedures. Since PL functions are
@@ -79,129 +79,129 @@
 		languages that don't gain access to database backends
 		internals or the filesystem. The languages PL/pgSQL and
 		PL/Tcl are known to be trusted.
-	    </Para>
-	</Step>
-</Procedure>
-
-<Procedure>
-    <Title>Example</Title>
-    <Step Performance="Required">
-    <Para>
+	    </para>
+	</step>
+</procedure>
+
+<procedure>
+    <title>Example</title>
+    <step performance="Required">
+    <para>
         The following command tells the database where to find the 
 	shared object for the PL/pgSQL languages call handler function.
-    </Para>
-    <ProgramListing>
+    </para>
+    <programlisting>
     CREATE FUNCTION plpgsql_call_handler () RETURNS OPAQUE AS
         '/usr/local/pgsql/lib/plpgsql.so' LANGUAGE 'C';
-    </ProgramListing>
-    </Step>
+    </programlisting>
+    </step>
 
-    <Step Performance="Required">
-    <Para>
+    <step performance="Required">
+    <para>
         The command
-    </Para>
-    <ProgramListing>
+    </para>
+    <programlisting>
     CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql'
         HANDLER plpgsql_call_handler
         LANCOMPILER 'PL/pgSQL';
-    </ProgramListing>
-    <Para>
+    </programlisting>
+    <para>
         then defines that the previously declared call handler
 	function should be invoked for functions and trigger procedures
 	where the language attribute is 'plpgsql'.
-    </Para>
-    <Para>
+    </para>
+    <para>
         PL handler functions have a special call interface that is
 	different from regular C language functions. One of the arguments
-	given to the handler is the object ID in the <FileName>pg_proc</FileName>
+	given to the handler is the object ID in the <filename>pg_proc</filename>
 	tables entry for the function that should be executed.
         The handler examines various system catalogs to analyze the
 	functions call arguments and it's return data type. The source
 	text of the functions body is found in the prosrc attribute of
-	<FileName>pg_proc</FileName>.
+	<filename>pg_proc</filename>.
 	Due to this, in contrast to C language functions, PL functions
 	can be overloaded like SQL language functions. There can be
 	multiple different PL functions having the same function name,
 	as long as the call arguments differ.
-    </Para>
-    <Para>
-        Procedural languages defined in the <FileName>template1</FileName>
+    </para>
+    <para>
+        Procedural languages defined in the <filename>template1</filename>
 	database are automatically defined in all subsequently created
 	databases. So the database administrator can decide which
 	languages are available by default.
-    </Para>
-    </Step>
-</Procedure>
-</Sect1> <!-- **** End of PL installation **** -->
+    </para>
+    </step>
+</procedure>
+</sect1> <!-- **** End of PL installation **** -->
 
 <!-- **********
      * The procedural language PL/pgSQL
      **********
 -->
 
-<Sect1>
-<Title>PL/pgSQL</Title>
+<sect1>
+<title>PL/pgSQL</title>
 
-<Para>
+<para>
     PL/pgSQL is a loadable procedural language for the
-    <ProductName>Postgres</ProductName> database system.
-</Para>
+    <productname>Postgres</productname> database system.
+</para>
 
-<Para>
+<para>
     This package was originally written by Jan Wieck.
-</Para>
+</para>
 
 <!-- **** PL/pgSQL overview **** -->
 
-<Sect2>
-<Title>Overview</Title>
+<sect2>
+<title>Overview</title>
 
-<Para>
+<para>
     The design goals of PL/pgSQL were to create a loadable procedural
     language that
-    <ItemizedList>
-    <ListItem>
-	<Para>
+    <itemizedlist>
+    <listitem>
+	<para>
         can be used to create functions and trigger procedures,
-	</Para>
-    </ListItem>
-    <ListItem>
-	<Para>
-        adds control structures to the <Acronym>SQL</Acronym> language,
-	</Para>
-    </ListItem>
-    <ListItem>
-	<Para>
+	</para>
+    </listitem>
+    <listitem>
+	<para>
+        adds control structures to the <acronym>SQL</acronym> language,
+	</para>
+    </listitem>
+    <listitem>
+	<para>
         can perform complex computations,
-	</Para>
-    </ListItem>
-    <ListItem>
-	<Para>
+	</para>
+    </listitem>
+    <listitem>
+	<para>
         inherits all user defined types, functions and operators,
-	</Para>
-    </ListItem>
-    <ListItem>
-	<Para>
+	</para>
+    </listitem>
+    <listitem>
+	<para>
         can be defined to be trusted by the server,
-	</Para>
-    </ListItem>
-    <ListItem>
-	<Para>
+	</para>
+    </listitem>
+    <listitem>
+	<para>
         is easy to use.
-	</Para>
-    </ListItem>
-    </ItemizedList>
-</Para>
-<Para>
+	</para>
+    </listitem>
+    </itemizedlist>
+</para>
+<para>
     The PL/pgSQL call handler parses the functions source text and
     produces an internal binary instruction tree on the first time, the
     function is called by a backend. The produced bytecode is identified
     in the call handler by the object ID of the function. This ensures,
     that changing a function by a DROP/CREATE sequence will take effect
     without establishing a new database connection. 
-</Para>
-<Para>
-    For all expressions and <Acronym>SQL</Acronym> statements used in
+</para>
+<para>
+    For all expressions and <acronym>SQL</acronym> statements used in
     the function, the PL/pgSQL bytecode interpreter creates a
     prepared execution plan using the SPI managers SPI_prepare() and
     SPI_saveplan() functions. This is done the first time, the individual
@@ -210,41 +210,41 @@
     plans would be required, will only prepare and save those plans
     that are really used during the entire lifetime of the database
     connection.
-</Para>
-<Para>
+</para>
+<para>
     Except for input-/output-conversion and calculation functions
     for user defined types, anything that can be defined in C language
     functions can also be done with PL/pgSQL. It is possible to
     create complex conditional computation functions and later use
     them to define operators or use them in functional indices.
-</Para>
-</Sect2>
+</para>
+</sect2>
 
 <!-- **** PL/pgSQL Description **** -->
 
-<Sect2>
-<Title>Description</Title>
+<sect2>
+<title>Description</title>
 
 <!-- **** PL/pgSQL structure **** -->
 
-<Sect3>
-<Title>Structure of PL/pgSQL</Title>
+<sect3>
+<title>Structure of PL/pgSQL</title>
 
-<Para>
+<para>
     The PL/pgSQL language is case insensitive. All keywords and
     identifiers can be used in mixed upper- and lowercase.
-</Para>
-<Para>
+</para>
+<para>
     PL/pgSQL is a block oriented language. A block is defined as
 
-<ProgramListing>
+<programlisting>
     [&lt;&lt;label&gt;&gt;]
     [DECLARE
         <replaceable>declarations</replaceable>]
     BEGIN
         <replaceable>statements</replaceable>
     END;
-</ProgramListing>
+</programlisting>
 
     There can be any number of subblocks in the statement section
     of a block. Subblocks can be used to hide variables from outside a
@@ -252,76 +252,78 @@
     declared in the declarations section preceding a block are
     initialized to their default values every time the block is entered,
     not only once per function call.
-</Para>
+</para>
   
-<Para>
+<para>
     It is important not to misunderstand the meaning of BEGIN/END for
     grouping statements in PL/pgSQL and the database commands for
     transaction control. Functions and trigger procedures cannot
-    start or commit transactions and <ProductName>Postgres</ProductName>
+    start or commit transactions and <productname>Postgres</productname>
     does not have nested transactions.
-</Para>
-</Sect3>
+</para>
+</sect3>
 
 <!-- **** PL/pgSQL comments **** -->
 
-<Sect3>
-<Title>Comments</Title>
+<sect3>
+<title>Comments</title>
 
-<Para>
+<para>
     There are two types of comments in PL/pgSQL. A double dash '--'
     starts a comment that extends to the end of the line. A '/*'
     starts a block comment that extends to the next occurence of '*/'.
     Block comments cannot be nested, but double dash comments can be
     enclosed into a block comment and a double dash can hide
     the block comment delimiters '/*' and '*/'.
-</Para>
-</Sect3>
+</para>
+</sect3>
 
 <!-- **** PL/pgSQL declarations **** -->
 
-<Sect3>
-<Title>Declarations</Title>
+<sect3>
+<title>Declarations</title>
 
-<Para>
+<para>
     All variables, rows and records used in a block or it's
     subblocks must be declared in the declarations section of a block
     except for the loop variable of a FOR loop iterating over a range
     of integer values. Parameters given to a PL/pgSQL function are
     automatically declared with the usual identifiers $n.
     The declarations have the following syntax:
-</Para>
-<VariableList>
-
-<VarListEntry>
-<Term>
-<Replaceable>name</Replaceable> [ CONSTANT ] <Replaceable>type</Replaceable> [ NOT NULL ] [ DEFAULT | := <Replaceable>value</Replaceable> ];
-</Term>
-<ListItem>
-<Para>
+</para>
+<variablelist>
+
+<varlistentry>
+<term>
+<replaceable>name</replaceable> [ CONSTANT ]
+<replaceable>>typ</replaceable>> [ NOT NULL ] [ DEFAULT | :=
+	<replaceable>value</replaceable> ];
+</term>
+<listitem>
+<para>
     Declares a variable of the specified base type. If the variable
     is declared as CONSTANT, the value cannot be changed. If NOT NULL
     is specified, an assignment of a NULL value results in a runtime
     error. Since the default value of all variables is the
-    <Acronym>SQL</Acronym> NULL value, all variables declared as NOT NULL
+    <acronym>SQL</acronym> NULL value, all variables declared as NOT NULL
     must also have a default value specified.
-</Para>
-<Para>
+</para>
+<para>
     The default value is evaluated ever time the function is called. So
-    assigning '<Replaceable>now</Replaceable>' to a variable of type
-    <Replaceable>datetime</Replaceable> causes the variable to have the
+    assigning '<replaceable>now</replaceable>' to a variable of type
+    <replaceable>datetime</replaceable> causes the variable to have the
     time of the actual function call, not when the function was
     precompiled into it's bytecode.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term>
-<Replaceable>name</Replaceable> <Replaceable>class</Replaceable>%ROWTYPE;
-</Term>
-<ListItem>
-<Para>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<replaceable>name</replaceable> <replaceable>class</replaceable>%ROWTYPE;
+</term>
+<listitem>
+<para>
     Declares a row with the structure of the given class. Class must be
     an existing table- or viewname of the database. The fields of the row
     are accessed in the dot notation. Parameters to a function can
@@ -331,110 +333,110 @@
     attributes of a table row are accessible in the row, no Oid or other
     system attributes (hence the row could be from a view and view rows
     don't have useful system attributes).
-</Para>
-<Para>
+</para>
+<para>
     The fields of the rowtype inherit the tables fieldsizes 
     or precision for char() etc. data types.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term>
-<Replaceable>name</Replaceable> RECORD;
-</Term>
-<ListItem>
-<Para>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<replaceable>name</replaceable> RECORD;
+</term>
+<listitem>
+<para>
     Records are similar to rowtypes, but they have no predefined structure.
     They are used in selections and FOR loops to hold one actual
     database row from a SELECT operation. One and the same record can be
     used in different selections. Accessing a record or an attempt to assign
     a value to a record field when there is no actual row in it results
     in a runtime error.
-</Para>
-<Para>
+</para>
+<para>
     The NEW and OLD rows in a trigger are given to the procedure as
-    records. This is necessary because in <ProductName>Postgres</ProductName>
+    records. This is necessary because in <productname>Postgres</productname>
     one and the same trigger procedure can handle trigger events for
     different tables.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term>
-<Replaceable>name</Replaceable> ALIAS FOR $n;
-</Term>
-<ListItem>
-<Para>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<replaceable>name</replaceable> ALIAS FOR $n;
+</term>
+<listitem>
+<para>
     For better readability of the code it is possible to define an alias
     for a positional parameter to a function.
-</Para>
-<Para>
+</para>
+<para>
     This aliasing is required for composite types given as arguments to
     a function. The dot notation $1.salary as in SQL functions is not
     allowed in PL/pgSQL.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term>
-RENAME <Replaceable>oldname</Replaceable> TO <Replaceable>newname</Replaceable>;
-</Term>
-<ListItem>
-<Para>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+RENAME <replaceable>oldname</replaceable> TO <replaceable>newname</replaceable>;
+</term>
+<listitem>
+<para>
     Change the name of a variable, record or row. This is useful
     if NEW or OLD should be referenced by another name inside a 
     trigger procedure.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-</VariableList>
-</Sect3>
+</variablelist>
+</sect3>
 
 <!-- **** PL/pgSQL data types **** -->
 
-<Sect3>
-<Title>Data Types</Title>
+<sect3>
+<title>Data Types</title>
 
-<Para>
+<para>
     The type of a varible can be any of the existing basetypes of
-    the database. <Replaceable>type</Replaceable> in the declarations
+    the database. <replaceable>type</replaceable> in the declarations
     section above is defined as:
-</Para>
-<Para>
-    <ItemizedList>
-    <ListItem>
-        <Para>
-	<ProductName>Postgres</ProductName>-basetype
-	</Para>
-    </ListItem>
-    <ListItem>
-        <Para>
-	<Replaceable>variable</Replaceable>%TYPE
-	</Para>
-    </ListItem>
-    <ListItem>
-        <Para>
-	<Replaceable>class.field</Replaceable>%TYPE
-	</Para>
-    </ListItem>
-    </ItemizedList>
-</Para>
-<Para>
-    <Replaceable>variable</Replaceable> is the name of a variable,
+</para>
+<para>
+    <itemizedlist>
+    <listitem>
+        <para>
+	<productname>Postgres</productname>-basetype
+	</para>
+    </listitem>
+    <listitem>
+        <para>
+	<replaceable>variable</replaceable>%TYPE
+	</para>
+    </listitem>
+    <listitem>
+        <para>
+	<replaceable>class.field</replaceable>%TYPE
+	</para>
+    </listitem>
+    </itemizedlist>
+</para>
+<para>
+    <replaceable>variable</replaceable> is the name of a variable,
 previously declared in the 
     same function, that is visible at this point.
-</Para>
-<Para>
-    <Replaceable>class</Replaceable> is the name of an existing table
-    or view where <Replaceable>field</Replaceable> is the name of
+</para>
+<para>
+    <replaceable>class</replaceable> is the name of an existing table
+    or view where <replaceable>field</replaceable> is the name of
     an attribute.
-</Para>
-<Para>
-    Using the <Replaceable>class.field</Replaceable>%TYPE
+</para>
+<para>
+    Using the <replaceable>class.field</replaceable>%TYPE
     causes PL/pgSQL to lookup the attributes definitions at the
     first call to the funciton during the lifetime of a backend.
     Have a table with a char(20) attribute and some PL/pgSQL functions
@@ -444,18 +446,18 @@ previously declared in the
     char(40) and restores the data. Ha - he forgot about the
     funcitons. The computations inside them will truncate the values
     to 20 characters. But if they are defined using the
-    <Replaceable>class.field</Replaceable>%TYPE
+    <replaceable>class.field</replaceable>%TYPE
     declarations, they will automagically handle the size change or
     if the new table schema defines the attribute as text type.
-</Para>
-</Sect3>
+</para>
+</sect3>
 
 <!-- **** PL/pgSQL expressions **** -->
 
-<Sect3>
-<Title>Expressions</Title>
+<sect3>
+<title>Expressions</title>
 
-<Para>
+<para>
     All expressions used in PL/pgSQL statements are processed using
     the backends executor. Expressions which appear to contain
 constants may in fact require run-time evaluation (e.g. 'now' for the
@@ -463,22 +465,22 @@ datetime type) so
 it is impossible for the PL/pgSQL parser
     to identify real constant values other than the NULL keyword. All
     expressions are evaluated internally by executing a query
-    <ProgramListing>
-    SELECT <Replaceable>expression</Replaceable>
-    </ProgramListing>
+    <programlisting>
+    SELECT <replaceable>expression</replaceable>
+    </programlisting>
     using the SPI manager. In the expression, occurences of variable
     identifiers are substituted by parameters and the actual values from
     the variables are passed to the executor in the parameter array. All
     expressions used in a PL/pgSQL function are only prepared and
     saved once.
-</Para>
-<Para>
+</para>
+<para>
     The type checking done by the <productname>Postgres</productname>
     main parser has some side
     effects to the interpretation of constant values. In detail there
     is a difference between what the two functions
 
-    <ProgramListing>
+    <programlisting>
     CREATE FUNCTION logfunc1 (text) RETURNS datetime AS '
         DECLARE
             logtxt ALIAS FOR $1;
@@ -487,11 +489,11 @@ it is impossible for the PL/pgSQL parser
             RETURN ''now'';
         END;
     ' LANGUAGE 'plpgsql';
-    </ProgramListing>
+    </programlisting>
 
     and
 
-    <ProgramListing>
+    <programlisting>
     CREATE FUNCTION logfunc2 (text) RETURNS datetime AS '
         DECLARE
             logtxt ALIAS FOR $1;
@@ -502,9 +504,9 @@ it is impossible for the PL/pgSQL parser
             RETURN curtime;
         END;
     ' LANGUAGE 'plpgsql';
-    </ProgramListing>
+    </programlisting>
 
-    do. In the case of logfunc1(), the <ProductName>Postgres</ProductName>
+    do. In the case of logfunc1(), the <productname>Postgres</productname>
     main parser
     knows when preparing the plan for the INSERT, that the string 'now'
     should be interpreted as datetime because the target field of logtable
@@ -512,389 +514,392 @@ it is impossible for the PL/pgSQL parser
     and this constant value is then used in all invocations of logfunc1()
     during the lifetime of the backend. Needless to say that this isn't what the
     programmer wanted.
-</Para>
-<Para>
-    In the case of logfunc2(), the <ProductName>Postgres</ProductName> 
+</para>
+<para>
+    In the case of logfunc2(), the <productname>Postgres</productname> 
     main parser does not know
     what type 'now' should become and therefor it returns a datatype of
     text containing the string 'now'. During the assignment
     to the local variable curtime, the PL/pgSQL interpreter casts this
     string to the datetime type by calling the text_out() and datetime_in()
     functions for the conversion.
-</Para>
-<Para>
-    This type checking done by the <ProductName>Postgres</ProductName> main
+</para>
+<para>
+    This type checking done by the <productname>Postgres</productname> main
     parser got implemented after PL/pgSQL was nearly done.
     It is a difference between 6.3 and 6.4 and affects all functions
     using the prepared plan feature of the SPI manager.
     Using a local
     variable in the above manner is currently the only way in PL/pgSQL to get
     those values interpreted correctly.
-</Para>
-<Para>
+</para>
+<para>
     If record fields are used in expressions or statements, the data types of
     fields should not change between calls of one and the same expression.
     Keep this in mind when writing trigger procedures that handle events
     for more than one table.
-</Para>
-</Sect3>
+</para>
+</sect3>
 
 <!-- **** PL/pgSQL statements **** -->
 
-<Sect3>
-<Title>Statements</Title>
+<sect3>
+<title>Statements</title>
 
-<Para>
+<para>
     Anything not understood by the PL/pgSQL parser as specified below
     will be put into a query and sent down to the database engine
     to execute. The resulting query should not return any data.
-</Para>
+</para>
 
-<VariableList>
+<variablelist>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
 Assignment
-</Term>
-<ListItem>
-<Para>
+</term>
+<listitem>
+<para>
     An assignment of a value to a variable or row/record field is
     written as
-    <ProgramListing>
-    <Replaceable>identifier</Replaceable> := <Replaceable>expression</Replaceable>;
-    </ProgramListing>
+    <programlisting>
+    <replaceable>identifier</replaceable> := <replaceable>expression</replaceable>;
+    </programlisting>
     If the expressions result data type doesn't match the variables
     data type, or the variable has a size/precision that is known
     (as for char(20)), the result value will be implicitly casted by
     the PL/pgSQL bytecode interpreter using the result types output- and
     the variables type input-functions. Note that this could potentially
     result in runtime errors generated by the types input functions.
-</Para>
-<Para>
+</para>
+<para>
     An assignment of a complete selection into a record or row can
     be done by
-    <ProgramListing>
-    SELECT <Replaceable>expressions</Replaceable> INTO <Replaceable>target</Replaceable> FROM ...;
-    </ProgramListing>
-    <Replaceable>target</Replaceable> can be a record, a row variable or a
+    <programlisting>
+    SELECT <replaceable>expressions</replaceable> INTO <replaceable>target</replaceable> FROM ...;
+    </programlisting>
+    <replaceable>target</replaceable> can be a record, a row variable or a
     comma separated list of variables and record-/row-fields.
-</Para>
-<Para>
+</para>
+<para>
     if a row or a variable list is used as target, the selected values
     must exactly match the structure of the target(s) or a runtime error
     occurs. The FROM keyword can be followed by any valid qualification,
     grouping, sorting etc. that can be given for a SELECT statement.
-</Para>
-<Para>
+</para>
+<para>
     There is a special variable named FOUND of type bool that can be used
     immediately after a SELECT INTO to check if an assignment had success.
 
-    <ProgramListing>
+    <programlisting>
     SELECT * INTO myrec FROM EMP WHERE empname = myname;
     IF NOT FOUND THEN
         RAISE EXCEPTION ''employee % not found'', myname;
     END IF;
-    </ProgramListing>
+    </programlisting>
 
     If the selection returns multiple rows, only the first is moved
     into the target fields. All others are silently discarded.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
 Calling another function
-</Term>
-<ListItem>
-<Para>
-    All functions defined in a <ProductName>Prostgres</ProductName>
+</term>
+<listitem>
+<para>
+    All functions defined in a <productname>Prostgres</productname>
     database return a value. Thus, the normal way to call a function
     is to execute a SELECT query or doing an assignment (resulting
     in a PL/pgSQL internal SELECT). But there are cases where someone
     isn't interested int the functions result.
-    <ProgramListing>
-    PERFORM <Replaceable>query</Replaceable>
-    </ProgramListing>
-    executes a 'SELECT <Replaceable>query</Replaceable>' over the
+    <programlisting>
+    PERFORM <replaceable>query</replaceable>
+    </programlisting>
+    executes a 'SELECT <replaceable>query</replaceable>' over the
     SPI manager and discards the result. Identifiers like local
     variables are still substituted into parameters.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
 Returning from the function
-</Term>
-<ListItem>
-<Para>
-    <ProgramListing>
-    RETURN <Replaceable>expression</Replaceable>
-    </ProgramListing>
-    The function terminates and the value of <Replaceable>expression</Replaceable>
+</term>
+<listitem>
+<para>
+    <programlisting>
+    RETURN <replaceable>expression</replaceable>
+    </programlisting>
+    The function terminates and the value of <replaceable>expression</replaceable>
     will be returned to the upper executor. The return value of a function
     cannot be undefined. If control reaches the end of the toplevel block
     of the function without hitting a RETURN statement, a runtime error
     will occur.
-</Para>
-<Para>
+</para>
+<para>
     The expressions result will be automatically casted into the
     functions return type as described for assignments.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
 Aborting and messages
-</Term>
-<ListItem>
-<Para>
+</term>
+<listitem>
+<para>
     As indicated in the above examples there is a RAISE statement that
-    can throw messages into the <ProductName>Postgres</ProductName>
+    can throw messages into the <productname>Postgres</productname>
     elog mechanism.
-    <ProgramListing>
-    RAISE <replaceable class="parameter">level</replaceable> ''<replaceable class="parameter">format</replaceable>'' [, <replaceable class="parameter">identifier</replaceable> [...]];
-    </ProgramListing>
+    <programlisting>
+    RAISE <replaceable class="parameter">level</replaceable>
+	 <replaceable class="parameter">r">for</replaceable>le>'' [,
+	  <replaceable class="parameter">identifier</replaceable> [...]];
+    </programlisting>
     Inside the format, <quote>%</quote> is used as a placeholder for the
     subsequent comma-separated identifiers. Possible levels are
     DEBUG (silently suppressed in production running databases), NOTICE 
     (written into the database log and forwarded to the client application)
     and EXCEPTION (written into the database log and aborting the transaction).
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
 Conditionals
-</Term>
-<ListItem>
-<Para>
-    <ProgramListing>
-    IF <Replaceable>expression</Replaceable> THEN
+</term>
+<listitem>
+<para>
+    <programlisting>
+    IF <replaceable>expression</replaceable> THEN
         <replaceable>statements</replaceable>
     [ELSE
         <replaceable>statements</replaceable>]
     END IF;
-    </ProgramListing>
-    The <Replaceable>expression</Replaceable> must return a value that
+    </programlisting>
+    The <replaceable>expression</replaceable> must return a value that
     at least can be casted into a boolean type.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
 Loops
-</Term>
-<ListItem>
-<Para>
+</term>
+<listitem>
+<para>
     There are multiple types of loops.
-    <ProgramListing>
+    <programlisting>
     [&lt;&lt;label&gt;&gt;]
     LOOP
         <replaceable>statements</replaceable>
     END LOOP;
-    </ProgramListing>
+    </programlisting>
     An unconditional loop that must be terminated explicitly
     by an EXIT statement. The optional label can be used by
     EXIT statements of nested loops to specify which level of
     nesting should be terminated.
-    <ProgramListing>
+    <programlisting>
     [&lt;&lt;label&gt;&gt;]
-    WHILE <Replaceable>expression</Replaceable> LOOP
+    WHILE <replaceable>expression</replaceable> LOOP
         <replaceable>statements</replaceable>
     END LOOP;
-    </ProgramListing>
+    </programlisting>
     A conditional loop that is executed as long as the evaluation
-    of <Replaceable>expression</Replaceable> is true.
-    <ProgramListing>
+    of <replaceable>expression</replaceable> is true.
+    <programlisting>
     [&lt;&lt;label&gt;&gt;]
-    FOR <Replaceable>name</Replaceable> IN [ REVERSE ] <Replaceable>expression</Replaceable> .. <Replaceable>expression</Replaceable> LOOP
+    FOR <replaceable>name</replaceable> IN [ REVERSE ]
+<replaceable>le>express</replaceable>le> .. <replaceable>expression</replaceable> LOOP
         <replaceable>statements</replaceable>
     END LOOP;
-    </ProgramListing>
+    </programlisting>
     A loop that iterates over a range of integer values. The variable
-    <Replaceable>name</Replaceable> is automatically created as type
+    <replaceable>name</replaceable> is automatically created as type
     integer and exists only inside the loop. The two expressions giving
     the lower and upper bound of the range are evaluated only when entering
     the loop. The iteration step is always 1.
-    <ProgramListing>
+    <programlisting>
     [&lt;&lt;label&gt;&gt;]
-    FOR <Replaceable>record | row</Replaceable> IN <Replaceable>select_clause</Replaceable> LOOP
+    FOR <replaceable>record | row</replaceable> IN <replaceable>select_clause</replaceable> LOOP
         <replaceable>statements</replaceable>
     END LOOP;
-    </ProgramListing>
+    </programlisting>
     The record or row is assigned all the rows resulting from the select
     clause and the statements executed for each. If the loop is terminated
     with an EXIT statement, the last assigned row is still accessible 
     after the loop.
-    <ProgramListing>
-    EXIT [ <Replaceable>label</Replaceable> ] [ WHEN <Replaceable>expression</Replaceable> ];
-    </ProgramListing>
-    If no <Replaceable>label</Replaceable> given,
+    <programlisting>
+    EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replaceable> ];
+    </programlisting>
+    If no <replaceable>label</replaceable> given,
  the innermost loop is terminated and the
     statement following END LOOP is executed next.
- If <Replaceable>label</Replaceable> is given, it
+ If <replaceable>label</replaceable> is given, it
     must be the label of the current or an upper level of nested loop
     blocks. Then the named loop or block is terminated and control
     continues with the statement after the loops/blocks corresponding
     END.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-</VariableList>
+</variablelist>
 
-</Sect3>
+</sect3>
 
 <!-- **** PL/pgSQL trigger procedures **** -->
 
-<Sect3>
-<Title>Trigger Procedures</Title>
+<sect3>
+<title>Trigger Procedures</title>
 
-<Para>
+<para>
     PL/pgSQL can be used to define trigger procedures. They are created
     with the usual CREATE FUNCTION command as a function with no
     arguments and a return type of OPAQUE.
-</Para>
-<Para>
-    There are some <ProductName>Postgres</ProductName> specific details
+</para>
+<para>
+    There are some <productname>Postgres</productname> specific details
     in functions used as trigger procedures.
-</Para>
-<Para>
+</para>
+<para>
     First they have some special variables created automatically in the 
     toplevel blocks declaration section. They are
-</Para>
+</para>
 
-<VariableList>
+<variablelist>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
     NEW
-</Term>
-<ListItem>
-<Para>
+</term>
+<listitem>
+<para>
     Datatype RECORD; variable holding the new database row on INSERT/UPDATE
     operations on ROW level triggers.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
     OLD
-</Term>
-<ListItem>
-<Para>
+</term>
+<listitem>
+<para>
     Datatype RECORD; variable holding the old database row on UPDATE/DELETE
     operations on ROW level triggers.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
     TG_NAME
-</Term>
-<ListItem>
-<Para>
+</term>
+<listitem>
+<para>
     Datatype name; variable that contains the name of the trigger actually
     fired.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
     TG_WHEN
-</Term>
-<ListItem>
-<Para>
+</term>
+<listitem>
+<para>
     Datatype text; a string of either 'BEFORE' or 'AFTER' depending on the
     triggers definition.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
     TG_LEVEL
-</Term>
-<ListItem>
-<Para>
+</term>
+<listitem>
+<para>
     Datatype text; a string of either 'ROW' or 'STATEMENT' depending on the
     triggers definition.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
     TG_OP
-</Term>
-<ListItem>
-<Para>
+</term>
+<listitem>
+<para>
     Datatype text; a string of 'INSERT', 'UPDATE' or 'DELETE' telling
     for which operation the trigger is actually fired.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
     TG_RELID
-</Term>
-<ListItem>
-<Para>
+</term>
+<listitem>
+<para>
     Datatype oid; the object ID of the table that caused the
     trigger invocation.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
     TG_RELNAME
-</Term>
-<ListItem>
-<Para>
+</term>
+<listitem>
+<para>
     Datatype name; the name of the table that caused the trigger
     invocation.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
     TG_NARGS
-</Term>
-<ListItem>
-<Para>
+</term>
+<listitem>
+<para>
     Datatype integer; the number of arguments given to the trigger
     procedure in the CREATE TRIGGER statement.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
     TG_ARGV[]
-</Term>
-<ListItem>
-<Para>
+</term>
+<listitem>
+<para>
     Datatype array of text; the arguments from the CREATE TRIGGER statement.
     The index counts from 0 and can be given as an expression. Invalid
     indices (&lt; 0 or &gt;= tg_nargs) result in a NULL value.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-</VariableList>
+</variablelist>
 
-<Para>
+<para>
     Second they must return either NULL or a record/row containing
     exactly the structure of the table the trigger was fired for.
     Triggers fired AFTER might always return a NULL value with no
@@ -904,22 +909,22 @@ Loops
     row in the operation. It is possible to replace single values directly
     in NEW and return that or to build a complete new record/row to
     return.
-</Para>
-</Sect3>
+</para>
+</sect3>
 
 <!-- **** PL/pgSQL exceptions **** -->
 
-<Sect3>
-<Title>Exceptions</Title>
+<sect3>
+<title>Exceptions</title>
 
-<Para>
-    <ProductName>Postgres</ProductName> does not have a very smart
+<para>
+    <productname>Postgres</productname> does not have a very smart
     exception handling model. Whenever the parser, planner/optimizer
     or executor decide that a statement cannot be processed any longer,
     the whole transaction gets aborted and the system jumps back
     into the mainloop to get the next query from the client application.
-</Para>
-<Para>
+</para>
+<para>
     It is possible to hook into the error mechanism to notice that this
     happens. But currently it's impossible to tell what really
     caused the abort (input/output conversion error, floating point
@@ -929,73 +934,73 @@ Loops
     And even if, at this point the information, that the transaction
     is aborted, is already sent to the client application, so resuming
     operation does not make any sense.
-</Para>
-<Para>
+</para>
+<para>
     Thus, the only thing PL/pgSQL currently does when it encounters
     an abort during execution of a function or trigger
     procedure is to write some additional DEBUG level log messages
     telling in which function and where (line number and type of
     statement) this happened.
-</Para>
-</Sect3>
-</Sect2>
+</para>
+</sect3>
+</sect2>
 
 <!-- **** PL/pgSQL Examples **** -->
 
-<Sect2>
-<Title>Examples</Title>
+<sect2>
+<title>Examples</title>
 
-<Para>
+<para>
 Here are only a few functions to demonstrate how easy PL/pgSQL
 functions can be written. For more complex examples the programmer
 might look at the regression test for PL/pgSQL.
-</Para>
+</para>
 
-<Para>
+<para>
 One painful detail of writing functions in PL/pgSQL is the handling
 of single quotes. The functions source text on CREATE FUNCTION must
 be a literal string. Single quotes inside of literal strings must be
 either doubled or quoted with a backslash. We are still looking for
 an elegant alternative. In the meantime, doubling the single qoutes
 as in the examples below should be used. Any solution for this
-in future versions of <ProductName>Postgres</ProductName> will be
+in future versions of <productname>Postgres</productname> will be
 upward compatible.
-</Para>
+</para>
 
-<Sect3>
-<Title>Some Simple PL/pgSQL Functions</Title>
+<sect3>
+<title>Some Simple PL/pgSQL Functions</title>
 
-<Para>
+<para>
     The following two PL/pgSQL functions are identical to their
     counterparts from the C language function discussion.
 
-    <ProgramListing>
+    <programlisting>
     CREATE FUNCTION add_one (int4) RETURNS int4 AS '
         BEGIN
             RETURN $1 + 1;
         END;
     ' LANGUAGE 'plpgsql';
-    </ProgramListing>
+    </programlisting>
 
-    <ProgramListing>
+    <programlisting>
     CREATE FUNCTION concat_text (text, text) RETURNS text AS '
         BEGIN
             RETURN $1 || $2;
         END;
     ' LANGUAGE 'plpgsql';
-    </ProgramListing>
-</Para>
+    </programlisting>
+</para>
 
-</Sect3>
+</sect3>
 
-<Sect3>
-<Title>PL/pgSQL Function on Composite Type</Title>
+<sect3>
+<title>PL/pgSQL Function on Composite Type</title>
 
-<Para>
+<para>
     Again it is the PL/pgSQL equivalent to the example from
     The C functions.
 
-    <ProgramListing>
+    <programlisting>
     CREATE FUNCTION c_overpaid (EMP, int4) RETURNS bool AS '
         DECLARE
             emprec ALIAS FOR $1;
@@ -1007,21 +1012,21 @@ upward compatible.
             RETURN emprec.salary > sallim;
         END;
     ' LANGUAGE 'plpgsql';
-    </ProgramListing>
-</Para>
+    </programlisting>
+</para>
 
-</Sect3>
+</sect3>
 
-<Sect3>
-<Title>PL/pgSQL Trigger Procedure</Title>
+<sect3>
+<title>PL/pgSQL Trigger Procedure</title>
 
-<Para>
+<para>
     This trigger ensures, that any time a row is inserted or updated
     in the table, the current username and time are stamped into the
     row. And it ensures that an employees name is given and that the
     salary is a positive value.
 
-    <ProgramListing>
+    <programlisting>
     CREATE TABLE emp (
         empname text,
         salary int4,
@@ -1052,108 +1057,110 @@ upward compatible.
 
     CREATE TRIGGER emp_stamp BEFORE INSERT OR UPDATE ON emp
         FOR EACH ROW EXECUTE PROCEDURE emp_stamp();
-    </ProgramListing>
-</Para>
+    </programlisting>
+</para>
 
-</Sect3>
+</sect3>
 
-</Sect2>
+</sect2>
 
-</Sect1>
+</sect1>
 
 <!-- **********
      * The procedural language PL/Tcl
      **********
 -->
 
-<Sect1>
-<Title>PL/Tcl</Title>
+<sect1>
+<title>PL/Tcl</title>
 
-<Para>
+<para>
     PL/Tcl is a loadable procedural language for the
-    <ProductName>Postgres</ProductName> database system
+    <productname>Postgres</productname> database system
     that enables the Tcl language to be used to create functions and
     trigger-procedures.
-</Para>
+</para>
 
-<Para>
+<para>
     This package was originally written by Jan Wieck.
-</Para>
+</para>
 
 <!-- **** PL/Tcl overview **** -->
 
-<Sect2>
-<Title>Overview</Title>
+<sect2>
+<title>Overview</title>
 
-<Para>
+<para>
     PL/Tcl offers most of the capabilities a function
     writer has in the C language, except for some restrictions.
-</Para>
-<Para>
+</para>
+<para>
     The good restriction is, that everything is executed in a safe
     Tcl-interpreter. In addition to the limited command set of safe Tcl, only
     a few commands are available to access the database over SPI and to raise
     messages via elog(). There is no way to access internals of the
     database backend or gaining OS-level access under the permissions of the
-    <ProductName>Postgres</ProductName> user ID like in C.
+    <productname>Postgres</productname> user ID like in C.
     Thus, any unprivileged database user may be
     permitted to use this language.
-</Para>
-<Para>
+</para>
+<para>
     The other, internal given, restriction is, that Tcl procedures cannot
     be used to create input-/output-functions for new data types.
-</Para>
-<Para>
+</para>
+<para>
     The shared object for the PL/Tcl call handler is automatically built
-    and installed in the <ProductName>Postgres</ProductName>
+    and installed in the <productname>Postgres</productname>
     library directory if the Tcl/Tk support is specified
     in the configuration step of the installation procedure.
-</Para>
-</Sect2>
+</para>
+</sect2>
 
 <!-- **** PL/Tcl description **** -->
 
-<Sect2>
-<Title>Description</Title>
+<sect2>
+<title>Description</title>
 
-<Sect3>
-<Title><ProductName>Postgres</ProductName> Functions and Tcl Procedure Names</Title>
+<sect3>
+<title><productname>Postgres</productname> Functions and Tcl Procedure Names</title>
 
-<Para>
-    In <ProductName>Postgres</ProductName>, one and the 
+<para>
+    In <productname>Postgres</productname>, one and the 
     same function name can be used for
     different functions as long as the number of arguments or their types
     differ. This would collide with Tcl procedure names. To offer the same
     flexibility in PL/Tcl, the internal Tcl procedure names contain the object
     ID of the procedures pg_proc row as part of their name. Thus, different
-    argtype versions of the same <ProductName>Postgres</ProductName> 
+    argtype versions of the same <productname>Postgres</productname> 
     function are different for Tcl too.
-</Para>
+</para>
 
-</Sect3>
+</sect3>
 
-<Sect3>
-<Title>Defining Functions in PL/Tcl</Title>
+<sect3>
+<title>Defining Functions in PL/Tcl</title>
 
-<Para>
+<para>
     To create a function in the PL/Tcl language, use the known syntax
 
-    <ProgramListing>
-    CREATE FUNCTION <Replaceable>funcname</Replaceable> (<Replaceable>argument-types</Replaceable>) RETURNS <Replaceable>returntype</Replaceable> AS '
+    <programlisting>
+    CREATE FUNCTION <replaceable>funcname</replaceable>
+ <replaceable>ceable>argumen</replaceable>ceable>) RETURNS
+       <replaceable>returntype</replaceable> AS '
         # PL/Tcl function body
     ' LANGUAGE 'pltcl';
-    </ProgramListing>
+    </programlisting>
 
     When calling this function in a query, the arguments are given as
     variables $1 ... $n to the Tcl procedure body. So a little max function
     returning the higher of two int4 values would be created as:
 
-    <ProgramListing>
+    <programlisting>
     CREATE FUNCTION tcl_max (int4, int4) RETURNS int4 AS '
         if {$1 > $2} {return $1}
 	return $2
     ' LANGUAGE 'pltcl';
-    </ProgramListing>
+    </programlisting>
 
     Composite type arguments are given to the procedure as Tcl arrays.
     The element names
@@ -1161,9 +1168,9 @@ upward compatible.
     type. If an attribute in the actual row
     has the NULL value, it will not appear in the array! Here is
     an example that defines the overpaid_2 function (as found in the
-    older <ProductName>Postgres</ProductName> documentation) in PL/Tcl
+    older <productname>Postgres</productname> documentation) in PL/Tcl
 
-    <ProgramListing>
+    <programlisting>
     CREATE FUNCTION overpaid_2 (EMP) RETURNS bool AS '
         if {200000.0 < $1(salary)} {
             return "t"
@@ -1173,15 +1180,15 @@ upward compatible.
         }
         return "f"
     ' LANGUAGE 'pltcl';
-    </ProgramListing>
-</Para>
+    </programlisting>
+</para>
 
-</Sect3>
+</sect3>
 
-<Sect3>
-<Title>Global Data in PL/Tcl</Title>
+<sect3>
+<title>Global Data in PL/Tcl</title>
 
-<Para>
+<para>
     Sometimes (especially when using the SPI functions described later) it
     is useful to have some global status data that is held between two
     calls to a procedure. 
@@ -1191,146 +1198,146 @@ upward compatible.
     an array is made available to each procedure via the upvar
     command. The global name of this variable is the procedures internal
     name and the local name is GD.
-</Para>
-</Sect3>
+</para>
+</sect3>
 
-<Sect3>
-<Title>Trigger Procedures in PL/Tcl</Title>
+<sect3>
+<title>Trigger Procedures in PL/Tcl</title>
 
-<Para>
-    Trigger procedures are defined in <ProductName>Postgres</ProductName>
+<para>
+    Trigger procedures are defined in <productname>Postgres</productname>
     as functions without
     arguments and a return type of opaque. And so are they in the PL/Tcl
     language.
-</Para>
-<Para>
+</para>
+<para>
     The informations from the trigger manager are given to the procedure body
     in the following variables:
-</Para>
-<VariableList>
+</para>
+<variablelist>
 
-<VarListEntry>
-<Term><Replaceable class="Parameter">
+<varlistentry>
+<term><replaceable class="Parameter">
 $TG_name
-</Replaceable></Term>
-<ListItem>
-<Para>
+</replaceable></term>
+<listitem>
+<para>
     The name of the trigger from the CREATE TRIGGER statement.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term><Replaceable class="Parameter">
+<varlistentry>
+<term><replaceable class="Parameter">
 $TG_relid
-</Replaceable></Term>
-<ListItem>
-<Para>
+</replaceable></term>
+<listitem>
+<para>
     The object ID of the table that caused the trigger procedure
     to be invoked.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term><Replaceable class="Parameter">
+<varlistentry>
+<term><replaceable class="Parameter">
 $TG_relatts
-</Replaceable></Term>
-<ListItem>
-<Para>
+</replaceable></term>
+<listitem>
+<para>
     A Tcl list of the tables field names prefixed with an empty list element.
     So looking up an element name in the list with the lsearch Tcl command
     returns the same positive number starting from 1 as the fields are numbered
     in the pg_attribute system catalog.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term><Replaceable class="Parameter">
+<varlistentry>
+<term><replaceable class="Parameter">
 $TG_when
-</Replaceable></Term>
-<ListItem>
-<Para>
+</replaceable></term>
+<listitem>
+<para>
     The string BEFORE or AFTER depending on the event of the trigger call.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term><Replaceable class="Parameter">
+<varlistentry>
+<term><replaceable class="Parameter">
 $TG_level
-</Replaceable></Term>
-<ListItem>
-<Para>
+</replaceable></term>
+<listitem>
+<para>
     The string ROW or STATEMENT depending on the event of the trigger call.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term><Replaceable class="Parameter">
+<varlistentry>
+<term><replaceable class="Parameter">
 $TG_op
-</Replaceable></Term>
-<ListItem>
-<Para>
+</replaceable></term>
+<listitem>
+<para>
     The string INSERT, UPDATE or DELETE depending on the event of the 
     trigger call.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term><Replaceable class="Parameter">
+<varlistentry>
+<term><replaceable class="Parameter">
 $NEW
-</Replaceable></Term>
-<ListItem>
-<Para>
+</replaceable></term>
+<listitem>
+<para>
     An array containing the values of the new table row on INSERT/UPDATE
     actions, or empty on DELETE.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term><Replaceable class="Parameter">
+<varlistentry>
+<term><replaceable class="Parameter">
 $OLD
-</Replaceable></Term>
-<ListItem>
-<Para>
+</replaceable></term>
+<listitem>
+<para>
     An array containing the values of the old table row on UPDATE/DELETE
     actions, or empty on INSERT.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term><Replaceable class="Parameter">
+<varlistentry>
+<term><replaceable class="Parameter">
 $GD
-</Replaceable></Term>
-<ListItem>
-<Para>
+</replaceable></term>
+<listitem>
+<para>
     The global status data array as described above.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term><Replaceable class="Parameter">
+<varlistentry>
+<term><replaceable class="Parameter">
 $args
-</Replaceable></Term>
-<ListItem>
-<Para>
+</replaceable></term>
+<listitem>
+<para>
     A Tcl list of the arguments to the procedure as given in the
     CREATE TRIGGER statement. The arguments are also accessible as $1 ... $n
     in the procedure body.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-</VariableList>
+</variablelist>
 
-<Para>
+<para>
     The return value from a trigger procedure is one of the strings OK or SKIP,
     or a list as returned by the 'array get' Tcl command. If the return value
     is OK, the normal operation (INSERT/UPDATE/DELETE) that fired this trigger
@@ -1339,14 +1346,14 @@ $args
     to return a modified row to the trigger manager that will be inserted instead
     of the one given in $NEW (INSERT/UPDATE only). Needless to say that all
     this is only meaningful when the trigger is BEFORE and FOR EACH ROW.
-</Para>
-<Para>
+</para>
+<para>
     Here's a little example trigger procedure that forces an integer value
     in a table to keep track of the # of updates that are performed on the
     row. For new row's inserted, the value is initialized to 0 and then
     incremented on every update operation:
 
-    <ProgramListing>
+    <programlisting>
     CREATE FUNCTION trigfunc_modcount() RETURNS OPAQUE AS '
         switch $TG_op {
             INSERT {
@@ -1367,161 +1374,163 @@ $args
 
     CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
         FOR EACH ROW EXECUTE PROCEDURE trigfunc_modcount('modcnt');
-    </ProgramListing>
+    </programlisting>
 
-</Para>
-</Sect3>
+</para>
+</sect3>
 
-<Sect3>
-<Title>Database Access from PL/Tcl</Title>
+<sect3>
+<title>Database Access from PL/Tcl</title>
 
-<Para>
+<para>
     The following commands are available to access the database from
     the body of a PL/Tcl procedure:
-</Para>
+</para>
 
-<VariableList>
+<variablelist>
 
-<VarListEntry>
-<Term>
-elog <Replaceable>level</Replaceable> <Replaceable>msg</Replaceable>
-</Term>
-<ListItem>
-<Para>
+<varlistentry>
+<term>
+elog <replaceable>level</replaceable> <replaceable>msg</replaceable>
+</term>
+<listitem>
+<para>
     Fire a log message. Possible levels are NOTICE, WARN, ERROR,
     FATAL, DEBUG and NOIND
     like for the elog() C function.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term>
-quote <Replaceable>string</Replaceable>
-</Term>
-<ListItem>
-<Para>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+quote <replaceable>string</replaceable>
+</term>
+<listitem>
+<para>
     Duplicates all occurences of single quote and backslash characters.
     It should be used when variables are used in the query string given
     to spi_exec or spi_prepare (not for the value list on spi_execp).
     Think about a query string like
 
-    <ProgramListing>
+    <programlisting>
     "SELECT '$val' AS ret"
-    </ProgramListing>
+    </programlisting>
 
     where the Tcl variable val actually contains "doesn't". This would result
     in the final query string
 
-    <ProgramListing>
+    <programlisting>
     "SELECT 'doesn't' AS ret"
-    </ProgramListing>
+    </programlisting>
 
     what would cause a parse error during spi_exec or spi_prepare.
     It should contain
 
-    <ProgramListing>
+    <programlisting>
     "SELECT 'doesn''t' AS ret"
-    </ProgramListing>
+    </programlisting>
 
     and has to be written as
 
-    <ProgramListing>
+    <programlisting>
     "SELECT '[ quote $val ]' AS ret"
-    </ProgramListing>
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term>
-spi_exec ?-count <Replaceable>n</Replaceable>? ?-array <Replaceable>name</Replaceable>? <Replaceable>query</Replaceable> ?<Replaceable>loop-body</Replaceable>?
-</Term>
-<ListItem>
-<Para>
+    </programlisting>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+spi_exec ?-count <replaceable>n</replaceable>? ?-array
+<replaceable>>nam</replaceable>>?<replaceable>e>que</replaceable>e> ?<replaceable>loop-body</replaceable>?
+</term>
+<listitem>
+<para>
     Call parser/planner/optimizer/executor for query.
     The optional -count value tells spi_exec the maximum number of rows
     to be processed by the query.
-</Para>
-<Para>
+</para>
+<para>
     If the query is
     a SELECT statement and the optional loop-body (a body of Tcl commands
     like in a foreach statement) is given, it is evaluated for each
     row selected and behaves like expected on continue/break. The values
     of selected fields are put into variables named as the column names. So a
 
-    <ProgramListing>
+    <programlisting>
     spi_exec "SELECT count(*) AS cnt FROM pg_proc"
-    </ProgramListing>
+    </programlisting>
 
     will set the variable $cnt to the number of rows in the pg_proc system
     catalog. If the option -array is given, the column values are stored
     in the associative array named 'name' indexed by the column name
     instead of individual variables.
 
-    <ProgramListing>
+    <programlisting>
     spi_exec -array C "SELECT * FROM pg_class" {
         elog DEBUG "have table $C(relname)"
     }
-    </ProgramListing>
+    </programlisting>
 
     will print a DEBUG log message for every row of pg_class. The return value
     of spi_exec is the number of rows affected by query as found in
     the global variable SPI_processed.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term>
-spi_prepare <Replaceable>query</Replaceable> <Replaceable>typelist</Replaceable>
-</Term>
-<ListItem>
-<Para>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+spi_prepare <replaceable>query</replaceable> <replaceable>typelist</replaceable>
+</term>
+<listitem>
+<para>
     Prepares AND SAVES a query plan for later execution. It is a bit different
     from the C level SPI_prepare in that the plan is automatically copied to the
     toplevel memory context. Thus, there is currently no way of preparing a
     plan without saving it.
-</Para>
-<Para>
+</para>
+<para>
     If the query references arguments, the type names must be given as a Tcl
     list. The return value from spi_prepare is a query ID to be used in
     subsequent calls to spi_execp. See spi_execp for a sample.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term>
-spi_exec ?-count <Replaceable>n</Replaceable>? ?-array <Replaceable>name</Replaceable>? ?-nulls <Replaceable>str</Replaceable>? <Replaceable>query</Replaceable> ?<Replaceable>valuelist</Replaceable>? ?<Replaceable>loop-body</Replaceable>?
-</Term>
-<ListItem>
-<Para>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+spi_exec ?-count <replaceable>n</replaceable>? ?-array
+<replaceable>>nam</replaceable>>? ?-nulls<replaceable>e>s</replaceable>e><replaceable>le>qu</replaceable>le<replaceable>ble>value</replaceable>ble>? ?<replaceable>loop-body</replaceable>?
+</term>
+<listitem>
+<para>
     Execute a prepared plan from spi_prepare with variable substitution.
     The optional -count value tells spi_execp the maximum number of rows
     to be processed by the query.
-</Para>
-<Para>
+</para>
+<para>
     The optional value for -nulls is a string of spaces and 'n' characters
     telling spi_execp which of the values are NULL's. If given, it must
     have exactly the length of the number of values.
-</Para>
-<Para>
+</para>
+<para>
     The queryid is the ID returned by the spi_prepare call.
-</Para>
-<Para>
+</para>
+<para>
     If there was a typelist given to spi_prepare, a Tcl list of values of
     exactly the same length must be given to spi_execp after the query. If
     the type list on spi_prepare was empty, this argument must be omitted.
-</Para>
-<Para>
+</para>
+<para>
     If the query is a SELECT statement, the same as described for spi_exec
     happens for the loop-body and the variables for the fields selected.
-</Para>
-<Para>
+</para>
+<para>
     Here's an example for a PL/Tcl function using a prepared plan:
 
-    <ProgramListing>
+    <programlisting>
     CREATE FUNCTION t1_count(int4, int4) RETURNS int4 AS '
         if {![ info exists GD(plan) ]} {
             # prepare the saved plan on the first call
@@ -1532,7 +1541,7 @@ spi_exec ?-count <Replaceable>n</Replaceable>? ?-array <Replaceable>name</Replac
         spi_execp -count 1 $GD(plan) [ list $1 $2 ]
         return $cnt
     ' LANGUAGE 'pltcl';
-    </ProgramListing>
+    </programlisting>
 
     Note that each backslash that Tcl should see must be doubled in
     the query creating the function, since the main parser processes
@@ -1540,16 +1549,16 @@ spi_exec ?-count <Replaceable>n</Replaceable>? ?-array <Replaceable>name</Replac
     Inside the query string given to spi_prepare should
     really be dollar signs to mark the parameter positions and to not let
     $1 be substituted by the value given in the first function call.
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
 
-<VarListEntry>
-<Term>
+<varlistentry>
+<term>
 Modules and the unknown command
-</Term>
-<ListItem>
-<Para>
+</term>
+<listitem>
+<para>
     PL/Tcl has a special support for things often used. It recognizes two
     magic tables, pltcl_modules and pltcl_modfuncs.
     If these exist, the module 'unknown' is loaded into the interpreter
@@ -1558,21 +1567,36 @@ Modules and the unknown command
     of the modules. If this is true, the module is loaded on demand.
     To enable this behavior, the PL/Tcl call handler must be compiled
     with -DPLTCL_UNKNOWN_SUPPORT set.
-</Para>
-<Para>
+</para>
+<para>
     There are support scripts to maintain these tables in the modules
     subdirectory of the PL/Tcl source including the source for the
     unknown module that must get installed initially.
-</Para>
-</ListItem>
-</VarListEntry>
-
-</VariableList>
-
-</Sect3>
-
-</Sect2>
-</Sect1>
-
-
-</Chapter>
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect3>
+
+</sect2>
+</sect1>
+</chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
+sgml-local-ecat-files:nil
+End:
+-->