Improve catalog commentary.

src/backend/catalog/README

-$Header: /cvsroot/pgsql/src/backend/catalog/README,v 1.3 2002/03/19 01:14:41 momjian Exp $
+$Header: /cvsroot/pgsql/src/backend/catalog/README,v 1.4 2002/03/22 20:14:42 tgl Exp $
 
 This directory contains .c files that manipulate the system catalogs
 as well as .h files that define the structure of the system catalogs.
@@ -23,34 +23,52 @@ bootstrap/ directory.  Just be careful when adding new DATA
 statements.
 
 - Some catalogs require that OIDs be preallocated to tuples because
-certain catalogs contain circular references.  For example, pg_type
-contains pointers into pg_proc (pg_type.typinput), and pg_proc
-contains back-pointers into pg_type (pg_proc.proargtypes).  In these
-cases, the references may be explicitly set by use of the "OID ="
-clause of the .bki insert statement.  If no such pointers are required
-to a given tuple, then the OID may be set to the wildcard value 0
+of cross-references from other pre-loaded tuples.  For example, pg_type
+contains pointers into pg_proc (e.g., pg_type.typinput), and pg_proc
+contains back-pointers into pg_type (pg_proc.proargtypes).  For such
+cases, the OID assigned to a tuple may be explicitly set by use of the
+"OID =" clause of the .bki insert statement.  If no such pointers are
+required to a given tuple, then the OID may be set to the wildcard value 0
 (i.e., the system generates a random OID in the usual way, or leaves it
-0 in a catalog that has no OIDs).
+0 in a catalog that has no OIDs).  In practice we usually preassign OIDs
+for all or none of the pre-loaded tuples in a given catalog, even if only
+some of them are actually cross-referenced.
 
-If you need to find a valid OID for a set of tuples that refer to each
-other, use the unused_oids script.  It generates inclusive ranges of
-*unused* OIDs (i.e., the line "45-900" means OIDs 45 through 900 have
-not been allocated yet).  All OIDs that are known directly to C code 
-should be referenced via #defines in the catalog .h files. So 
-unused_oids is sufficient for assigning new OIDs.).  The unused_oids
-script simply 'discovers' those which are free.
+- We also sometimes preallocate OIDs for catalog tuples whose OIDs must
+be known directly in the C code.  In such cases, put a #define in the
+catalog's .h file, and use the #define symbol in the C code.  Writing
+the actual numeric value of any OID in C code is considered very bad form.
+(Direct references to pg_proc OIDs are common enough that there's a special
+mechanism to create the necessary #define's automatically.  For all the
+other system catalogs, you have to manually create any #define's you need.)
 
-- BOOTSTRAP tables must be at the start of the Makefile POSTGRES_BKI_SRCS
-variable, as these will not be created through standard function means, but
-will be written directly to disk.  Thats how pg_class is created without
-depending on functions which depend on the existance of pg_class.  The
-list of files this currently includes is:
-	pg_proc.h pg_type.h pg_attribute.h pg_class.h
+- If you need to find a valid OID for a tuple that will be referred to by
+others, use the unused_oids script.  It generates inclusive ranges of
+*unused* OIDs (i.e., the line "45-900" means OIDs 45 through 900 have
+not been allocated yet).  Currently, OIDs 1-9999 are reserved for manual
+assignment; the unused_oids script simply looks through the include/catalog
+headers to see which ones do not appear in "OID =" clauses.
 
-Don't forget to add the entry to heap.c to function heap_create() which
-sets the OID of the relation when it's a bootstrapped system table.  It's
-near the top of the function with the comment beginning in 'Real ugly stuff'
+- To create a "BOOTSTRAP" table you have to do a lot of extra work: these
+tables are not created through a normal CREATE TABLE operation, but spring
+into existence when first written to during initdb.  Therefore, you must
+manually create appropriate entries for them in the pre-loaded contents of
+pg_class, pg_attribute, and pg_type.  You'll also need to add code to function
+heap_create() in heap.c to force the correct OID to be assigned when the table
+is first referenced.  (It's near the top of the function with the comment
+beginning in 'Real ugly stuff'.)  Avoid making new catalogs be bootstrap
+catalogs if at all possible; generally, only tables that must be written to
+to create a table should be bootstrapped.
 
+- Certain BOOTSTRAP tables must be at the start of the Makefile
+POSTGRES_BKI_SRCS variable, as these will not be created through standard
+function means, but will be written directly to disk.  That's how pg_class is
+created without depending on functions which depend on the existence of
+pg_class.  The list of files this currently includes is:
+	pg_proc.h pg_type.h pg_attribute.h pg_class.h
+Also, indexing.h must be last, since the indexes can't be created until all
+the tables are in place.  There are reputedly some other order dependencies
+in the .bki list, too.
 
 -----------------------------------------------------------------